strtok(3)

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

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

موجز
#include <string.h>

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

الوصف
الدالة 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() تُرجع مؤشرًا إلى الرمز التالي، أو NULL إذا لم تكن هناك رموز أخرى.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
strtok() | سلامة الخيوط | MT-Unsafe race:strtok

المعايير
C11, POSIX.1-2008.

التاريخ
POSIX.1-2001، C89، SVr4، 4.3BSD.

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

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

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

أمثلة
انظر getaddrinfo_a(3).

انظر أيضًا
memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3), strstr(3), strtok_r(3), wcstok(3)

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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