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?‎

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

friday?‎

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

getgm

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

getlocal

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

getutc

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

gmt?‎

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

gmt_offset

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

gmtime

يحولgmtime التوقيت إلى التوقيت العالمي الموحد

gmtoff

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

hash

يُعيدرمز تجزئة (hash code) للتوقيت.

hour

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

inspect

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

isdst

يُعيدisdst القيمة true إن وقع التوقيت أثناء التوقيت الصيفي

localtime

يحولlocaltime التوقيت إلى التوقيت المحلي

mday

يستخلصmday من التوقيت رقم اليوم من الشهر

min

يستخلصmin من التوقيت رقم الدقيقة من الساعة

mon

يستخلصmon من التوقيت رقم الشهر من السنة

monday?‎

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

month

يستخلصmonth من التوقيت رقم الشهر من السنة

nsec

يُعيدnsec عدد النانوثواني المقابل للتوقيت.

round

يُقرّبround الثواني الكسرية وفق دقة معينة.

saturday?‎

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

sec

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

strftime

يُنسقstrftime التوقيت وفقًا للموجّهات (directives) الموجودة في سلسلة التنسيق المعطاة.

subsec

يُعيدsubsec الجزء العشري من التوقيت.

succ

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

sunday?‎

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

thursday?‎

يُعيدthursday?‎ القيمة true إن كان التوقيت يمثل يوم الخميس.

to_a

يُعيدto_a مصفوفة عشارية تضم قيم التوقيت

to_f

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

to_i

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

to_r

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

to_s

يُعيدto_s سلسلة نصية تمثل التوقيت

tuesday?‎

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

tv_nsec

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

tv_sec

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

tv_usec

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

usec

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

utc

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

utc?‎

يُعيدutc?‎ القيمة true إن كان التوقيت ضمن نطاق التوقيت العالمي الموحد

utc_offset

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

wday

يُعيدwday عددا صحيحا يمثل رقم اليوم في الأسبوع

wednesday?‎

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

yday

يُعيدyday عددا صحيحا يمثل رقم اليوم في السنة ، 1..366.

year

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

zone

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

مصادر

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