الاسم¶

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)) متبوعًا بإشارة اختيارية مفردة '+' أو '-'. إذا كان الأساس صفرًا أو 16، فقد تتضمن السلسلة بعد ذلك بادئة "0x"، ويُقرأ الرقم بالأساس 16؛ وإلا، يُؤخذ الأساس الصفري على أنه 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().

المعايير¶

C11, POSIX.1-2008.

التاريخ¶

strtoul()

POSIX.1-2001, C89, SVr4.

strtoull()

POSIX.1-2001، C99.

تحذيرات¶

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

تُعتبر القيم السالبة مدخلات صالحة وتُحوّل بصمت إلى قيمة unsigned long المكافئة.

أمثلة¶

انظر المثال في صفحة دليل 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.