الاسم¶

strtok, strtok_r - استخراج الرموز من السلاسل

المكتبة¶

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

موجز¶

#include <string.h>

char *strtok(char *_Nullable restrict str, const char *restrict delim);
char *strtok_r(char *_Nullable restrict str, const char *restrict delim,
               char **restrict saveptr);

strtok_r():

    _POSIX_C_SOURCE


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

الوصف¶

الدالة strtok() تقسم سلسلة محارف إلى تسلسل من صفر أو أكثر من الرموز غير الفارغة. في الاستدعاء الأول لـ strtok()، يجب تحديد السلسلة المراد تحليلها في str. في كل استدعاء لاحق يجب أن يحلل نفس السلسلة، يجب أن يكون str NULL.

الوسيط delim يحدد مجموعة من البايتات التي تفصل الرموز في السلسلة المحللة. قد يحدد المستدعي سلاسل مختلفة في delim في استدعاءات متتالية تحلل نفس السلسلة.

كل استدعاء لـ strtok() يُرجع مؤشرًا إلى سلسلة محارف منتهية بقيمة خالية تحتوي على الرمز التالي. هذه السلسلة لا تتضمن البايت الفاصل. إذا لم يتم العثور على المزيد من الرموز، تُرجع strtok() NULL.

تسلسل من الاستدعاءات لـ strtok() التي تعمل على نفس السلسلة يحافظ على مؤشر يحدد النقطة التي يبدأ منها البحث عن الرمز التالي. الاستدعاء الأول لـ strtok() يضبط هذا المؤشر ليشير إلى أول بايت من السلسلة. يتم تحديد بداية الرمز التالي بالمسح للأمام بحثًا عن البايت غير الفاصل التالي في str. إذا تم العثور على مثل هذا البايت، يُعتبر بداية الرمز التالي. إذا لم يتم العثور على مثل هذا البايت، فلا توجد رموز أخرى، وتُرجع strtok() NULL. (سلسلة فارغة أو تحتوي فقط على فواصل ستتسبب في إرجاع strtok() NULL في الاستدعاء الأول.)

يتم العثور على نهاية كل رمز بالمسح للأمام حتى يتم العثور على البايت الفاصل التالي أو حتى يتم مواجهة البايت الختامي الصفري ('\0'). إذا تم العثور على بايت فاصل، يُستبدل ببايت صفري لإنهاء الرمز الحالي، وتحفظ strtok() مؤشرًا إلى البايت التالي؛ سيُستخدم هذا المؤشر كنقطة بداية عند البحث عن الرمز التالي. في هذه الحالة، تُرجع strtok() مؤشرًا إلى بداية الرمز الذي تم العثور عليه.

من الوصف أعلاه، يتبع ذلك أن تسلسلًا من بايتين فاصلين متجاورين أو أكثر في السلسلة المحللة يُعتبر فاصلًا واحدًا، وأن البايتات الفاصلة في بداية أو نهاية السلسلة تُتجاهل. بعبارة أخرى: الرموز التي تُرجعها strtok() هي دائمًا سلاسل غير فارغة. وبالتالي، على سبيل المثال، بالنظر إلى السلسلة "aaa;;bbb,"، فإن الاستدعاءات المتتالية لـ strtok() التي تحدد سلسلة الفاصل ";," سترجع السلاسل "aaa" و "bbb"، ثم مؤشرًا فارغًا.

الدالة strtok_r() هي نسخة قابلة لإعادة الدخول من strtok(). المعامل saveptr هو مؤشر لمتغير من نوع char * يُستخدم داخليًا بواسطة strtok_r() للحفاظ على السياق بين الاستدعاءات المتتالية التي تحلل نفس السلسلة.

في أول استدعاء لـ strtok_r()، يجب أن يشير str إلى السلسلة المراد تحليلها، ويُتجاهل قيمة *saveptr (لكن انظر الإصدارات). في الاستدعاءات اللاحقة، يجب أن يكون str NULL، ويجب أن يبقى saveptr (والمخزن المؤقت الذي يشير إليه) دون تغيير منذ الاستدعاء السابق.

يمكن تحليل سلاسل مختلفة بشكل متزامن باستخدام تسلسلات من الاستدعاءات لـ strtok_r() تحدد معاملات saveptr مختلفة.

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

ترجع الدالتان strtok() و strtok_r() مؤشرًا إلى الرمز التالي، أو NULL إذا لم تكن هناك رموز أخرى.

السمات¶

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

الإصدارات¶

في بعض التطبيقات، يُطلب أن يكون *saveptr NULL في أول استدعاء لـ strtok_r() يُستخدم لتحليل str.

المعايير¶

strtok()

C11, POSIX.1-2008.

strtok_r()

POSIX.1-2008.

التاريخ¶

strtok()

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

strtok_r()

POSIX.1-2001.

العلل¶

كن حذرًا عند استخدام هذه الدوال. إذا استخدمتها، فلاحظ أن:

•

هذه الدوال تُعدل معاملها الأول.

•

لا يمكن استخدام هذه الدوال على السلاسل الثابتة.

•

يُفقد هوية البايت الفاصل.

•

تستخدم الدالة strtok() مخزنًا مؤقتًا ثابتًا أثناء التحليل، لذا فهي غير آمنة للخيوط. استخدم strtok_r() إذا كان هذا مهمًا لك.

أمثلة¶

يستخدم البرنامج أدناه حلقات متداخلة توظف strtok_r() لتقسيم سلسلة إلى تسلسل هرمي ذي مستويين من الرموز. تحدد وسيطة سطر الأوامر الأولى السلسلة المراد تحليلها. تحدد الوسيطة الثانية بايت (بايتات) المحدد المستخدمة لفصل تلك السلسلة إلى رموز "رئيسية". تحدد الوسيطة الثالثة بايت (بايتات) المحدد المستخدمة لفصل الرموز "الرئيسية" إلى رموز فرعية.

مثال على المخرجات التي ينتجها هذا البرنامج هو التالي:

$ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
1: a/bbb///cc


         --> a


         --> bbb


         --> cc
2: xxx


         --> xxx
3: yyy


         --> yyy

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


    char *str1, *str2, *token, *subtoken;


    char *saveptr1, *saveptr2;


    int j;


    if (argc != 4) {


        fprintf(stderr, "Usage: %s string delim subdelim\n",


                argv[0]);


        exit(EXIT_FAILURE);


    }


    for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {


        token = strtok_r(str1, argv[2], &saveptr1);


        if (token == NULL)


            break;


        printf("%d: %s\n", j, token);


        for (str2 = token; ; str2 = NULL) {


            subtoken = strtok_r(str2, argv[3], &saveptr2);


            if (subtoken == NULL)


                break;


            printf("\t --> %s\n", subtoken);


        }


    }


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3), strstr(3), wcstok(3)

ترجمة¶

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

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

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