Ruby/Time

الصنف Time هو تجريد لمفهومي التاريخ والوقت. يتم تخزين Time داخليا كعدد الثواني (مع كسورها) منذ توقيت يونيكس (1 يناير 1970 00:00 بالتوقيت العالمي). انظر أيضًا الوحدة Date لمزيد من المعلومات.

يعامِل الصنف Time توقيت جرينتش (GMT، اختصار للعبارة Greenwich Mean Time) والتوقيت العالمي الموحد (UTC، اختصار للعبارة Universal Time Coordinated) على أنهما متكافئان. توقيت جرينتش هو الطريقة الأقدم للإشارة إلى هذه الأوقات المرجعية، ولا تزال موجودة في أسماء الاستدعاءات على أنظمة POSIX.

يمكن أن يكون لجميع الأوقات كسور. انتبه لهذا الأمر عند مقارنة الأوقات مع بعضها البعض؛ فالأوقات التي تبدو متساوية عند عرضها، قد تكون مختلفة عند المقارنة.

منذ روبي 1.9.2، يستخدم الصنف Time عددًا صحيحًا ذا إشارة بحجم 63 بت أو عددًا من النوع Bignum أو Rational. العدد الصحيح يمثل عدد النانوثواني منذ بدء توقيت يونيكس، والتي يمكن أن تمثل ‎1823-11-12 بالقيمة ‎2116-02-20. عند استخدام Bignum أو Rational (قبل 1823، وبعد 2116، بالنانوثانية) ، يعمل الصنف Time بشكل أبطأ مقارنة باستخدام الأعداد الصحيحة.

الأمثلة

كل الأمثلة الموجودة في صفحات التوابع تعمل باستخدام المنطقة الزمنية EST (التوقيت الشرقي القياسي [Eastern Standard Time]) والتي تساوي GMT-5 بتوقيت غرينتش.

إنشاء توقيت جديد

يمكنك إنشاء توقيت جديد (نسخة من الصنف Time) عبر التابع new، إذ سيستخدم الوقت الحالي في النظام. التابع now هو اسم بديل للمتغير this. يمكنك أيضًا تمرير أجزاء من الوقت إلى new، مثل السنة والشهر والدقيقة وما إلى ذلك. عندما تريد إنشاء توقيت بهذا التابع، فيجب أن تمرر السنة على الأقل. إذا مررت السنة وحدها، فسيتم تعيين الوقت الافتراضي لبقية القيم عند الشهر يناير/كانون الثاني من بداية ذلك العام على الساعة 00:00:00 بتوقيت المنطقة الزمنية الحالية للنظام.

إليك بعض الأمثلة:

Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
Time.new(2002, 10)     #=> 2002-10-01 00:00:00 -0500
Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200‎

يمكنك أيضًا استخدام التوابع gm و local و utc لاعتماد المناطق الزمنية لغرينتش أو التوقيت المحلي أو التوقيت العالمي بدلًا من استخدام إعدادات النظام الحالي. يمكنك أيضًا إنشاء توقيت جديد باستخدام at، والذي يأخذ عدد الثواني (أو أعشار الثواني) منذ بدء توقيت يونيكس.

Time.at(628232400) #=> 1989-11-28 00:00:00 -0500‎

العمل مع التوقيتات

بمجرد أن تُنشئ توقيتًا (نسخة من الصنف Time)، فهناك العديد من الأشياء التي يمكنك القيام بها. فيما يلي بعض الأمثلة.

في جميع الأمثلة التالية، سنفترض أنك قمت بما يلي:

t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")‎

هل t يتوافق مع يوم الاثنين؟

t.monday? #=> false‎

أي عام هو هذا؟

t.year #=> 1993‎

هل t توقيت صيفي؟

t.dst? #=> false‎

ما هو اليوم الذي يوافق عامًا بعد t؟

t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900‎

كم عدد الثواني منذ توقيت يونيكس وحتى t؟

t.to_i #=> 730522800‎

يمكنك أيضًا القيام بالعمليات والوظائف العادية، مثل مقارنة توقيتين:

t1 = Time.new(2010)
t2 = Time.new(2011)
t1 == t2 #=> false
t1 == t1 #=> true
t1 <  t2 #=> true
t1 >  t2 #=> false
Time.new(2010,10,31).between?(t1, t2) #=> true‎

توابع الصنف العامة

at

ينشئ توقيتًا جديدًا انطلاقًا من معلومات الوقت المٌمرَّرة إليه.

gm

ينشئ توقيتًا جديدًا استنادًا إلى القيم المعطاة، ويتم تفسيرها وفق التوقيت العالمي الموحد UTC ‏(GMT).

local

ينشئ توقيتًا جديدًا بشكل مشابه للتابع gm باستثناء أنَّه يفسر القيم في إطار المنطقة الزمنية المحلية.

mktime

ينشئ توقيتًا جديدًا بشكل مشابه للتابع gm باستثناء أنَّه يفسر القيم في إطار المنطقة الزمنية المحلية.

new

ينشئ توقيتًا جديدًا. يتم ضبطه عند وقت النظام الحالي إذا لم يُمرر أي وسيط.

now

يُنشئ توقيتًا جديدًا من الوقت الحالي

utc

ينشئ توقيتًا جديدًا استنادًا إلى القيم المعطاة، ويتم تفسيره وفق التوقيت العالمي الموحد UTC‏ (GMT).

توابع النسخة العامة

+

يضيف عددًا من الثواني (ربما يكون عدد كسري) إلى التوقيت المعطى، ثم يُعيد تلك القيمةكتوقيت جديد.

-

يُعيد الفرق بالثانية بين وقتين، أو يطرح عددًا يمثِّل الثواني من التوقيت المعطى.

<=>

يوازن بين توقيتين.

asctime

يُعيد سلسلة نصية أساسية (canonical string) تحوي توقيت الكائن Time الذي استدعي معه.

ctime

يُعيد سلسلة نصية أساسية (canonical string) تحوي توقيت الكائن Time الذي استدعي معه.

day

يستخلص من التوقيت رقم اليوم من الشهر (1..n).

dst?‎

يتحقق إن وقع التوقيت أثناء التوقيت الصيفي في منطقته الزمنية.

eql?‎

يتحقق إذا كان توقيتان متساويين تمامًا.

friday?‎

يتحقق إن كان التوقيت يمثل يوم الجمعة.

getgm

يُعيد توقيتًا جديدًا يمثل التوقيت الذي استُدعي معه بالتوقيت العالمي الموحد (UTC).

getlocal

يُعيد توقيتًا جديدًا يمثل التوقيت الذي استُدعي معه بالتوقيت المحلي (باستخدام المنطقة الزمنية المحلية السارية لهذه العملية).

getutc

يُعيد توقيتًا جديدًا يمثل التوقيت الذي استُدعي معه بالتوقيت العالمي الموحد (UTC).

gmt?‎

يتحقق إن كان التوقيت الذي استدعي معه ممثلًا بالتوقيت العالمي الموحد (UTC).

gmt_offset

يُعيد الفارق بين المنطقة الزمنية للتوقيت المعطى والتوقيت العالمي الموحد (UTC) بالثانية.

gmtime

يحول التوقيت الذي استُدعي معه إلى التوقيت العالمي الموحد (UTC).

gmtoff

يُعيد الفارق بين المنطقة الزمنية للتوقيت الذي استُدعي معه والتوقيت العالمي الموحد (UTC) بالثانية.

hash

يُعيد القيمة hash للتوقيت الذي استدعي معه.

hour

يُستخلص من التوقيت رقم الساعة لليوم.

inspect

يُعيد سلسلة نصية تمثل التوقيت الذي استدعي معه. 

isdst

يتحقق إن وقع التوقيت الذي استُدعي معه أثناء التوقيت الصيفي في منطقته الزمنية.

localtime

يحول التوقيت الذي استُدعي معه إلى التوقيت المحلي (باستخدام المنطقة الزمنية المحلية السارية لهذه العملية).

mday

يستخلص من التوقيت الذي استدعي معه رقم اليوم من الشهر.

min

يستخلص من التوقيت الذي استدعي معه رقم الدقيقة من الساعة.

mon

يستخلص من التوقيت الذي استدعي معه رقم الشهر من السنة.

monday?‎

يتحقق إن كان التوقيت يمثل يوم الاثنين.

month

يستخلص من التوقيت الذي استدعي معه رقم الشهر من السنة.

nsec

يُعيد النانو ثانية المقابل للتوقيت الذي مر منذ توقيت يونيكس.

round

يُقرّب الأجزاء العشرية من الثواني وفق دقة معينة من المنازل العشرية للتوقيت الذي استدعي معه.

saturday?‎

يتحقق إن كان التوقيت يمثل يوم السبت.

sec

يستخلص من التوقيت رقم الثانية في الدقيقة.

strftime

يُنسق التوقيت الذي استدعي معه وفقًا للموجّهات (directives) الموجودة في سلسلة التنسيق المُمرَّرة إليه.

subsec

يُعيد الجزء العشري للثانية من التوقيت الذي استدعي معه.

succ

يُعيد توقيتا جديدًا، مع إضافة ثانية واحدة على التوقيت الذي استُدعي معه.

sunday?‎

يتحقق إن كان التوقيت يمثل يوم الأحد.

thursday?‎

يتحقق إن كان التوقيت يمثل يوم الخميس.

to_a

يحول التوقيت الذي استدعي معه إلى مصفوفة.

to_f

يحول قيمة التوقيت المعطى إلى عدد عشري يمثل عدد الثواني التي مرَّت منذ توقيت يونكس.

to_i

يحول قيمة التوقيت المعطى إلى عدد صحيح يمثل الثواني التي مرت منذ توقيت يونكس.

to_r

يحول قيمة التوقيت المعطى إلى عدد جذري يمثل عدد الثواني التي مرت منذ توقيت يونكس.

to_s

يحول التوقيت المعطى إلى سلسلة نصية. 

tuesday?‎

يتحقق إن كان التوقيت يمثل يوم الخميس.

tv_nsec

يُعيد عدد النانوثواني المقابلة للتوقيت المعطى التي مرت منذ توقيت يونيكس.

tv_sec

يُعيد القيمة المقابلة للتوقيت التي تمثل عدد الثواني التي مرت منذ توقيت يونيكس.

tv_usec

يُعيد المقابلة للتوقيت التي تمثل عدد الميكروثواني التي مرت منذ توقيت يونيكس.

usec

يُعيد القيمة المقابلة للتوقيت التي تمثل عدد الميكروثواني التي مرت منذ توقيت يونيكس.

utc

يحول التوقيت إلى التوقيت العالمي الموحد (UTC)‏.

utc?‎

يتحقق إن كان التوقيت الذي استُدعي معه يمثل توقيتًا في النطاق العالمي الموحد UTC‏ (GMT).

utc_offset

يُعيد الفارق بين المنطقة الزمنية للتوقيت والتوقيت العالمي الموحد UTC بالثانية.

wday

يُعيد عددًا صحيحًا يمثل رقم اليوم في الأسبوع للتوقيت الذي استدعي معه.

wednesday?‎

يتحقق إن كان التوقيت يمثل يوم الأربعاء.

yday

يُعيد عددًا صحيحًا يمثل رقم اليوم في السنة للتوقيت الذي استدعي معه.

year

يستخلص من التوقيت الذي استُدعي معه قيمة السنة (بما في ذلك القرن).

zone

يعيد اسم المنطقة الزمنية المستخدمة في التوقيت الذي استدعي معه.

مصادر

• صفحة الصنف Time في توثيق روبي الرسمي.