من نص إلى عدد في لغة C: atoi وstrtol وتحويل الأعداد إلى نص

يصل النص من المستخدمين والملفات وسطر الأوامر على هيئة محارف. فـ "42" ثلاثة بايتات - '4' و'2' و'\0' - ولا شيء فيها هو العدد 42 حتى تحوّله. وتقدّم C جيلين من دوال التحويل: القصيرة القديمة التي لا تستطيع الإبلاغ عن الأخطاء، والأطول التي تستطيع. تعرض هذه الصفحة كليهما وتشرح لماذا تستخدم البرامج الحقيقية المجموعة الثانية.

العائلة القديمة: atoi وatol وatof

تُقرأ كأسمائها: من ASCII إلى int، وإلى long، وإلى double. وسيط واحد ونتيجة واحدة.

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    printf("%d\n", atoi("42"));
    printf("%d\n", atoi("  -17 trailing junk"));
    printf("%f\n", atof("3.14"));
    return 0;
}

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

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    printf("atoi(\"0\")     = %d\n", atoi("0"));
    printf("atoi(\"hello\") = %d\n", atoi("hello"));
    printf("atoi(\"\")      = %d\n", atoi(""));
    return 0;
}

تطبع الثلاثة كلها 0. فلا رمز إرجاع ولا راية ولا وسيلة للسؤال "هل نجح ذلك؟" - وقيمة تفيض عن int سلوك غير معرَّف لا خطأ مُبلَّغ عنه. ولثابت نصّي كتبته بنفسك في برنامج تجريبي هذا محتمل. أما لأي شيء يستطيع شخص أو ملف توفيره، فهو مولّد أخطاء صامتة.

الأداة الصحيحة: strtol

strtol (من سلسلة إلى long) هي التحويل نفسه مع قناتين للإبلاغ عمّا حدث.

long strtol(const char *text, char **endptr, int base);

تُضبَط endptr على أول محرف لم تستهلكه الدالة. وbase هو أساس العدد - استخدم 10، أو 0 لتدع بادئة الثابت تقرّر (0x للست عشري، وصفر بادئ للثماني).

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *input = "42 apples";
    char *end;

    long value = strtol(input, &end, 10);

    printf("value = %ld\n", value);
    printf("stopped at: \"%s\"\n", end);
    printf("consumed %td characters\n", end - input);
    return 0;
}

وقراءة endptr تجيب عن الأسئلة التي لا تستطيع atoi الإجابة عنها:

• end == input تعني أنه لم يُحوَّل شيء - فالنص لم يبدأ بعدد.
• *end != '\0' تعني وجود محتوى لاحق. وكون ذلك خطأً قرارك: فهو مقبول عند تحليل "42 apples"، ومشكلة حين كان ينبغي أن يكون السطر كله عددًا.

ويُبلَّغ عن الفيضان منفصلًا عبر errno. والاصطلاح الكامل الصحيح يستحق أن يُكتب مرة ويُعاد استخدامه:

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <limits.h>

/* تُرجِع 1 عند النجاح، و0 عند أي نوع من الفشل */
int parse_int(const char *text, int *out) {
    char *end;
    errno = 0;

    long value = strtol(text, &end, 10);

    if (end == text) {
        return 0;                 /* لا أرقام إطلاقًا */
    }
    if (*end != '\0') {
        return 0;                 /* مخلّفات لاحقة */
    }
    if (errno == ERANGE || value < INT_MIN || value > INT_MAX) {
        return 0;                 /* خارج مدى int */
    }

    *out = (int)value;
    return 1;
}

int main(void) {
    const char *tests[] = {"42", "-7", "hello", "", "9999999999", "12abc"};
    int n = (int)(sizeof tests / sizeof tests[0]);

    for (int i = 0; i < n; i++) {
        int value;
        if (parse_int(tests[i], &value)) {
            printf("\"%s\" -> %d\n", tests[i], value);
        } else {
            printf("\"%s\" -> rejected\n", tests[i]);
        }
    }
    return 0;
}

ثلاثة تفاصيل تجعل هذا صحيحًا. errno = 0 قبل الاستدعاء تهمّ لأن المكتبة لا تضبط errno إلا ضبطًا؛ ولا تمسحها أبدًا، فقيمة قديمة من استدعاء سابق ستُقرأ على أنها فشل هذا الاستدعاء. وتُرجِع strtol نوع long، الذي قد يكون أوسع من int، ففحص المدى مقابل INT_MIN/INT_MAX منفصل عن ERANGE. وإرجاع النجاح كحالة مع تسليم القيمة عبر مؤشّر هو كيف تبلّغ دوال C عن "إما قيمة وإما فشل" - فالقيمة المُرجَعة لا تستطيع أداء المهمّتين.

وstrtoul هي النظير غير الموقّع، وstrtoll/strtoull تتوليان long long.

أسس أخرى

يقرأ الأساس 16 ست عشريًا؛ ويفحص الأساس 0 البادئةَ ويقرّر بنفسه.

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    char *end;

    printf("%ld\n", strtol("ff", &end, 16));      /* 255 */
    printf("%ld\n", strtol("0x1A", &end, 0));     /* 26، اكتُشفت البادئة */
    printf("%ld\n", strtol("1011", &end, 2));     /* 11، ثنائي */
    printf("%ld\n", strtol("755", &end, 8));      /* 493، ثماني */
    return 0;
}

والأساس 0 فخّ في حالة واحدة بعينها: فعدد عشري محشوّ بصفر مثل "012" يُقرأ ثمانيًا ويخرج 10. فإن كان إدخالك عشريًا، فاكتب 10 صراحةً.

الفاصلة العائمة: strtod

strtod لها الشكل نفسه لأجل double، ولـ atof العيب نفسه الذي لـ atoi.

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>

int main(void) {
    const char *text = "3.14159 rest";
    char *end;
    errno = 0;

    double value = strtod(text, &end);

    if (end == text) {
        printf("not a number\n");
    } else if (errno == ERANGE) {
        printf("out of range\n");
    } else {
        printf("value = %f, stopped at \"%s\"\n", value, end);
    }
    return 0;
}

وتقبل strtod أيضًا الترميز العلمي ("1.5e3")، والأعداد العشرية الست عشرية، والكلمتين "inf" و"nan". وتؤثّر الإعدادات المحلّية في فاصل الكسر العشري، وهو ما يفاجئ من يحلّلون ملفات كُتبت في مكان آخر - وفي الإعداد المحلّي الافتراضي "C" يكون الفاصل نقطة دائمًا.

من الأعداد إلى النص: snprintf

في الاتجاه الآخر، snprintf هي الإجابة المعيارية. تكتب على الأكثر بالحجم الذي تعطيه إياها، وتنهي السلسلة دائمًا، وتُرجِع الطول الذي كانت ستحتاجه النتيجة الكاملة.

#include <stdio.h>

int main(void) {
    char buf[32];
    int n = 4095;

    int written = snprintf(buf, sizeof buf, "%d", n);
    printf("text: \"%s\" (needed %d chars)\n", buf, written);

    snprintf(buf, sizeof buf, "%05d", n);
    printf("padded: %s\n", buf);

    snprintf(buf, sizeof buf, "%x / %o / %.2f", n, n, n / 1000.0);
    printf("mixed:  %s\n", buf);
    return 0;
}

والقيمة المُرجَعة هي فحص الاقتطاع. فإن كانت أكبر من حجم المخزن أو مساوية له، فالنص لم يتّسع:

#include <stdio.h>

int main(void) {
    char small[8];

    int needed = snprintf(small, sizeof small, "value=%d", 1234567);

    if (needed < 0) {
        printf("encoding error\n");
    } else if ((size_t)needed >= sizeof small) {
        printf("truncated: \"%s\" (needed %d bytes)\n", small, needed + 1);
    } else {
        printf("ok: %s\n", small);
    }
    return 0;
}

وشيئان لا تلجأ إليهما: itoa ليست جزءًا من C المعيارية، فالشيفرة التي تستخدمها لن تُترجَم في كل مكان؛ وsprintf هي snprintf بلا حدّ حجم، ما يعني أنها ستكتب بعد نهاية مخزنك دون اعتراض.

المحارف المفردة و'0'

محارف الأرقام من '0' إلى '9' مضمون أنها متتالية، فالطرح البسيط يحوّل بين محرف رقم وقيمته.

#include <stdio.h>
#include <ctype.h>

int main(void) {
    char c = '7';
    int digit = c - '0';
    printf("char '%c' -> int %d\n", c, digit);

    int value = 3;
    char back = (char)(value + '0');
    printf("int %d -> char '%c'\n", value, back);
    return 0;
}

والأرقام وحدها تتصرّف هكذا - فليس مطلوبًا أن تكون الحروف متتالية، فـ c - 'a' غير قابلة للنقل لحسابات الأبجدية. واحرس الطرح بـ isdigit قبل الوثوق به:

#include <stdio.h>
#include <ctype.h>

int main(void) {
    char text[] = "a1b2c3";
    int sum = 0;

    for (int i = 0; text[i] != '\0'; i++) {
        if (isdigit((unsigned char)text[i])) {
            sum += text[i] - '0';
        }
    }

    printf("digits sum to %d\n", sum);
    return 0;
}

والتحويل إلى unsigned char مطلوب للسبب نفسه المذكور في السلاسل النصية: فدوال <ctype.h> غير معرَّفة للوسائط السالبة، وchar العادي قد يكون موقّعًا.

أي دالة تستخدم

• نصّ من مستخدم أو ملف أو argv ← strtol / strtod مع الفحص الكامل.
• ثابت نصّي كتبته بنفسك وتتحكّم فيه ← atoi مقبولة، وإن لم تكن لافتة.
• عدد إلى مخزن ← snprintf، وافحص القيمة المُرجَعة.
• محرف رقم واحد ← اطرح '0' بعد isdigit.
• أبدًا ← gets وsprintf وitoa.