التمكن من Carbon لمعالجة التواريخ والأوقات في Golang

1: البدء مع كاربون

1.1 المقدمة

حزمة جولانغ بسيطة ودلالية وودية للمطورين لإدارة الأوقات والتواريخ.

فوائد استخدام كاربون في إدارة الأوقات والتواريخ:

• ودية للمطورين: تقدم كاربون واجهة سلسة وتعبيرية للتعامل مع الأوقات والتواريخ تكون بديهية للمطورين.
• دعم التدويل: يدعم التدويل، مما يتيح لك توطين تمثيلات التاريخ الخاصة بك.
• عدم التغييرية: تكون حالات كاربون عديمة التغيير، وهذا يعني أنه يمكن نقلها بسلام من دون تعديلات غير متوقعة.
• معالجة المناطق الزمنية: تبسيط تعقيد إدارة الأوقات والتواريخ عبر مناطق زمنية مختلفة.
• واجهة برمجة واسعة النطاق: توفر مجموعة شاملة من الوظائف لإنشاء وتحليل وتنسيق التواريخ والأوقات.

1.2 دليل التثبيت

تثبيت لإصدار جولانج >= 1.16

لتثبيت حزمة كاربون لإصدار جولانج 1.16 أو أعلى، استخدم الأمر التالي:

go get -u github.com/golang-module/carbon/v2

ثم، استوردها في ملف جولانج الخاص بك:

import "github.com/golang-module/carbon/v2"

تثبيت لإصدار جولانج < 1.16

بالنسبة لإصدارات جولانج القديمة، يمكنك لازالة تثبيت كاربون باستخدام:

go get -u github.com/golang-module/carbon

واستيرادها بنفس الطريقة:

import "github.com/golang-module/carbon"

يرجى ملاحظة أن الإصدار v1 لم يعد يُحدّث نشطًا، ولكن سيتم الاحتفاظ به لإصلاح الأخطاء.

1.3 إعداد مشروع كاربون الأول

تكوين كاربون الأساسي: بمجرد تثبيت كاربون، يمكنك البدء في استخدامه ببساطة عن طريق إنشاء مثيل كاربون جديد. يمكنك تخصيص كاربون عن طريق ضبط التخطيط الإفتراضي العالمي، والمنطقة الزمنية، والإعداد المحلي لتناسب احتياجات مشروعك.

ضبط التخطيط العالمي الافتراضي، والمنطقة الزمنية، والإعداد المحلي:

carbon.SetDefault(carbon.Default{
  Layout: carbon.RFC3339Layout,
  Timezone: carbon.PRC,
  Locale: "ar",
})

إذا لم يتم ضبطها صراحة، فإن كاربون لديها إعدادات افتراضية لهذه — Layout: "2006-01-02 15:04:05"، Timezone: Local، Locale: "en".

2: العمليات الأساسية في كاربون

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

استرداد الوقت والتاريخ الحالي

استرداد تاريخ ووقت الحالي هو عملية أساسية في العديد من التطبيقات. باستخدام كاربون، يمكنك الحصول على مثيل الوقت والتاريخ الحالي من خلال استدعاء الطريقة carbon.Now().

فلنلق نظرة على كيفية جلب الوقت والتاريخ الحالي:

// جلب تاريخ ووقت الحالي كمثيل كاربون.
now := carbon.Now()

fmt.Println("التاريخ والوقت الحالي:", now)

عرض اليوم الحالي، والأمس، والغد

كاربون يوفر طريقة أنيقة للعمل مع التواريخ بالنسبة لليوم الحالي. للحصول على تمثيل للتاريخ لليوم الحالي والأمس والغد، يمكنك استخدام الطرق carbon.Now()، carbon.Yesterday()، و carbon.Tomorrow() على التوالي:

// تاريخ اليوم
today := carbon.Now()
fmt.Println("اليوم:", today.ToDateTimeString())

// تاريخ الأمس
yesterday := carbon.Yesterday()
fmt.Println("الأمس:", yesterday.ToDateTimeString())

// تاريخ الغد
tomorrow := carbon.Tomorrow()
fmt.Println("الغد:", tomorrow.ToDateTimeString())

توفر الطرق وسيلة موجزة للتفاعل مع هذه المراجع التاريخية المستخدمة بشكل شائع بدون حسابات يدوية.

تنسيق وتمثيل الوقت الحالي

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

إليك كيفية تنسيق التاريخ والوقت الحالي بطرق مختلفة:

// تمثيل قياسي للتاريخ والوقت
fmt.Println("RFC3339:", now.ToRFC3339String())
fmt.Println("ISO8601:", now.ToIso8601String())

// تنسيق مخصص للتاريخ والوقت
fmt.Println("مخصص:", now.Format("Monday, 02-Jan-06 15:04:05 MST"))

// باستخدام التخطيطات المعرفة مسبقًا
fmt.Println("صياغة ANSIC:", now.ToAnsicString())
fmt.Println("صياغة UnixDate:", now.ToUnixDateString())
fmt.Println("صياغة RubyDate:", now.ToRubyDateString())
fmt.Println("صياغة Kitchen:", now.ToKitchenString())

// للأنماط المخصصة، استخدم الطريقة Format
fmt.Println("النمط المخصص:", now.Format("2006-01-02 3:04 PM"))

2.2 إنشاء حالات كاربون

إنشاء حالات من الطابع الزمني

في Go، التعامل مع الطوابع الزمنية شائع، ويوفر Carbon طرقاً بديهية للتعامل معها. الطابع الزمني هو سلسلة من الأحرف أو المعلومات المُشفرة تحدد متى حدثت حدث معين، وعادة ما تُعطي تاريخًا ووقت اليوم، وأحيانا دقة تصل إلى جزء صغير من الثانية.

لإنشاء حالة Carbon من طابع زمني Unix، الذي يمثل عدد الثواني التي مرت منذ البدء الفعلي لنظام Unix (منتصف ليل 1 يناير 1970، بتوقيت عالمي متفق عليه)، يمكنك استخدام مستويات دقة مختلفة:

// إنشاء حالة Carbon من طابع زمني معين بدقة الثانية
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // الناتج: "2020-08-05 13:14:15 +080 CST"

// بالنسبة لدقة أعلى (بالميلي ثانية)، استخدم `CreateFromTimestampMilli`
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // الناتج: "2020-08-05 13:14:15.999 +080 CST"

// للميكروثانية، استخدم `CreateFromTimestampMicro`
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // الناتج: "2020-08-05 13:14:15.999999 +080 CST"

// وبالنسبة للنانوثانية، استخدم `CreateFromTimestampNano`
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // الناتج: "2020-08-05 13:14:15.999999999 +080 CST"

إنشاء حالات من مكونات التاريخ والوقت

إذا كانت لديك المكونات الفردية لتاريخ معين، مثل السنة والشهر واليوم، أو مكونات الوقت مثل الساعة والدقيقة والثانية، يمكن لـ Carbon التعامل مع هذه الحالات أيضا.

// إنشاء حالة Carbon من تاريخ معين فقط
date := carbon.CreateFromDate(2022, 12, 25)
fmt.Println(date.ToDateString()) // الناتج: "2022-12-25"

// إنشاء حالة Carbon من وقت معين فقط
time := carbon.CreateFromTime(23, 59, 59)
fmt.Println(time.ToTimeString()) // الناتج: "23:59:59"

// إنشاء حالة Carbon من تاريخ ووقت معين
dateTime := carbon.CreateFromDateTime(2022, 12, 25, 23, 59, 59)
fmt.Println(dateTime.ToDateTimeString()) // الناتج: "2022-12-25 23:59:59"

2.3 تحليل سلاسل الوقت

التعامل مع تمثيلات الوقت والتاريخ كسلاسل نصية سيناريو شائع. يجعل Carbon من السهل تحويل السلاسل إلى حالات Carbon.

استخدام carbon.Parse لتنسيقات الوقت القياسية:

// تحليل سلسلة نصية تحتوي على تاريخ ووقت
c := carbon.Parse("2020-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
    fmt.Printf("خطأ: %v", c.Error)
} else {
    fmt.Println(c.ToDateTimeString()) // الناتج: "2020-08-05 13:14:15"
}

// تحليل سلسلة نصية بتنسيق RFC3339
rfc3339 := carbon.Parse("2020-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // الناتج: "2020-08-05 13:14:15 +080 CST"

تنسيقات مخصصة باستخدام ParseByFormat و ParseByLayout

يمكنك أيضًا تحليل السلاسل النصية التي تتبع تنسيق محدد لا يتم التعامل معه مباشرة بواسطة carbon.Parse.

// تحليل سلسلة زمنية كحالة Carbon بناءً على التنسيق
byFormat := carbon.ParseByFormat("2020|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // الناتج: "2020-08-05 13:14:15"

// تحليل سلسلة زمنية كحالة Carbon بناءً على التخطيط
byLayout := carbon.ParseByLayout("2020|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // الناتج: "2020-08-05"

التعامل مع الأخطاء

تحقق دائماً من حقل Error للتأكد من نجاح عملية التحليل:

invalidDate := carbon.Parse("هذا ليس تاريخًا", carbon.PRC)
if invalidDate.IsInvalid() {
    fmt.Println("خطأ في تحليل التاريخ:", invalidDate.Error)
}

تذكر، أن فحص الأخطاء القوية هو جزء حرج من العمل مع التواريخ والأوقات لتجنب النتائج غير المتوقعة أو انهيار النظام.