strftime(3)

الاسم
strftime - تنسيق التاريخ والوقت

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

موجز
#include <time.h>

size_t strftime(size_t max;
                char s[restrict max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm);

size_t strftime_l(size_t max;
                char s[restrict max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm,
                locale_t locale);

الوصف
الدالة strftime() تُنسّق الوقت المفصل tm وفقًا لمواصفات التنسيق format وتضع النتيجة في مصفوفة المحارف s بحجم max. بنية الوقت المفصل tm مُعرّفة في <time.h>. انظر أيضًا ctime(3).

مواصفات التنسيق هي سلسلة محارف منتهية بقيمة خالية وقد تحتوي على تسلسلات محارف خاصة تُسمى مواصفات التحويل، كل منها يُقدّم بحرف '%' ويُنهى بحرف آخر يُعرف باسم حرف محدد التحويل. جميع تسلسلات المحارف الأخرى هي تسلسلات محارف عادية.

محارف تسلسلات المحارف العادية (بما في ذلك البايت الخالي) تُنسخ حرفيًا من format إلى s. ومع ذلك، محارف مواصفات التحويل تُستبدل كما هو موضح في القائمة أدناه. في هذه القائمة، الحقل (الحقول) المستخدم من بنية tm يُعرض أيضًا.

%a  الاسم المختصر ليوم الأسبوع وفقًا للإعدادات المحلية الحالية. (مُحسوب من tm_wday.) (الأسماء المحددة المستخدمة في الإعدادات المحلية الحالية يمكن الحصول عليها باستدعاء nl_langinfo(3) مع ABDAY_{1–7} كمعامل.)

%A  الاسم الكامل ليوم الأسبوع وفقًا للإعدادات المحلية الحالية. (مُحسوب من tm_wday.) (الأسماء المحددة المستخدمة في الإعدادات المحلية الحالية يمكن الحصول عليها باستدعاء nl_langinfo(3) مع DAY_{1–7} كمعامل.)

%b  اسم الشهر المختصر وفقًا للإعدادات المحلية الحالية. (مُحسوب من tm_mon.) (الأسماء المحددة المستخدمة في الإعدادات المحلية الحالية يمكن الحصول عليها باستدعاء nl_langinfo(3) مع ABMON_{1–12} كمعامل.)

%B  اسم الشهر الكامل وفقًا للإعدادات المحلية الحالية. (مُحسوب من tm_mon.) (الأسماء المحددة المستخدمة في الإعدادات المحلية الحالية يمكن الحصول عليها باستدعاء nl_langinfo(3) مع MON_{1–12} كمعامل.)

%c  تمثيل التاريخ والوقت المفضل للإعدادات المحلية الحالية. (التنسيق المحدد المستخدم في الإعدادات المحلية الحالية يمكن الحصول عليه باستدعاء nl_langinfo(3) مع D_T_FMT كمعامل لمواصفة التحويل %c، ومع ERA_D_T_FMT لمواصفة التحويل %Ec.) (في الإعدادات المحلية POSIX هذا مكافئ لـ %a %b %e %H:%M:%S %Y.)

%C  رقم القرن (السنة/100) كعدد صحيح مكون من رقمين. (SU) (مواصفة التحويل %EC تتوافق مع اسم العصر.) (مُحسوب من tm_year.)

%d  يوم الشهر كعدد عشري (نطاق 01 إلى 31). (مُحسوب من tm_mday.)

%D  مكافئ لـ %m/%d/%y. (إيخ—للأمريكيين فقط. يجب على الأمريكيين ملاحظة أنه في البلدان الأخرى %d/%m/%y شائع إلى حد ما. هذا يعني أنه في السياق الدولي هذا التنسيق غامض ولا ينبغي استخدامه.) (SU)

%e  مثل %d، يوم الشهر كعدد عشري، ولكن الصفر البادئ يُستبدل بمسافة. (SU) (مُحسوب من tm_mday.)

%E  مُعدّل: استخدم تنسيقًا بديلًا ("قائم على العصر")؛ انظر أدناه. (SU)

%F  مكافئ لـ %Y-%m-%d (تنسيق التاريخ ISO 8601). (C99)

%G  السنة القائمة على الأسبوع وفق ISO 8601 (انظر الملاحظات) مع القرن كرقم عشري. السنة المكونة من 4 أرقام المقابلة لرقم الأسبوع ISO (انظر %V). لها نفس التنسيق والقيمة مثل %Y، باستثناء أنه إذا كان رقم الأسبوع ISO ينتمي إلى السنة السابقة أو التالية، تُستخدم تلك السنة بدلاً من ذلك. (TZ) (محسوبة من tm_year و tm_yday و tm_wday.)

%g  مثل %G، ولكن بدون القرن، أي بسنة مكونة من رقمين (00–99). (TZ) (محسوبة من tm_year و tm_yday و tm_wday.)

%h  مكافئ لـ %b. (SU)

%H  الساعة كرقم عشري باستخدام ساعة 24 ساعة (النطاق 00 إلى 23). (محسوبة من tm_hour.)

%I  الساعة كرقم عشري باستخدام ساعة 12 ساعة (النطاق 01 إلى 12). (محسوبة من tm_hour.)

%j  يوم السنة كرقم عشري (النطاق 001 إلى 366). (محسوب من tm_yday.)

%k  الساعة (ساعة 24 ساعة) كرقم عشري (النطاق 0 إلى 23)؛ الأرقام المفردة يسبقها فراغ. (انظر أيضًا %H.) (محسوبة من tm_hour.) (TZ)

%l  الساعة (ساعة 12 ساعة) كرقم عشري (النطاق 1 إلى 12)؛ الأرقام المفردة يسبقها فراغ. (انظر أيضًا %I.) (محسوبة من tm_hour.) (TZ)

%m  الشهر كرقم عشري (النطاق 01 إلى 12). (محسوب من tm_mon.)

%M  الدقيقة كرقم عشري (النطاق 00 إلى 59). (محسوبة من tm_min.)

%n  حرف سطر جديد. (SU)

%O  مُعدِّل: استخدم رموزًا رقمية بديلة؛ انظر أدناه. (SU)

%p  إما "AM" أو "PM" وفقًا لقيمة الوقت المعطاة، أو السلاسل المحارف المقابلة للإعدادات المحلية الحالية. يُعامل الظهيرة كـ "PM" ومنتصف الليل كـ "AM". (محسوبة من tm_hour.) (يمكن الحصول على تمثيلات السلاسل المحارف المحددة المستخدمة لـ "AM" و "PM" في الإعدادات المحلية الحالية باستدعاء nl_langinfo(3) مع AM_STR و PM_STR، على التوالي.)

%P  مثل %p ولكن بأحرف صغيرة: "am" أو "pm" أو سلسلة محارف مقابلة للإعدادات المحلية الحالية. (محسوبة من tm_hour.) (GNU)

%r  الوقت بترميز a.m. أو p.m.. (SU) (يمكن الحصول على التنسيق المحدد المستخدم في الإعدادات المحلية الحالية باستدعاء nl_langinfo(3) مع T_FMT_AMPM كمعامل.) (في الإعدادات المحلية POSIX هذا مكافئ لـ %I:%M:%S %p.)

%R  الوقت بترميز 24 ساعة (%H:%M). (SU) للحصول على نسخة تتضمن الثواني، انظر %T أدناه.

%s  عدد الثواني منذ الحقبة، 1970-01-01 00:00:00 +0000 (UTC). (TZ) (محسوب من mktime(tm).)

%S  الثانية كرقم عشري (النطاق 00 إلى 60). (النطاق يصل إلى 60 للسماح بالثواني الكبيسة العرضية.) (محسوبة من tm_sec.)

%t  حرف جدولة. (SU)

%T  الوقت بترميز 24 ساعة (%H:%M:%S). (SU)

%u  يوم الأسبوع كعدد عشري، النطاق 1 إلى 7، الاثنين هو 1. انظر أيضًا %w. (محسوب من tm_wday.) (SU)

%U  رقم الأسبوع من السنة الحالية كعدد عشري، النطاق 00 إلى 53، يبدأ بأول يوم أحد كأول يوم في الأسبوع 01. انظر أيضًا %V و %W. (محسوب من tm_yday و tm_wday.)

%V  رقم الأسبوع وفق ISO 8601 (انظر الملاحظات) من السنة الحالية كعدد عشري، النطاق 01 إلى 53، حيث الأسبوع 1 هو أول أسبوع يحتوي على 4 أيام على الأقل في السنة الجديدة. انظر أيضًا %U و %W. (محسوب من tm_year و tm_yday و tm_wday.) (SU)

%w  يوم الأسبوع كعدد عشري، النطاق 0 إلى 6، الأحد هو 0. انظر أيضًا %u. (محسوب من tm_wday.)

%W  رقم الأسبوع من السنة الحالية كعدد عشري، النطاق 00 إلى 53، يبدأ بأول يوم اثنين كأول يوم في الأسبوع 01. (محسوب من tm_yday و tm_wday.)

%x  تمثيل التاريخ المفضل للإعدادات المحلية الحالية دون الوقت. (يمكن الحصول على التنسيق المحدد المستخدم في الإعدادات المحلية الحالية باستدعاء nl_langinfo(3) مع D_FMT كمعامل لمواصفات التحويل %x، ومع ERA_D_FMT لمواصفات التحويل %Ex.) (في الإعدادات المحلية POSIX هذا مكافئ لـ %m/%d/%y.)

%X  تمثيل الوقت المفضل للإعدادات المحلية الحالية دون التاريخ. (يمكن الحصول على التنسيق المحدد المستخدم في الإعدادات المحلية الحالية باستدعاء nl_langinfo(3) مع T_FMT كمعامل لمواصفات التحويل %X، ومع ERA_T_FMT لمواصفات التحويل %EX.) (في الإعدادات المحلية POSIX هذا مكافئ لـ %H:%M:%S.)

%y  السنة كعدد عشري بدون قرن (النطاق 00 إلى 99). (مواصفات التحويل %Ey تتوافق مع السنة منذ بداية العصر المشار إليه بمواصفات التحويل %EC.) (محسوب من tm_year)

%Y  السنة كعدد عشري شامل القرن. (مواصفات التحويل %EY تتوافق مع تمثيل السنة البديل الكامل.) (محسوب من tm_year)

%z  المنطقة الزمنية الرقمية +hhmm أو -hhmm (أي إزاحة الساعة والدقيقة من UTC). (SU)

%Z  اسم المنطقة الزمنية أو اختصارها.

%+  التاريخ والوقت بتنسيق date(1). (TZ) (غير مدعوم في glibc2.)

%%  حرف '%' حرفي.

يمكن تعديل بعض مواصفات التحويل بوضع المُعدِّل E أو O المُعدِّل قبل حرف محدد التحويل للإشارة إلى استخدام تنسيق بديل. إذا لم يكن التنسيق أو المواصفات البديلة موجودة للإعدادات المحلية الحالية، سيكون السلوك كما لو تم استخدام مواصفات التحويل غير المعدلة. (SU) تذكر مواصفات UNIX الموحدة %Ec و %EC و %Ex و %EX و %Ey و %EY و %Od و %Oe و %OH و %OI و %Om و %OM و %OS و %Ou و %OU و %OV و %Ow و %OW و %Oy، حيث تأثير المُعدِّل O هو استخدام رموز عددية بديلة (مثل الأرقام الرومانية)، وتأثير المُعدِّل E هو استخدام تمثيل بديل يعتمد على الإعدادات المحلية. يمكن الحصول على القواعد التي تحكم تمثيل التاريخ مع المُعدِّل E بتزويد ERA كمعامل لـ nl_langinfo(3). أحد الأمثلة على هذه الأشكال البديلة هو نظام التقويم الياباني في الإعدادات المحلية ja_JP في glibc.

strftime_l() مكافئ لـ strftime()، باستثناء أنه يستخدم الإعدادات المحلية المحددة بدلاً من الإعدادات المحلية الحالية. السلوك غير محدد إذا كانت الإعدادات المحلية غير صالحة أو LC_GLOBAL_LOCALE.

قيمة الإرجاع
بشرط ألا تتجاوز سلسلة المحارف الناتجة، بما في ذلك البايت الفارغ الختامي، max بايت، تُرجع strftime() عدد البايتات (باستثناء البايت الفارغ الختامي) الموضوعة في المصفوفة s. إذا تجاوز طول سلسلة المحارف الناتجة (بما في ذلك البايت الفارغ الختامي) max بايت، فتُرجع strftime() 0، وتكون محتويات المصفوفة غير محددة.

لاحظ أن قيمة الإرجاع 0 لا تشير بالضرورة إلى خطأ. على سبيل المثال، في العديد من الإعدادات المحلية يُنتج %p سلسلة محارف فارغة. سلسلة محارف التنسيق الفارغة ستُنتج بالمثل سلسلة محارف فارغة.

البيئة
تُستخدم متغيرات البيئة TZ و LC_TIME.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
strftime(), strftime_l() | سلامة الخيوط | بيئة محلية آمنة لتعدد الخيوط (MT-Safe)

المعايير

strftime()
    C11, POSIX.1-2008.

strftime_l()
    POSIX.1-2008.

التاريخ

strftime()
    SVr4، C89.

strftime_l()
    POSIX.1-2008.

توجد تضمينات صارمة بين مجموعة التحويلات المعطاة في ANSI C (غير موسومة)، وتلك المعطاة في مواصفات UNIX الموحدة (موسومة SU)، وتلك المعطاة في حزمة المنطقة الزمنية لأولسون (موسومة TZ)، وتلك المعطاة في glibc (موسومة GNU)، باستثناء أن %+ غير مدعوم في glibc2. من ناحية أخرى، لدى glibc2 عدة امتدادات إضافية. يشير POSIX.1 فقط إلى ANSI C؛ يصف POSIX.2 تحت date(1) عدة امتدادات يمكن تطبيقها على strftime() أيضًا. تحويل %F موجود في C99 وPOSIX.1-2001.

في SUSv2، سمح محدد %S بنطاق من 00 إلى 61، للسماح بالاحتمال النظري لدقيقة تتضمن ثانية كبيسة مزدوجة (لم توجد مثل هذه الدقيقة أبدًا).

ملاحظات

  تواريخ الأسبوع وفقًا لمعيار ISO 8601
تُنتج %G و %g و %V قيمًا محسوبة من السنة القائمة على الأسبوع المُعرَّفة بمعيار ISO 8601. في هذا النظام، تبدأ الأسابيع يوم الاثنين، وتُرقَّم من 01 للأسبوع الأول حتى 52 أو 53 للأسبوع الأخير. الأسبوع 1 هو أول أسبوع تقع فيه أربعة أيام أو أكثر ضمن السنة الجديدة (أو، بشكل مترادف، الأسبوع 01 هو: أول أسبوع من السنة يحتوي على يوم الخميس؛ أو الأسبوع الذي يحتوي على 4 يناير). عندما يقع ثلاثة أيام أو أقل من الأسبوع التقويمي الأول للسنة الجديدة ضمن تلك السنة، فإن نظام ISO 8601 القائم على الأسبوع يعد تلك الأيام جزءًا من الأسبوع 52 أو 53 من السنة السابقة. على سبيل المثال، 1 يناير 2010 هو يوم جمعة، مما يعني أن ثلاثة أيام فقط من ذلك الأسبوع التقويمي تقع في 2010. وبالتالي، يعتبر نظام ISO 8601 القائم على الأسبوع هذه الأيام جزءًا من الأسبوع 53 (%V) من عام 2009 (%G)؛ يبدأ الأسبوع 01 من عام ISO 8601 2010 يوم الاثنين، 4 يناير 2010. وبالمثل، يُعتبر أول يومين من يناير 2011 جزءًا من الأسبوع 52 من عام 2010.

  ملاحظات glibc
يوفر glibc بعض الامتدادات لمواصفات التحويل. (لم تُحدَّد هذه الامتدادات في POSIX.1-2001، لكن بعض الأنظمة الأخرى توفر ميزات مشابهة.) بين الحرف '%' وحرف محدد التحويل، يمكن تحديد علامة اختيارية وعرض حقل width. (تسبق هذه المُعدِّلات E أو O، إن وُجدت.)

يُسمح بأحرف العلامة التالية:

_   (شرطة سفلية) حشو سلسلة محارف رقمية ناتجة بمسافات.

-   (شرطة) لا تحشُ سلسلة محارف رقمية ناتجة.

0   حشو سلسلة محارف رقمية ناتجة بأصفار حتى لو استخدم حرف محدد التحويل حشوًا بمسافات مبدئيًا.

^   تحويل الأحرف الأبجدية في سلسلة المحارف الناتجة إلى أحرف كبيرة.

#   تبديل حالة سلسلة المحارف الناتجة. (تعمل هذه العلامة فقط مع بعض أحرف محددات التحويل، ومن بينها، هي مفيدة حقًا فقط مع %Z.)

يمكن أن يتبع العلامة (التي قد تكون غائبة) محدد عرض عشري اختياري. إذا كان الحجم الطبيعي للحقل أصغر من هذا العرض، فتُحشى سلسلة المحارف الناتجة (على اليسار) إلى العرض المحدد.

العلل
إذا تجاوزت سلسلة المحارف الناتجة max بايت، لا يُضبط errno. هذا يجعل من المستحيل التمييز بين حالة الخطأ هذه والحالات التي تنتج فيها سلسلة محارف التنسيق بشكل شرعي سلسلة محارف ناتجة بطول صفري. لا يحدد POSIX.1-2001 أي إعدادات errno لـ strftime().

تشتكي بعض الإصدارات المعيبة من gcc(1) من استخدام %c: تحذير: `%c' يُنتج آخر رقمين فقط من السنة في بعض الإعدادات المحلية. بالطبع يُشجَّع المبرمجون على استخدام %c، لأنه يُعطي التمثيل المفضل للتاريخ والوقت. يُواجه المرء جميع أنواع الإبهامات الغريبة لتجاوز مشكلة gcc(1) هذه. أحد الحلول النظيفة نسبيًا هو إضافة دالة وسيطة

    size_t
    my_strftime(char *s, size_t max, const char *fmt,
                const struct tm *tm)
    {
        return strftime(s, max, fmt, tm);
    }

في الوقت الحالي، يوفر gcc(1) الخيار -Wno-format-y2k لمنع التحذير، لذا لم يعد الحل البديل أعلاه مطلوبًا.

أمثلة
تنسيق تاريخ متوافق مع RFC 2822 (مع بيئة محلية إنجليزية لـ %a و %b)

    "%a, %d %b %Y %T %z"

تنسيق تاريخ متوافق مع RFC 822 (مع بيئة محلية إنجليزية لـ %a و %b)

    "%a, %d %b %y %T %z"

  برنامج مثال
يمكن استخدام البرنامج أدناه للتجربة مع strftime().

بعض الأمثلة لسلسلة النتيجة المنتجة بواسطة تطبيق glibc لـ strftime() هي كما يلي:

    $ ./a.out '%m'
    Result string is "11"
    $ ./a.out '%5m'
    Result string is "00011"
    $ ./a.out '%_5m'
    Result string is "   11"

  مصدر البرنامج
    #include <stdio.h>
    #include <stdlib.h>
    #include <time.h>

    int
    main(int argc, char *argv[])
    {
        char outstr[200];
        time_t t;
        struct tm *tmp;

        if (argc != 2) {
            fprintf(stderr, "Usage: %s: <format-string>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        t = time(NULL);
        tmp = localtime(&t);
        if (tmp == NULL) {
            perror("localtime");
            exit(EXIT_FAILURE);
        }

        if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
            fprintf(stderr, "strftime returned 0");
            exit(EXIT_FAILURE);
        }

        printf("Result string is \"%s\"\n", outstr);
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
date(1), time(2), ctime(3), nl_langinfo(3), setlocale(3), sprintf(3), strptime(3)

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

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

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