1: Carbonの初め方

1.1 はじめに

日付と時刻を扱うためのシンプルで意味のあるgolangパッケージです。

Carbonを使用する利点：

  • 開発者向けの使いやすさ: Carbonは適直で表現力豊かなインターフェースを提供し、開発者にとって直感的です。
  • 国際化のサポート: 日付表現を地域化することができる、国際化をサポートします。
  • イミュータビリティ: Carbonのインスタンスは不変であり、予期しない変更がないように安全に渡すことができます。
  • タイムゾーンの扱い: Carbonは異なるタイムゾーン間での日付と時刻の管理の複雑さを簡略化します。
  • 豊富なAPI: 日付と時刻の作成、解析、フォーマットのための包括的な関数セットを提供します。

1.2 インストールガイド

Goバージョン >= 1.16のためのインストール

Goバージョン1.16以上の場合、以下のコマンドを使用してCarbonパッケージをインストールします:

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

その後、パッケージをGoファイルにインポートします:

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

Goバージョン < 1.16のためのインストール

古いバージョンのGoの場合、以下を使用してCarbonをインストールできます:

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

そして同様にインポートします:

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

v1はもはや積極的に更新されていませんが、バグ修正のために保守されます。

1.3 最初のCarbonプロジェクトのセットアップ

Carbonの基本的な構成: Carbonがインストールされたら、新しいCarbonインスタンスを作成するだけで使用を開始できます。 プロジェクトの要件に合わせてデフォルトのグローバルレイアウト、タイムゾーン、およびロケールを設定することで、Carbonをカスタマイズできます。

グローバルデフォルトレイアウト、タイムゾーン、ロケールの設定:

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

明示的に設定されていない場合、これらのCarbonのデフォルト設定は次の通りです — Layout: "2006-01-02 15:04:05", Timezone: Local, Locale: "en"。

2: 基本的なCarbonの動作

2.1 現在の時刻の操作

現在の日付と時刻の取得

多くのアプリケーションで現在の日付と時刻の取得は基本的な操作です。Carbonを使用すると、carbon.Now()メソッドを呼び出すことで現在の日付時刻インスタンスを取得できます。現在の日付時刻の取得方法を見てみましょう:

// 現在の日付時刻をCarbonインスタンスとして取得します。
now := carbon.Now()

fmt.Println("現在の日付時刻:", now)

今日、昨日、明日の表示

Carbonは現在の日にちに関連する日付を扱うエレガントな方法を提供します。今日、昨日、および明日の日付の表現を取得するために、それぞれ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())

これらのメソッドは、手動で計算する必要なく、よく使用される日付参照の端的な取扱いを提供します。

現在時刻のフォーマットと表現

Carbonは異なる方法で日付時刻をフォーマットおよび表示できます。ISO8601などの標準フォーマット、カスタムフォーマット、または地域化されたバージョンが必要な場合、Carbonにはその要件に合ったメソッドがあります。

以下は、現在の日付時刻をいくつかの方法でフォーマットする方法です:

// 標準的な日付時刻表現
fmt.Println("RFC3339:", now.ToRFC3339String())
fmt.Println("ISO8601:", now.ToIso1String())

// カスタムな日付時刻フォーマット
fmt.Println("Custom:", now.Format("Monday, 02-Jan-06 15:04:05 MST"))

// 事前定義のレイアウトを使用
fmt.Println("ANSIC format:", now.ToAnsicString())
fmt.Println("UnixDate format:", now.ToUnixDateString())
fmt.Println("RubyDate format:", now.ToRubyDateString())
fmt.Println("Kitchen format:", now.ToKitchenString())

// カスタムパターンの場合、Formatメソッドを使用します
fmt.Println("Custom pattern:", now.Format("2006-01-02 3:04 PM"))

2.2 Carbonインスタンスの作成

タイムスタンプからインスタンスを作成する

Goではタイムスタンプを扱うことが頻繁にあり、Carbonはこれらを扱う直感的な方法を提供しています。タイムスタンプは、特定のイベントが発生した時点を識別する一連の文字またはエンコードされた情報であり、通常は日付と時刻を与え、時には秒の小さな部分まで精度が高いことがあります。

UnixタイムスタンプからCarbonのインスタンスを作成するには、さまざまな精度レベルを使用できます：

// 秒単位の精度で指定のタイムスタンプから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のインスタンスとして解析
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)
}

日付と時刻を扱う際の堅牢なエラーチェックは、予期しない結果やシステムのクラッシュを防ぐために重要な部分です。