الاسم¶

strtol, strtoll, strtoq - تحويل سلسلة محارف إلى عدد صحيح طويل

المكتبة¶

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

موجز¶

#include <stdlib.h>

long strtol(const char *restrict nptr,
            char **_Nullable restrict endptr, int base);
long long strtoll(const char *restrict nptr,
            char **_Nullable restrict endptr, int base);

strtoll():

    _ISOC99_SOURCE


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

الوصف¶

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

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

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

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

تعمل الدالة strtoll() تمامًا مثل الدالة strtol() ولكنها تُعيد قيمة عدد صحيح من نوع long long.

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

تُعيد الدالة strtol() نتيجة التحويل، إلا إذا كانت القيمة ستؤدي إلى تجاوز سفلي أو تجاوز علوي. إذا حدث تجاوز سفلي، تُعيد strtol() LONG_MIN. إذا حدث تجاوز علوي، تُعيد strtol() LONG_MAX. في كلتا الحالتين، يُضبط errno على ERANGE. ينطبق نفس الشيء تمامًا على strtoll() (مع LLONG_MIN وLLONG_MAX بدلاً من LONG_MIN وLONG_MAX).

الأخطاء¶

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

EINVAL

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

ERANGE

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

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

السمات¶

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

الإصدارات¶

وفقًا لـ POSIX.1، في الإعدادات المحلية غير "C" و"POSIX"، قد تقبل هذه الدوال سلاسل رقمية أخرى محددة بالتنفيذ.

يمتلك BSD أيضًا

quad_t strtoq(const char *nptr, char **endptr, int base);

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

المعايير¶

C23، ‏POSIX.1-2024.

التاريخ¶

strtol()

POSIX.1-2001، C89، SVr4، 4.3BSD.

strtoll()

POSIX.1-2001، C99.

"0b"، "0B"

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

تحذيرات¶

errno = 0;
n = strtol(s, &end, base);
if (end == s)
	goto no_number;
if ((errno == ERANGE && n == _Minof(long)) || n < min)
	goto too_low;
if ((errno == ERANGE && n == _Maxof(long)) || n > max)
	goto too_high;

errno = 0;
strtol("0", NULL, base);
if (errno == EINVAL)


    goto unsupported_base;

العلل¶

أمثلة¶

يُظهر البرنامج الموضح أدناه استخدام strtol(). يُحدد وسيط سطر الأوامر الأولى سلسلة محارف يجب أن تحلل منها strtol() رقمًا. يُحدد الوسيط الثاني (الاختياري) الأساس المستخدم للتحويل. (يُحوَّل هذا الوسيط إلى شكل رقمي باستخدام atoi(3)، وهي دالة لا تؤدي فحص الأخطاء ولها واجهة أبسط من strtol().) بعض الأمثلة على النتائج التي ينتجها هذا البرنامج هي التالية:

$ ./a.out 123
strtol() returned 123
$ ./a.out '    123'
strtol() returned 123
$ ./a.out 123abc
strtol() returned 123
Further characters after number: "abc"
$ ./a.out 123abc 55
strtol: Invalid argument
$ ./a.out ''
No digits were found
$ ./a.out 4000000000
strtol: Numerical result out of range

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{


    int base;


    char *endptr, *str;


    long val;


    if (argc < 2) {


        fprintf(stderr, "Usage: %s str [base]\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    str = argv[1];


    base = (argc > 2) ? atoi(argv[2]) : 0;


    errno = 0;    /* To distinguish success/failure after call */


    strtol("0", NULL, base);


    if (errno == EINVAL) {


        perror("strtol");


        exit(EXIT_FAILURE);


    }


    errno = 0;    /* To distinguish success/failure after call */


    val = strtol(str, &endptr, base);


    /* Check for various possible errors.  */


    if (errno == ERANGE) {


        perror("strtol");


        exit(EXIT_FAILURE);


    }


    if (endptr == str) {


        fprintf(stderr, "No digits were found\n");


        exit(EXIT_FAILURE);


    }


    /* If we got here, strtol() successfully parsed a number.  */


    printf("strtol() returned %ld\n", val);


    if (*endptr != '\0')        /* Not necessarily an error.  */


        printf("Further characters after number: \"%s\"\n", endptr);


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

atof(3), atoi(3), atol(3), strtod(3), strtoimax(3), strtoul(3)

ترجمة¶

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

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

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