مهارت در استفاده از Carbon برای کنترل تاریخ و زمان در گولنگ

1: شروع کار با کاربن

1.1 مقدمه

پکیج ساده، معنایی و قابل استفاده توسعه‌دهنده برای تاریخ و زمان در گولنگ

مزایای استفاده از کاربن برای برخورد با تاریخ و زمان:

• قابلیت استفاده برای توسعه‌دهندگان: کاربن یک رابط فلوئنت و بیان‌کننده برای برخورد با تاریخ و زمان ارائه می‌دهد که برای توسعه‌دهندگان قابل فهم است.
• پشتیبانی از بین‌المللی‌سازی: این پکیج از بین‌المللی‌سازی پشتیبانی می‌کند و به شما امکان محلی‌سازی نمایش تاریخ‌ها را می‌دهد.
• تغییرناپذیری: نمونه‌های کاربن تغییرناپذیر هستند که به این معنی است که می‌توانند به‌طور ایمن منتقل شوند بدون اعمال تغییرات غیرمنتظره.
• مدیریت مناطق زمانی: کاربن پیچیدگی مدیریت تاریخ و زمان را در مناطق زمانی مختلف ساده می‌کند.
• API گسترده: این پکیج مجموعه‌ای جامع از توابع را برای ایجاد، تجزیه و فرمت‌بندی تاریخ و زمان ارائه می‌دهد.

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: "en",
})

اگر به صورت صریح تنظیم نشده باشد، کاربن تنظیمات پیش‌فرض برای این‌ها دارد — طرح: "2006-01-02 15:04:05"، منطقه زمانی: محلی، محل: "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("یکشنبه، 02-ژانویه-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، UTC) را نشان می‌دهد، می توانید از سطوح دقت مختلف استفاده کنید:

// ایجاد یک نمونه از Carbon از یک زمان داده شده با دقت ثانیه
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // خروجی: "202-08-05 13:14:15 +080 CST"

// برای دقت بالاتر (میلی‌ثانیه)، از `CreateFromTimestampMilli` استفاده کنید
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // خروجی: "202-08-05 13:14:15.999 +080 CST"

// برای میکروثانیه، از `CreateFromTimestampMicro` استفاده کنید
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // خروجی: "202-08-05 13:14:15.999999 +080 CST"

// و برای نانوثانیه، از `CreateFromTimestampNano` استفاده کنید
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // خروجی: "202-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("202-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
    fmt.Printf("خطا: %v", c.Error)
} else {
    fmt.Println(c.ToDateTimeString()) // خروجی: "202-08-05 13:14:15"
}

// تجزیه یک رشته با فرمت RFC3339
rfc3339 := carbon.Parse("202-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // خروجی: "202-08-05 13:14:15 +080 CST"

فرمت‌های سفارشی با ParseByFormat و ParseByLayout

می‌توانید همچنین رشته‌هایی که در یک فرمت خاص که توسط carbon.Parse به صورت مستقیم پشتیبانی نمی‌شود، تجزیه کنید.

// تجزیه یک رشته زمان به عنوان یک نمونه از Carbon با فرمت
byFormat := carbon.ParseByFormat("202|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // خروجی: "202-08-05 13:14:15"

// تجزیه یک رشته زمان به عنوان یک نمونه از Carbon با layout
byLayout := carbon.ParseByLayout("202|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // خروجی: "202-08-05"

رفع اشکالات

همیشه بررسی کنید که فیلد Error برای اطمینان از موفقیت تجزیه است:

invalidDate := carbon.Parse("این تاریخ نیست", carbon.PRC)
if invalidDate.IsInvalid() {
    fmt.Println("خطا در تجزیه تاریخ:", invalidDate.Error)
}

به‌خاطر بسپارید که بررسی خطاها یک بخش اساسی از کار با تاریخ و زمان است تا از نتایج غیرمنتظره یا خرابی سیستم جلوگیری شود.