الاسم¶

mbrtowc - تحويل تسلسل متعدد البايت إلى محرف عريض

المكتبة¶

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

موجز¶

#include <wchar.h>

size_t mbrtowc(size_t n;
               wchar_t *restrict pwc, const char s[restrict n],
               size_t n, mbstate_t *restrict ps);

الوصف¶

الحالة الرئيسية لهذه الدالة هي عندما لا يكون s فارغًا ولا يكون pwc فارغًا. في هذه الحالة، تفحص الدالة mbrtowc() على الأكثر n بايت من السلسلة متعددة البايت بدءًا من s، وتستخرج المحرف متعدد البايت الكامل التالي، وتُحوّله إلى محرف عريض وتُخزّنه في *pwc. تُحدّث حالة الإزاحة *ps. إذا لم يكن المحرف العريض المُحوّل هو L'\0' (المحرف العريض الفارغ)، تُعيد عدد البايتات التي استُهلكت من s. إذا كان المحرف العريض المُحوّل هو L'\0'، تُعيد تعيين حالة الإزاحة *ps إلى الحالة الأولية وتُعيد 0.

إذا كانت البايتات n بدءًا من s لا تحتوي على محرف متعدد البايت كامل، تُعيد mbrtowc() (size_t) -2. يمكن أن يحدث هذا حتى لو كان n >= MB_CUR_MAX، إذا كانت السلسلة متعددة البايت تحتوي على تسلسلات إزاحة زائدة.

إذا كانت السلسلة متعددة البايت بدءًا من s تحتوي على تسلسل متعدد البايت غير صالح قبل المحرف الكامل التالي، تُعيد mbrtowc() (size_t) -1 وتُعيِّن errno إلى EILSEQ. في هذه الحالة، تكون التأثيرات على *ps غير مُعرَّفة.

حالة مختلفة هي عندما لا يكون s فارغًا ولكن pwc فارغ. في هذه الحالة، تتصرف الدالة mbrtowc() كما هو مذكور أعلاه، باستثناء أنها لا تُخزّن المحرف العريض المُحوّل في الذاكرة.

حالة ثالثة هي عندما يكون s فارغًا. في هذه الحالة، يُتجاهل pwc و n. إذا كانت حالة التحويل المُمثَّلة بـ *ps تُشير إلى تحويل محرف متعدد البايت غير مكتمل، تُعيد الدالة mbrtowc() (size_t) -1، وتُعيِّن errno إلى EILSEQ، وتترك *ps في حالة غير مُعرَّفة. خلاف ذلك، تضع الدالة mbrtowc() *ps في الحالة الأولية وتُعيد 0.

في جميع الحالات المذكورة أعلاه، إذا كان ps فارغًا، يُستخدم حالة مجهولة ثابتة معروفة فقط للدالة mbrtowc() بدلاً من ذلك. خلاف ذلك، يجب أن يكون *ps كائن mbstate_t صالحًا. يمكن تهيئة كائن mbstate_t a إلى الحالة الأولية بتصفيته، على سبيل المثال باستخدام

memset(&a, 0, sizeof(a));

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

تُعيد الدالة mbrtowc() عدد البايتات التي تم تحليلها من التسلسل متعدد البايت بدءًا من s، إذا تم التعرف على محرف عريض غير L'\0'. تُعيد 0، إذا تم التعرف على محرف عريض L'\0'. تُعيد (size_t) -1 وتُعيِّن errno إلى EILSEQ، إذا تم مواجهة تسلسل متعدد البايت غير صالح. تُعيد (size_t) -2 إذا كانت البايتات n المُستهلكة تُشكِّل تسلسل محرف جزئي صالح؛ يجب تغذية بيانات لاحقة إضافية.

السمات¶

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

المعايير¶

C11, POSIX.1-2008.

التاريخ¶

POSIX.1-2001، C99.

ملاحظات¶

يعتمد سلوك mbrtowc() على فئة LC_CTYPE من الإعدادات المحلية الحالية.

انظر أيضًا¶

mbsinit(3), mbsrtowcs(3)

ترجمة¶

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

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

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