الاسم¶

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()

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، للسماح بالاحتمال النظري لدقيقة تتضمن ثانية كبيسة مزدوجة (لم توجد مثل هذه الدقيقة أبدًا).

ملاحظات¶

العلل¶

إذا تجاوزت سلسلة المحارف الناتجة 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"

$ ./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 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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