الاسم¶

strtoul, strtoull, strtouq - تحويل سلسلة محارف إلى عدد صحيح طويل غير مُوقَّع

المكتبة¶

مكتبة سي المعيارية (libc، -lc)

موجز¶

#include <stdlib.h>

unsigned long strtoul(const char *restrict nptr,
                      char **_Nullable restrict endptr, int base);
unsigned long long strtoull(const char *restrict nptr,
                      char **_Nullable restrict endptr, int base);

strtoull():

    _ISOC99_SOURCE


        || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

الوصف¶

الدالة strtoul() تُحوِّل الجزء الأولي من السلسلة في nptr إلى قيمة unsigned long وفقًا لـ base المُعطى، والذي يجب أن يكون بين 2 و36 شاملاً، أو أن يكون القيمة الخاصة 0.

قد تبدأ السلسلة بكمية اختيارية من المسافات البيضاء (كما يحددها isspace(3)) تليها علامة '+' أو '-' اختيارية واحدة. إذا كانت base صفرًا أو 16، فقد تتضمن السلسلة بادئة "0x" أو "0X"، وسيُقرأ الرقم بالأساس 16؛ أما إذا كانت base صفرًا أو 2، فقد تتضمن السلسلة بادئة "0b" أو "0B"، وسيُقرأ الرقم بالأساس 2؛ وخلاف ذلك، تُتخذ base الصفرية على أنها 10 (عشري) ما لم يكن المحرف التالي هو '0'، وفي هذه الحالة تُتخذ على أنها 8 (ثماني).

يُحوَّل باقي السلسلة إلى قيمة unsigned long بالطريقة الواضحة، ويتوقف عند أول حرف ليس رقمًا صالحًا في الأساس المُعطى. (في الأساسات فوق 10، الحرف 'A' سواء كان كبيرًا أو صغيرًا يُمثل 10، و'B' يُمثل 11، وهكذا، مع 'Z' الذي يُمثل 35.)

إذا كان endptr ليس NULL، وكان base مدعومًا، تخزِّن strtoul() عنوان أول حرف غير صالح في *endptr. إذا لم تكن هناك أرقام على الإطلاق، تخزِّن strtoul() القيمة الأصلية لـ nptr في *endptr (وتُعيد 0). على وجه الخصوص، إذا كان *nptr ليس '\0' ولكن **endptr هو '\0' عند الإرجاع، فإن السلسلة بأكملها صالحة.

تعمل الدالة strtoull() تمامًا مثل الدالة strtoul() ولكنها تُعيد قيمة unsigned long long.

قيمة الإرجاع¶

تُعيد الدالة strtoul() إما نتيجة التحويل، أو إذا كانت هناك علامة ناقص بادئة، نفي نتيجة التحويل المُمثَّلة كقيمة غير مُوقَّعة، ما لم تكن القيمة الأصلية (غير المنفية) ستفيض؛ في الحالة الأخيرة، تُعيد strtoul() ULONG_MAX وتضبط errno على ERANGE. ينطبق نفس الشيء تمامًا على strtoull() (مع ULLONG_MAX بدلاً من ULONG_MAX).

الأخطاء¶

لا تعدل هذه الدالة errno عند النجاح.

EINVAL

(ليس في C99) يحتوي الأساس المعطى على قيمة غير مدعومة.

ERANGE

القيمة الناتجة كانت خارج النطاق.

قد يقوم التنفيذ أيضًا بضبط errno على EINVAL في حالة عدم إجراء أي تحويل (لم تُرَ أي أرقام، وأُرْجِعَ 0).

السمات¶

للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).

الإصدارات¶

في الإعدادات المحلية غير الإعداد "C"، قد تُقبل سلاسل أخرى. (على سبيل المثال، قد يكون فاصل الآلاف للإعداد المحلي الحالي مدعومًا.)

يمتلك BSD أيضًا

u_quad_t strtouq(const char *nptr, char **endptr, int base);

بتعريف مشابه تمامًا. اعتمادًا على حجم الكلمة في البنية الحالية، قد يكون هذا مكافئًا لـ strtoull() أو لـ strtoul().

المعايير¶

C23، ‏POSIX.1-2024.

التاريخ¶

strtoul()

POSIX.1-2001, C89, SVr4.

strtoull()

POSIX.1-2001، C99.

"0b"، "0B"

C23. glibc 2.38. (ليس في POSIX.)

تحذيرات¶

نظرًا لأن strtoul() يمكنها شرعيًا إرجاع 0 أو ULONG_MAX (ULLONG_MAX لـ strtoull()) في كل من النجاح والفشل، يجب على البرنامج المُستدعي ضبط errno على 0 قبل الاستدعاء، ثم تحديد ما إذا حدث خطأ بالتحقق مما إذا كان errno له قيمة غير صفرية بعد الاستدعاء.

العلل¶

أمثلة¶

انظر المثال في صفحة دليل strtol(3)؛ استخدام الدوال الموصوفة في صفحة الدليل هذه مشابه.

انظر أيضًا¶

a64l(3), atof(3), atoi(3), atol(3), strtod(3), strtol(3), strtoumax(3)

ترجمة¶

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.