Scroll to navigation

strptime(3) Library Functions Manual strptime(3)

الاسم

strptime - تحويل تمثيل سلسلة محارف للوقت إلى بنية tm زمنية

المكتبة

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

موجز

#define _XOPEN_SOURCE       /* انظر feature_test_macros(7) */
#include <time.h>
char *strptime(const char *restrict s, const char *restrict format,
               struct tm *restrict tm);

الوصف

دالة strptime() هي عكس strftime(3); تُحوِّل سلسلة المحارف المشار إليها بـ s إلى قيم تُخزَّن في بنية "الوقت المفصَّل" المشار إليها بـ tm، باستخدام التنسيق المحدد بـ format.

بنية الوقت المفصَّل tm موصوفة في tm(3type).

وسيط format هو سلسلة محارف تتكون من واصفات حقول ومحارف نصية، تذكِّر بـ scanf(3). يتكون كل واصف حقل من محرف % يتبعه محرف آخر يحدد الاستبدال لواصف الحقل. يجب أن تحتوي جميع المحارف الأخرى في سلسلة format على محرف مطابق في سلسلة الإدخال، باستثناء المسافات البيضاء، التي تطابق صفرًا أو أكثر من محارف المسافات البيضاء في سلسلة الإدخال. يجب أن تكون هناك مسافة بيضاء أو محارف أبجدية رقمية أخرى بين أي واصفي حقل.

دالة strptime() تعالج سلسلة الإدخال من اليسار إلى اليمين. يُعالَج كل عنصر من عناصر الإدخال الثلاثة الممكنة (مسافة بيضاء، حرفي، أو تنسيق) واحدًا تلو الآخر. إذا تعذَّرت مطابقة الإدخال مع سلسلة التنسيق، تتوقف الدالة. لا تُعالَج بقية سلسلتي التنسيق والإدخال.

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

%%
محرف %.
%a أو %A
اسم يوم الأسبوع وفقًا للإعدادات المحلية الحالية، بشكل مختصر أو الاسم الكامل.
%b أو %B أو %h
اسم الشهر وفقًا للإعدادات المحلية الحالية، بشكل مختصر أو الاسم الكامل.
%c
تمثيل التاريخ والوقت للإعدادات المحلية الحالية.
%C
رقم القرن (0–99).
%d أو %e
يوم الشهر (1–31).
%D
مكافئ لـ %m/%d/%y. (هذا هو نمط التاريخ الأمريكي، مُربك جدًا لغير الأمريكيين، خاصةً وأن %d/%m/%y يُستخدم على نطاق واسع في أوروبا. تنسيق ISO 8601 القياسي هو %Y-%m-%d.)
%H
الساعة (0–23).
%I
الساعة على ساعة ذات 12 ساعة (1–12).
%j
رقم اليوم في السنة (1–366).
%m
رقم الشهر (1–12).
%M
الدقيقة (0–59).
%n
مسافة بيضاء عشوائية.
%p
المكافئ المحلي لـ AM أو PM. (ملاحظة: قد لا يوجد أي منها.)
%r
وقت الساعة 12 ساعة (باستخدام AM أو PM المحلي). في الإعدادات المحلية POSIX يعادل %I:%M:%S %p. إذا كان t_fmt_ampm فارغًا في جزء LC_TIME من الإعدادات المحلية الحالية، فإن السلوك غير محدد.
%R
يعادل %H:%M.
%S
الثانية (0–60; قد تظهر 60 للثواني الكبيسة؛ سابقًا كان مسموحًا أيضًا بـ 61).
%t
مسافة بيضاء عشوائية.
%T
يعادل %H:%M:%S.
%U
رقم الأسبوع مع الأحد كأول يوم في الأسبوع (0–53). أول أحد في يناير هو اليوم الأول من الأسبوع 1.
%w
الرقم الترتيبي ليوم الأسبوع (0–6)، مع الأحد = 0.
%W
رقم الأسبوع مع الاثنين كأول يوم في الأسبوع (0–53). أول اثنين في يناير هو اليوم الأول من الأسبوع 1.
%x
التاريخ، باستخدام تنسيق التاريخ المحلي.
%X
الوقت، باستخدام تنسيق الوقت المحلي.
%y
السنة ضمن القرن (0–99). عندما لا يُحدد قرن بخلاف ذلك، تشير القيم في النطاق 69–99 إلى سنوات في القرن العشرين (1969–1999)؛ تشير القيم في النطاق 00–68 إلى سنوات في القرن الحادي والعشرين (2000–2068).
%Y
السنة، بما في ذلك القرن (على سبيل المثال، 1991).

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

يحدد معدل E أن سلسلة المحارف المدخلة قد تحتوي على إصدارات بديلة تعتمد على الإعدادات المحلية لتمثيل التاريخ والوقت:

%Ec
تمثيل التاريخ والوقت البديل المحلي.
%EC
اسم السنة الأساسية (الفترة) في التمثيل البديل للمحلية.
%Ex
تمثيل التاريخ البديل للمحلية.
%EX
تمثيل الوقت البديل للمحلية.
%Ey
الإزاحة من %EC (السنة فقط) في التمثيل البديل للمحلية.
%EY
تمثيل السنة البديل الكامل.

يحدد المُعدِّل O أن الإدخال الرقمي قد يكون بصيغة بديلة معتمدة على المحلية:

%Od أو %Oe
يوم الشهر باستخدام الرموز الرقمية البديلة للمحلية؛ الأصفار البادئة مسموح بها ولكنها غير مطلوبة.
%OH
الساعة (ساعة 24 ساعة) باستخدام الرموز الرقمية البديلة للمحلية.
%OI
الساعة (ساعة 12 ساعة) باستخدام الرموز الرقمية البديلة للمحلية.
%Om
الشهر باستخدام الرموز الرقمية البديلة للمحلية.
%OM
الدقائق باستخدام رموز المنطقة الرقمية البديلة.
%OS
الثواني باستخدام رموز المنطقة الرقمية البديلة.
%OU
رقم الأسبوع من السنة (الأحد كأول يوم في الأسبوع) باستخدام رموز المنطقة الرقمية البديلة.
%Ow
الرقم الترتيبي ليوم الأسبوع (الأحد=0)، باستخدام رموز المنطقة الرقمية البديلة.
%OW
رقم الأسبوع من السنة (الاثنين كأول يوم في الأسبوع) باستخدام رموز المنطقة الرقمية البديلة.
%Oy
السنة (الإزاحة من %C) باستخدام رموز المنطقة الرقمية البديلة.

قيمة الإرجاع

قيمة إرجاع الدالة هي مؤشر إلى أول حرف لم يُعالج في استدعاء الدالة هذا. في حال احتواء سلسلة المحارف المدخلة على محارف أكثر مما تتطلبه سلسلة التنسيق، يشير المؤشر إلى ما بعد آخر حرف مدخل تم استهلاكه. في حال استهلاك سلسلة المحارف المدخلة بالكامل، يشير المؤشر إلى البايت الصفري في نهاية السلسلة. إذا فشلت strptime() في مطابقة كامل سلسلة التنسيق وبالتالي حدث خطأ، تُرجع الدالة NULL.

السمات

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

الواجهة السمة القيمة
strptime() سلامة الخيوط بيئة محلية آمنة لتعدد الخيوط (MT-Safe)

المعايير

POSIX.1-2008.

التاريخ

POSIX.1-2001, SUSv2.

ملاحظات

من حيث المبدأ، لا تُهيئ هذه الدالة tm بل تخزن فقط القيم المحددة. هذا يعني أنه يجب تهيئة tm قبل الاستدعاء. تختلف التفاصيل قليلاً بين أنظمة UNIX المختلفة. لا يلمس تطبيق glibc تلك الحقول غير المحددة صراحة، باستثناء إعادة حساب حقلي tm_wday و tm_yday إذا تغير أي من عناصر السنة أو الشهر أو اليوم.

يُؤخذ تحديد 'y' (السنة في القرن) لتحديد سنة في النطاق 1950–2049 بواسطة glibc 2.0. ويُؤخذ كسنة في 1969–2068 منذ glibc 2.1.

ملاحظات glibc

لأسباب التناظر، يحاول glibc دعم نفس محارف التنسيق لـ strptime() كما هو الحال لـ strftime(3). (في معظم الحالات، تُحلل الحقول المقابلة، لكن لا يُغير أي حقل في tm.) يؤدي هذا إلى:

%F
مكافئ لـ %Y-%m-%d، تنسيق التاريخ ISO 8601.
%g
السنة المقابلة لرقم أسبوع ISO، لكن بدون القرن (0–99).
%G
السنة المقابلة لرقم أسبوع ISO. (على سبيل المثال، 1991.)
%u
يوم الأسبوع كرقم عشري (1–7، حيث الاثنين = 1).
%V
رقم الأسبوع وفقًا لـ ISO 8601:1988 كرقم عشري (1–53). إذا كان الأسبوع (الذي يبدأ يوم الاثنين) الذي يحتوي على 1 يناير يحتوي على أربعة أيام أو أكثر في السنة الجديدة، فإنه يُعتبر الأسبوع 1. وإلا، فهو الأسبوع الأخير من العام السابق، والأسبوع التالي هو الأسبوع 1.
%z
مواصفات منطقة زمنية قياسية وفقًا لـ RFC-822/ISO 8601.
%Z
اسم المنطقة الزمنية.

وبالمثل، نظرًا لامتدادات GNU لـ strftime(3)، يُقبل %k كمرادف لـ %H، ويجب قبول %l كمرادف لـ %I، ويُقبل %P كمرادف لـ %p. وأخيرًا:

%s
عدد الثواني منذ العصر، 1970-01-01 00:00:00 +0000 (UTC). لا تُحتسب الثواني الكبيسة إلا إذا كان دعم الثواني الكبيسة متاحًا.

لا يتطلب تنفيذ glibc وجود مسافة بيضاء بين واصفَي حقلين.

أمثلة

يوضح المثال التالي استخدام strptime() وstrftime(3).

#define _XOPEN_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
int
main(void)
{


    struct tm tm;


    char buf[255];


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


    strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);


    strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);


    puts(buf);


    exit(EXIT_SUCCESS);
}

انظر أيضًا

time(2)، getdate(3)، scanf(3)، setlocale(3)، strftime(3)

ترجمة

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

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

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

6 أبريل 2026 صفحات دليل لينكس 6.18