strtol(3)

الاسم
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);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

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).
الواجهة | السمة | القيمة
strtol(), strtoll(), strtoq() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe)

الإصدارات
وفقًا لـ 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.)

تحذيرات

  فحوصات النطاق
نظرًا لأن strtol() يمكنها قانونيًا إرجاع 0 أو LONG_MAX أو LONG_MIN (LLONG_MAX أو LLONG_MIN لـ strtoll()) في كل من النجاح والفشل، يجب على البرنامج المستدعي ضبط errno على 0 قبل الاستدعاء، ثم تحديد ما إذا حدث خطأ بالتحقق مما إذا كان errno == ERANGE بعد الاستدعاء.

    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;

  base
إذا كان base بحاجة إلى الاختبار، فيجب اختباره في استدعاء حيث من المعروف أن السلسلة ستنجح. وإلا، فمن المستحيل التمييز بين الأخطاء بشكل محمول.

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

العلل

  مساحة فارغة
تقبل هذه الدوال المسافات البيضاء البادئة بصمت. لرفض المسافات البيضاء، استدع isspace(3) قبل strtol().

أمثلة
يُظهر البرنامج الموضح أدناه استخدام 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 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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