الاسم¶

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

المكتبة¶

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

موجز¶

#include <stdlib.h>

size_t mbstowcs(size_t dsize;
                wchar_t dest[restrict dsize], const char *restrict src,
                size_t dsize);

الوصف¶

إذا لم يكن dest NULL، فحوِّل سلسلة المحارف متعددة البايت src إلى سلسلة محارف عريضة تبدأ عند dest. يُكتب على الأكثر dsize حرفًا عريضًا إلى dest. يجب أن تبدأ سلسلة المحارف في src في حالة الإزاحة الأولية. يمكن أن يتوقف التحويل لثلاثة أسباب:

•

تمت مصادفة تسلسل متعدد البايت غير صالح. في هذه الحالة، تُعاد (size_t) -1.

•

خُزنت dsize من المحارف العريضة غير L'\0' عند dest. في هذه الحالة، يُعاد عدد المحارف العريضة المكتوبة إلى dest، لكن حالة الإزاحة عند هذه النقطة تُفقد.

•

حُوّلت سلسلة المحارف متعددة البايت بالكامل، بما في ذلك حرف النهاية الصفري ('\0'). في هذه الحالة، يُعاد عدد المحارف العريضة المكتوبة إلى dest، باستثناء حرف النهاية الصفري العريض.

إذا كان dest فارغا (NULL)، يُتجاهل dsize، ويستمر التحويل كما هو موضح أعلاه، باستثناء أن المحارف العريضة المحولة لا تُكتب في الذاكرة، ولا يوجد حد للطول.

لتجنب الحالة 2 أعلاه، يجب على المبرمج التأكد من أن dsize أكبر من أو يساوي mbstowcs(NULL,src,0)+1.

يجب على المبرمج التأكد من وجود مساحة لـ dsize من المحارف العريضة على الأقل في dest.

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

عدد المحارف العريضة التي تشكل الجزء المحول من سلسلة المحارف العريضة، دون تضمين حرف النهاية الصفري العريض. إذا تمت مصادفة تسلسل متعدد البايت غير صالح، تُعاد (size_t) -1.

السمات¶

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

الإصدارات¶

توفر الدالة mbsrtowcs(3) واجهة أفضل لنفس الوظيفة.

المعايير¶

C11, POSIX.1-2008.

التاريخ¶

POSIX.1-2001، C99.

ملاحظات¶

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

أمثلة¶

يوضح البرنامج أدناه استخدام mbstowcs()، بالإضافة إلى بعض دوال تصنيف المحارف العريضة. مثال على التشغيل هو التالي:

$ ./t_mbstowcs de_DE.UTF-8 Grüße!
Length of source string (excluding terminator):


    8 bytes


    6 multibyte characters
Wide character string is: Grüße! (6 characters)


    G alpha upper


    r alpha lower


    ü alpha lower


    ß alpha lower


    e alpha lower


    ! !alpha

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


    size_t mbslen;      /* Number of multibyte characters in source */


    wchar_t *wcs;       /* Pointer to converted wide character string */


    if (argc < 3) {


        fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    /* Apply the specified locale.  */


    if (setlocale(LC_ALL, argv[1]) == NULL) {


        perror("setlocale");


        exit(EXIT_FAILURE);


    }


    /* Calculate the length required to hold argv[2] converted to


       a wide character string.  */


    mbslen = mbstowcs(NULL, argv[2], 0);


    if (mbslen == (size_t) -1) {


        perror("mbstowcs");


        exit(EXIT_FAILURE);


    }


    /* Describe the source string to the user.  */


    printf("Length of source string (excluding terminator):\n");


    printf("    %zu bytes\n", strlen(argv[2]));


    printf("    %zu multibyte characters\n\n", mbslen);


    /* Allocate wide character string of the desired size.  Add 1


       to allow for terminating null wide character (L'\0').  */


    wcs = calloc(mbslen + 1, sizeof(*wcs));


    if (wcs == NULL) {


        perror("calloc");


        exit(EXIT_FAILURE);


    }


    /* Convert the multibyte character string in argv[2] to a


       wide character string.  */


    if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {


        perror("mbstowcs");


        exit(EXIT_FAILURE);


    }


    printf("Wide character string is: %ls (%zu characters)\n",


           wcs, mbslen);


    /* Now do some inspection of the classes of the characters in


       the wide character string.  */


    for (wchar_t *wp = wcs; *wp != 0; wp++) {


        printf("    %lc ", (wint_t) *wp);


        if (!iswalpha(*wp))


            printf("!");


        printf("alpha ");


        if (iswalpha(*wp)) {


            if (iswupper(*wp))


                printf("upper ");


            if (iswlower(*wp))


                printf("lower ");


        }


        putchar('\n');


    }


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)

ترجمة¶

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

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

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