Go 每日一庫之 go-carbon，優雅的 golang 日期時間處理庫

gouguoyin發表於2021-02-03

Carbon

carbon 是一個輕量級、語義化、對開發者友好的 Golang 時間處理庫，支援鏈式呼叫和 gorm、xorm、zorm 等主流 orm。

安裝使用

// 使用 github 庫
go get -u github.com/golang-module/carbon
import (
 "github.com/golang-module/carbon")
// 使用 gitee 庫
go get -u gitee.com/go-package/carbon
import (
 "gitee.com/go-package/carbon")

用法示例

預設時區為 Local，即伺服器所在時區，假設當前時間為 2020-08-05 13:14:15

昨天、今天、明天

// 今天此刻
carbon.Now().ToDateTimeString() // 2020-08-05 13:14:15
// 今天日期
carbon.Now().ToDateString() // 2020-08-05
// 今天時間
carbon.Now().ToTimeString() // 13:14:15
// 今天秒級時間戳
carbon.Now().ToTimestamp() // 1596604455
carbon.Now().ToTimestampWithSecond() // 1596604455
// 今天毫秒級時間戳
carbon.Now().ToTimestampWithMillisecond() // 1596604455000
// 今天微秒級時間戳
carbon.Now().ToTimestampWithMicrosecond() // 1596604455000000
// 今天納秒級時間戳
carbon.Now().ToTimestampWithNanosecond() // 1596604455000000000
// 指定時區的今天此刻
carbon.SetTimezone(Carbon.NewYork).Now().ToDateTimeString() // 2020-08-05 01:14:15
// 昨天此刻
carbon.Yesterday().ToDateTimeString() // 2020-08-04 13:14:15
// 昨天日期
carbon.Yesterday().ToDateString() // 2020-08-04
// 昨天時間
carbon.Yesterday().ToTimeString() // 13:14:15
// 昨天秒級時間戳
carbon.Yesterday().ToTimestamp() // 1596518055
carbon.Yesterday().ToTimestampWithSecond() // 1596518055
// 明天毫秒級時間戳
carbon.Yesterday().ToTimestampWithMillisecond() // 1596518055000
// 明天微秒級時間戳
carbon.Yesterday().ToTimestampWithMicrosecond() // 1596518055000000
// 明天納秒級時間戳
carbon.Yesterday().ToTimestampWithNanosecond() // 1596518055000000000
// 指定時區的昨天此刻
carbon.SetTimezone(Carbon.NewYork).Yesterday().ToDateTimeString() // 2020-08-04 01:14:15
// 指定日期的昨天此刻
carbon.Parse("2021-01-28 13:14:15").Yesterday().ToDateTimeString() // 2021-01-27 13:14:15
// 明天此刻
carbon.Tomorrow().ToDateTimeString() // 2020-08-06 13:14:15
// 明天日期
carbon.Tomorrow().ToDateString() // 2020-08-06
// 明天時間
carbon.Tomorrow().ToTimeString() // 13:14:15
// 明天秒級時間戳
carbon.Tomorrow().ToTimestamp() // 1596690855
carbon.Tomorrow().ToTimestampWithSecond() // 1596690855
// 明天毫秒級時間戳
carbon.Tomorrow().ToTimestampWithMillisecond() // 1596690855000
// 明天微秒級時間戳
carbon.Tomorrow().ToTimestampWithMicrosecond() // 1596690855000000
// 明天納秒級時間戳
carbon.Tomorrow().ToTimestampWithNanosecond() // 1596690855000000000
// 指定時區的明天此刻
carbon.SetTimezone(Carbon.NewYork).Tomorrow().ToDateTimeString() // 2020-08-06 01:14:15
// 指定日期的明天此刻
carbon.Parse("2021-01-28 13:14:15").Tomorrow().ToDateTimeString() // 2021-01-29 13:14:15

建立 Carbon 例項

// 從秒級時間戳建立 Carbon 例項
carbon.CreateFromTimestamp(1596604455).ToDateTimeString() // 2020-08-05 13:14:15
// 從毫秒級時間戳建立 Carbon 例項
carbon.CreateFromTimestamp(1596604455000).ToDateTimeString() // 2020-08-05 13:14:15
// 從微秒級時間戳建立 Carbon 例項
carbon.CreateFromTimestamp(1596604455000000).ToDateTimeString() // 2020-08-05 13:14:15
// 從納級時間戳建立 Carbon 例項
carbon.CreateFromTimestamp(1596604455000000000).ToDateTimeString() // 2020-08-05 13:14:15
// 從年月日時分秒建立 Carbon 例項
carbon.CreateFromDateTime(2020, 8, 5, 13, 14, 15).ToDateTimeString() // 2020-08-05 13:14:15
// 從年月日建立 Carbon 例項(時分秒預設為當前時分秒)
carbon.CreateFromDate(2020, 8, 5).ToDateTimeString() // 2020-08-05 13:14:15
// 從時分秒建立 Carbon 例項(年月日預設為當前年月日)
carbon.CreateFromTime(13, 14, 15).ToDateTimeString() // 2020-08-05 13:14:15

將標準格式時間字串解析成 Carbon 例項

carbon.Parse("").ToDateTimeString() // 空字串
carbon.Parse("0000-00-00 00:00:00").ToDateTimeString() // 空字串
carbon.Parse("0000-00-00").ToDateTimeString() // 空字串
carbon.Parse("2020-08-05 13:14:15").ToDateTimeString() // 2020-08-05 13:14:15
carbon.Parse("2020-08-05").ToDateTimeString() // 2020-08-05 00:00:00
carbon.Parse("20200805131415").ToDateTimeString() // 2020-08-05 13:14:15
carbon.Parse("20200805").ToDateTimeString() // 2020-08-05 00:00:00
carbon.Parse("2020-08-05T13:14:15+08:00").ToDateTimeString() // 2020-08-05 00:00:00

將特殊格式時間字串解析成 Carbon 例項

carbon.ParseByFormat("2020|08|05 13|14|15", "Y|m|d H|i|s").ToDateTimeString // 2020-08-05 13:14:15
carbon.ParseByFormat("It is 2020-08-05 13:14:15", "It is Y-m-d H:i:s").ToDateTimeString // 2020-08-05 13:14:15
carbon.ParseByFormat("今天是 2020年08月05日13時14分15秒", "今天是 Y年m月d日H時i分s秒").ToDateTimeString // 2020-08-05 13:14:15

將佈局時間字串解析成 Carbon 例項

carbon.ParseByLayout("2020|08|05 13|14|15", "2006|01|02 15:04:05").ToDateTimeString // 2020-08-05 13:14:15
carbon.ParseByLayout("It is 2020-08-05 13:14:15", "It is 2006-01-02 15:04:05").ToDateTimeString // 2020-08-05 13:14:15
carbon.ParseByLayout("今天是 2020年08月05日13時14分15秒", "今天是 2006年01月02日15時04分05秒").ToDateTimeString() // 2020-08-05 13:14:15

carbon 和 time.Time 互轉

// 將 time.Time 轉換成 Carbon
carbon.Time2Carbon(time.Now())
// 將 Carbon 轉換成 time.Time
carbon.Now().Carbon2Time() 或 carbon.Now().Time

時間設定

// 設定時區
carbon.SetTimezone(carbon.PRC).Now().ToDateTimeString() // 2020-08-05 13:14:15
carbon.SetTimezone(carbon.Tokyo).Now().ToDateTimeString() // 2020-08-05 14:14:15
carbon.SetTimezone(carbon.Tokyo).SetTimezone(carbon.PRC).Now().ToDateTimeString() // 2020-08-05 13:14:15
// 設定年
carbon.Parse("2019-08-05").SetYear(2020).ToDateString() // 2020-08-05
carbon.Parse("2020-02-29").SetYear(2019).ToDateString() // 2019-03-01
// 設定月
carbon.Parse("2020-01-31").SetMonth(2).ToDateString() // 2020-03-02
carbon.Parse("2020-08-05").SetMonth(2).ToDateString() // 2020-02-05
// 設定日
carbon.Parse("2019-08-05").SetDay(31).ToDateString() // 2020-08-31
carbon.Parse("2020-02-01").SetDay(31).ToDateString() // 2020-03-02
// 設定時
carbon.Parse("2020-08-05 13:14:15").SetHour(10).ToDateTimeString() // 2020-08-05 10:14:15
carbon.Parse("2020-08-05 13:14:15").SetHour(24).ToDateTimeString() // 2020-08-06 00:14:15
// 設定分
carbon.Parse("2020-08-05 13:14:15").SetMinute(10).ToDateTimeString() // 2020-08-05 13:10:15
carbon.Parse("2020-08-05 13:14:15").SetMinute(60).ToDateTimeString() // 2020-08-05 14:00:15
// 設定秒
carbon.Parse("2020-08-05 13:14:15").SetSecond(10).ToDateTimeString() // 2020-08-05 13:14:10
carbon.Parse("2020-08-05 13:14:15").SetSecond(60).ToDateTimeString() // 2020-08-05 13:15:00

更多時區常量請檢視const.go檔案

開始時間、結束時間

// 本年開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfYear().ToDateTimeString() // 2020-01-01 00:00:00
// 本年結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfYear().ToDateTimeString() // 2020-12-31 23:59:59
// 本月開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfMonth().ToDateTimeString() // 2020-08-01 00:00:00
// 本月結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfMonth().ToDateTimeString() // 2020-08-31 23:59:59
// 本週開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfWeek().ToDateTimeString() // 2020-08-03 00:00:00
// 本週結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfWeek().ToDateTimeString() // 2020-08-09 23:59:59
// 本日開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfDay().ToDateTimeString() // 2020-08-05 00:00:00
// 本日結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfDay().ToDateTimeString() // 2020-08-05 23:59:59
// 本小時開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfHour().ToDateTimeString() // 2020-08-05 13:00:00
// 本小時結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfHour().ToDateTimeString() // 2020-08-05 13:59:59
// 本分鐘開始時間
carbon.Parse("2020-08-05 13:14:15").StartOfMinute().ToDateTimeString() // 2020-08-05 13:14:00
// 本分鐘結束時間
carbon.Parse("2020-08-05 13:14:15").EndOfMinute().ToDateTimeString() // 2020-08-05 13:14:59

時間旅行

// 三世紀後
carbon.Parse("2020-02-29 13:14:15").AddCenturies(3).ToDateTimeString() // 2320-02-29 13:14:15
// 三世紀後(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").AddCenturiesNoOverflow(3).ToDateTimeString() // 2320-02-29 13:14:15
// 一世紀後
carbon.Parse("2020-02-29 13:14:15").AddCentury().ToDateTimeString() // 2120-02-29 13:14:15
// 一世紀後(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").AddCenturyNoOverflow().ToDateTimeString() // 2120-02-29 13:14:15
// 三世紀前
carbon.Parse("2020-02-29 13:14:15").SubCenturies(3).ToDateTimeString() // 1720-02-29 13:14:15
// 三世紀前(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").SubCenturiesNoOverflow(3).ToDateTimeString() // 1720-02-29 13:14:15
// 一世紀前
carbon.Parse("2020-02-29 13:14:15").SubCentury().ToDateTimeString() // 1920-02-29 13:14:15
// 一世紀前(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").SubCenturyNoOverflow().ToDateTimeString() // 1920-02-29 13:14:15
// 三年後
carbon.Parse("2020-02-29 13:14:15").AddYears(3).ToDateTimeString() // 2023-03-01 13:14:15
// 三年後(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").AddYearsNoOverflow(3).ToDateTimeString() // 2023-02-28 13:14:15
// 一年後
carbon.Parse("2020-02-29 13:14:15").AddYear().ToDateTimeString() // 2021-03-01 13:14:15
// 一年後(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").AddYearNoOverflow().ToDateTimeString() // 2021-02-28 13:14:15
// 三年前
carbon.Parse("2020-02-29 13:14:15").SubYears(3).ToDateTimeString() // 2017-03-01 13:14:15
// 三年前(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").SubYearsNoOverflow(3).ToDateTimeString() // 2017-02-28 13:14:15
// 一年前
carbon.Parse("2020-02-29 13:14:15").SubYear().ToDateTimeString() // 2019-03-01 13:14:15
// 一年前(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").SubYearNoOverflow().ToDateTimeString() // 2019-02-28 13:14:15
// 三季度後
carbon.Parse("2019-08-31 13:14:15").AddQuarters(3).ToDateTimeString() // 2019-03-02 13:14:15
// 三季度後(月份不溢位)
carbon.Parse("2019-08-31 13:14:15").AddQuartersNoOverflow(3).ToDateTimeString() // 2019-02-29 13:14:15
// 一季度後
carbon.Parse("2019-11-30 13:14:15").AddQuarter().ToDateTimeString() // 2020-03-01 13:14:15
// 一季度後(月份不溢位)
carbon.Parse("2019-11-30 13:14:15").AddQuarterNoOverflow().ToDateTimeString() // 2020-02-29 13:14:15
// 三季度前
carbon.Parse("2019-08-31 13:14:15").SubQuarters(3).ToDateTimeString() // 2019-03-03 13:14:15
// 三季度前(月份不溢位)
carbon.Parse("2019-08-31 13:14:15").SubQuartersNoOverflow(3).ToDateTimeString() // 2019-02-28 13:14:15
// 一季度前
carbon.Parse("2020-05-31 13:14:15").SubQuarter().ToDateTimeString() // 2020-03-02 13:14:15
// 一季度前(月份不溢位)
carbon.Parse("2020-05-31 13:14:15").SubQuarterNoOverflow().ToDateTimeString() // 2020-02-29 13:14:15
// 三月後
carbon.Parse("2020-02-29 13:14:15").AddMonths(3).ToDateTimeString() // 2020-05-29 13:14:15
// 三月後(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").AddMonthsNoOverflow(3).ToDateTimeString() // 2020-05-29 13:14:15
// 一月後
carbon.Parse("2020-01-31 13:14:15").AddMonth().ToDateTimeString() // 2020-03-02 13:14:15
// 一月後(月份不溢位)
carbon.Parse("2020-01-31 13:14:15").AddMonthNoOverflow().ToDateTimeString() // 2020-02-29 13:14:15
// 三月前
carbon.Parse("2020-02-29 13:14:15").SubMonths(3).ToDateTimeString() // 2019-11-29 13:14:15
// 三月前(月份不溢位)
carbon.Parse("2020-02-29 13:14:15").SubMonthsNoOverflow(3).ToDateTimeString() // 2019-11-29 13:14:15
// 一月前
carbon.Parse("2020-03-31 13:14:15").SubMonth().ToDateTimeString() // 2020-03-02 13:14:15
// 一月前(月份不溢位)
carbon.Parse("2020-03-31 13:14:15").SubMonthNoOverflow().ToDateTimeString() // 2020-02-29 13:14:15
// 三週後
carbon.Parse("2020-02-29 13:14:15").AddWeeks(3).ToDateTimeString() // 2020-03-21 13:14:15
// 一週後
carbon.Parse("2020-02-29 13:14:15").AddWeek().ToDateTimeString() // 2020-03-07 13:14:15
// 三週前
carbon.Parse("2020-02-29 13:14:15").SubWeeks(3).ToDateTimeString() // 2020-02-08 13:14:15
// 一週前
carbon.Parse("2020-02-29 13:14:15").SubWeek().ToDateTimeString() // 2020-02-22 13:14:15
// 三天後
carbon.Parse("2020-08-05 13:14:15").AddDays(3).ToDateTimeString() // 2020-08-08 13:14:15
// 一天後
carbon.Parse("2020-08-05 13:14:15").AddDay().ToDateTimeString() // 2020-08-05 13:14:15
// 三天前
carbon.Parse("2020-08-05 13:14:15").SubDays(3).ToDateTimeString() // 2020-08-02 13:14:15
// 一天前
carbon.Parse("2020-08-05 13:14:15").SubDay().ToDateTimeString() // 2020-08-04 13:14:15
// 三小時後
carbon.Parse("2020-08-05 13:14:15").AddHours(3).ToDateTimeString() // 2020-08-05 16:14:15
// 二小時半後
carbon.Parse("2020-08-05 13:14:15").AddDuration("2.5h").ToDateTimeString() // 2020-08-05 15:44:15
carbon.Parse("2020-08-05 13:14:15").AddDuration("2h30m").ToDateTimeString() // 2020-08-05 15:44:15
// 一小時後
carbon.Parse("2020-08-05 13:14:15").AddHour().ToDateTimeString() // 2020-08-05 14:14:15
// 三小時前
carbon.Parse("2020-08-05 13:14:15").SubHours(3).ToDateTimeString() // 2020-08-05 10:14:15
// 二小時半前
carbon.Parse("2020-08-05 13:14:15").SubDuration("2.5h").ToDateTimeString() // 2020-08-05 10:44:15
carbon.Parse("2020-08-05 13:14:15").SubDuration("2h30m").ToDateTimeString() // 2020-08-05 10:44:15
// 一小時前
carbon.Parse("2020-08-05 13:14:15").SubHour().ToDateTimeString() // 2020-08-05 12:14:15
// 三分鐘後
carbon.Parse("2020-08-05 13:14:15").AddMinutes(3).ToDateTimeString() // 2020-08-05 13:17:15
// 二分鐘半後
carbon.Parse("2020-08-05 13:14:15").AddDuration("2.5m").ToDateTimeString() // 2020-08-05 13:16:45
carbon.Parse("2020-08-05 13:14:15").AddDuration("2m30s").ToDateTimeString() // 2020-08-05 13:16:45
// 一分鐘後
carbon.Parse("2020-08-05 13:14:15").AddMinute().ToDateTimeString() // 2020-08-05 13:15:15
// 三分鐘前
carbon.Parse("2020-08-05 13:14:15").SubMinutes(3).ToDateTimeString() // 2020-08-05 13:11:15
// 二分鐘半前
carbon.Parse("2020-08-05 13:14:15").SubDuration("2.5m").ToDateTimeString() // 2020-08-05 13:11:45
carbon.Parse("2020-08-05 13:14:15").SubDuration("2m30s").ToDateTimeString() // 2020-08-05 13:11:45
// 一分鐘前
carbon.Parse("2020-08-05 13:14:15").SubMinute().ToDateTimeString() // 2020-08-05 13:13:15
// 三秒鐘後
carbon.Parse("2020-08-05 13:14:15").AddSeconds(3).ToDateTimeString() // 2020-08-05 13:14:18
// 二秒鐘半後
carbon.Parse("2020-08-05 13:14:15").AddDuration("2.5s").ToDateTimeString() // 2020-08-05 13:14:17
// 一秒鐘後
carbon.Parse("2020-08-05 13:14:15").AddSecond().ToDateTimeString() // 2020-08-05 13:14:16
// 三秒鐘前
carbon.Parse("2020-08-05 13:14:15").SubSeconds(3).ToDateTimeString() // 2020-08-05 13:14:12
// 二秒鐘半前
carbon.Parse("2020-08-05 13:14:15").SubDuration("2.5s").ToDateTimeString() // 2020-08-05 13:14:12
// 一秒鐘前
carbon.Parse("2020-08-05 13:14:15").SubSecond().ToDateTimeString() // 2020-08-05 13:14:14

時間差

// 相差多少周
carbon.Parse("2020-08-05 13:14:15").DiffInWeeks(carbon.Parse("2020-07-28 13:14:15")) // -1
// 相差多少周（絕對值）
carbon.Parse("2020-08-05 13:14:15").DiffInWeeksWithAbs(carbon.Parse("2020-07-28 13:14:15")) // 1
// 相差多少天
carbon.Parse("2020-08-05 13:14:15").DiffInDays(carbon.Parse("2020-08-04 13:14:15")) // -1
// 相差多少天（絕對值）
carbon.Parse("2020-08-05 13:14:15").DiffInDaysWithAbs(carbon.Parse("2020-08-04 13:14:15")) // 1
// 相差多少小時
carbon.Parse("2020-08-05 13:14:15").DiffInHours(carbon.Parse("2020-08-05 12:14:15")) // -1
// 相差多少小時（絕對值）
carbon.Parse("2020-08-05 13:14:15").DiffInHoursWithAbs(carbon.Parse("2020-08-05 12:14:15")) // 1
// 相差多少分
carbon.Parse("2020-08-05 13:14:15").DiffInMinutes(carbon.Parse("2020-08-05 13:13:15")) // -1
// 相差多少分（絕對值）
carbon.Parse("2020-08-05 13:14:15").DiffInMinutesWithAbs(carbon.Parse("2020-08-05 13:13:15")) // 1
// 相差多少秒
carbon.Parse("2020-08-05 13:14:15").DiffInSeconds(carbon.Parse("2020-08-05 13:14:14")) // -1
// 相差多少秒（絕對值）
carbon.Parse("2020-08-05 13:14:15").DiffInSecondsWithAbs(carbon.Parse("2020-08-05 13:14:14")) // 1

時間比較

// 是否大於
carbon.Parse("2020-08-05 13:14:15").Gt(carbon.Parse("2020-08-04 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Gt(carbon.Parse("2020-08-05 13:14:15")) // false
carbon.Parse("2020-08-05 13:14:15").Compare(">", carbon.Parse("2020-08-04 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare(">", carbon.Parse("2020-08-05 13:14:15")) // false
// 是否小於
carbon.Parse("2020-08-05 13:14:15").Lt(carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Lt(carbon.Parse("2020-08-05 13:14:15")) // false
carbon.Parse("2020-08-05 13:14:15").Compare("<", carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare("<", carbon.Parse("2020-08-05 13:14:15")) // false
// 是否等於
carbon.Parse("2020-08-05 13:14:15").Eq(carbon.Parse("2020-08-05 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Eq(carbon.Parse("2020-08-05 13:14:00")) // false
carbon.Parse("2020-08-05 13:14:15").Compare("=", carbon.Parse("2020-08-05 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare("=", carbon.Parse("2020-08-05 13:14:00")) // false
// 是否不等於
carbon.Parse("2020-08-05 13:14:15").Ne(carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Ne(carbon.Parse("2020-08-05 13:14:15")) // false
carbon.Parse("2020-08-05 13:14:15").Compare("!=", carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare("<>", carbon.Parse("2020-08-05 13:14:15")) // false
// 是否大於等於
carbon.Parse("2020-08-05 13:14:15").Gte(carbon.Parse("2020-08-04 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Gte(carbon.Parse("2020-08-05 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare(">=", carbon.Parse("2020-08-04 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare(">=", carbon.Parse("2020-08-05 13:14:15")) // true
// 是否小於等於
carbon.Parse("2020-08-05 13:14:15").Lte(carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Lte(carbon.Parse("2020-08-05 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare("<=", carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").Compare("<=", carbon.Parse("2020-08-05 13:14:15")) // true
// 是否在兩個時間之間(不包括這兩個時間)
carbon.Parse("2020-08-05 13:14:15").Between(carbon.Parse("2020-08-05 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // false
carbon.Parse("2020-08-05 13:14:15").Between(carbon.Parse("2020-08-04 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // true
// 是否在兩個時間之間(包括開始時間)
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedStartTime(carbon.Parse("2020-08-05 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedStartTime(carbon.Parse("2020-08-04 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // true
// 是否在兩個時間之間(包括結束時間)
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedEndTime(carbon.Parse("2020-08-04 13:14:15"), carbon.Parse("2020-08-05 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedEndTime(carbon.Parse("2020-08-04 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // true
// 是否在兩個時間之間(包括這兩個時間)
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedBoth(carbon.Parse("2020-08-05 13:14:15"), carbon.Parse("2020-08-06 13:14:15")) // true
carbon.Parse("2020-08-05 13:14:15").BetweenIncludedBoth(carbon.Parse("2020-08-04 13:14:15"), carbon.Parse("2020-08-05 13:14:15")) // true

時間判斷

// 是否是零值時間
carbon.Parse("").IsZero() // true
carbon.Parse("0").IsZero() // true
carbon.Parse("0000-00-00 00:00:00").IsZero() // true
carbon.Parse("0000-00-00").IsZero() // true
carbon.Parse("00:00:00").IsZero() // true
carbon.Parse("2020-08-05 00:00:00").IsZero() // false
carbon.Parse("2020-08-05").IsZero() // false
// 是否是當前時間
carbon.Now().IsNow() // true
// 是否是未來時間
carbon.Tomorrow().IsFuture() // true
// 是否是過去時間
carbon.Yesterday().IsPast() // true
// 是否是閏年
carbon.Parse("2020-08-05 13:14:15").IsLeapYear() // true
// 是否是長年
carbon.Parse("2020-08-05 13:14:15").IsLongYear() // true
// 是否是一月
carbon.Parse("2020-08-05 13:14:15").IsJanuary() // false
// 是否是二月
carbon.Parse("2020-08-05 13:14:15").IsFebruary() // false
// 是否是三月
carbon.Parse("2020-08-05 13:14:15").IsMarch() // false
// 是否是四月
carbon.Parse("2020-08-05 13:14:15").IsApril()  // false
// 是否是五月
carbon.Parse("2020-08-05 13:14:15").IsMay() // false
// 是否是六月
carbon.Parse("2020-08-05 13:14:15").IsJune() // false
// 是否是七月
carbon.Parse("2020-08-05 13:14:15").IsJuly() // false
// 是否是八月
carbon.Parse("2020-08-05 13:14:15").IsAugust() // false
// 是否是九月
carbon.Parse("2020-08-05 13:14:15").IsSeptember() // true
// 是否是十月
carbon.Parse("2020-08-05 13:14:15").IsOctober() // false
// 是否是十一月
carbon.Parse("2020-08-05 13:14:15").IsNovember() // false
// 是否是十二月
carbon.Parse("2020-08-05 13:14:15").IsDecember() // false
// 是否是週一
carbon.Parse("2020-08-05 13:14:15").IsMonday() // false
// 是否是週二
carbon.Parse("2020-08-05 13:14:15").IsTuesday() // true
// 是否是週三
carbon.Parse("2020-08-05 13:14:15").IsWednesday() // false
// 是否是週四
carbon.Parse("2020-08-05 13:14:15").IsThursday()  // false
// 是否是週五
carbon.Parse("2020-08-05 13:14:15").IsFriday() // false
// 是否是週六
carbon.Parse("2020-08-05 13:14:15").IsSaturday() // false
// 是否是週日
carbon.Parse("2020-08-05 13:14:15").IsSunday() // false
// 是否是工作日
carbon.Parse("2020-08-05 13:14:15").IsWeekday() // false
// 是否是週末
carbon.Parse("2020-08-05 13:14:15").IsWeekend() // true
// 是否是昨天
carbon.Parse("2020-08-04 13:14:15").IsYesterday() // true
carbon.Parse("2020-08-04 00:00:00").IsYesterday() // true
carbon.Parse("2020-08-04").IsYesterday() // true
// 是否是今天
carbon.Parse("2020-08-05 13:14:15").IsToday() // true
carbon.Parse("2020-08-05 00:00:00").IsToday() // true
carbon.Parse("2020-08-05").IsToday() // true
// 是否是明天
carbon.Parse("2020-08-06 13:14:15").IsTomorrow() // true
carbon.Parse("2020-08-06 00:00:00").IsTomorrow() // true
carbon.Parse("2020-08-06").IsTomorrow() // true

時間輸出

// 輸出秒級時間戳
carbon.Parse("2020-08-05 13:14:15").ToTimestamp() // 1596604455
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithSecond() // 1596604455
// 輸出毫秒級時間戳
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithMillisecond() // 1596604455000
// 輸出微秒級時間戳
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithMicrosecond() // 1596604455000000
// 輸出納秒級時間戳
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithNanosecond() // 1596604455000000000
// 輸出日期時間字串
carbon.Parse("2020-08-05 13:14:15").ToDateTimeString() // 2020-08-05 13:14:15
// 輸出日期字串
carbon.Parse("2020-08-05 13:14:15").ToDateString() // 2020-08-05
// 輸出時間字串
carbon.Parse("2020-08-05 13:14:15").ToTimeString() // 13:14:15
// 輸出Ansic格式字串
carbon.Parse("2020-08-05 13:14:15").ToAnsicString() // Wed Aug  5 13:14:15 2020
// 輸出Atom字串
carbon.Parse("2020-08-05 13:14:15").ToAtomString() // Wed Aug  5 13:14:15 2020
// 輸出UnixDate格式字串
carbon.Parse("2020-08-05 13:14:15").ToUnixDateString() // Wed Aug  5 13:14:15 CST 2020
// 輸出RubyDate格式字串
carbon.Parse("2020-08-05 13:14:15").ToRubyDateString() // Wed Aug 05 13:14:15 +0800 2020
// 輸出Kitchen格式字串
carbon.Parse("2020-08-05 13:14:15").ToKitchenString() // 1:14PM
// 輸出Cookie格式字串
carbon.Parse("2020-08-05 13:14:15").ToCookieString() // Wednesday, 05-Aug-2020 13:14:15 CST
// 輸出DayDateTime格式字串
carbon.Parse("2020-08-05 13:14:15").ToDayDateTimeString() // Wed, Aug 5, 2020 1:14 PM
// 輸出RSS格式字串
carbon.Parse("2020-08-05 13:14:15").ToRssString() // Wed, 05 Aug 2020 13:14:15 +0800
// 輸出W3C格式字串
carbon.Parse("2020-08-05 13:14:15").ToW3cString() // 2020-08-05T13:14:15+08:00
// 輸出RFC822格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc822String() // 05 Aug 20 13:14 CST
// 輸出RFC822Z格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc822zString() // 05 Aug 20 13:14 +0800
// 輸出RFC850格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc850String() // Wednesday, 05-Aug-20 13:14:15 CST
// 輸出RFC1036格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc1036String() // Wed, 05 Aug 20 13:14:15 +0800
// 輸出RFC1123格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc1123String() // Wed, 05 Aug 2020 13:14:15 CST
// 輸出RFC2822格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc2822String() // Wed, 05 Aug 2020 13:14:15 +0800
// 輸出RFC3339格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc3339String() // 2020-08-05T13:14:15+08:00
// 輸出RFC7231格式字串
carbon.Parse("2020-08-05 13:14:15").ToRfc7231String() // Wed, 05 Aug 2020 05:14:15 GMT
// 輸出字串
carbon.Parse("2020-08-05 13:14:15").ToString() // 2020-08-05 13:14:15 +0800 CST
// 輸出格式化字串，Format()是ToFormatString()的簡寫
carbon.Parse("2020-08-05 13:14:15").ToFormatString("YmdHis") // 20200805131415
carbon.Parse("2020-08-05 13:14:15").ToFormatString("Y年m月d H時i分s秒") // 2020年08月05日 13時14分15秒
carbon.Parse("2020-08-05 13:14:15").Format("YmdHis") // 20200805131415
carbon.Parse("2020-08-05 13:14:15").Format("l jS of F Y h:i:s A") // Wednesday 5th of August 2020 01:14:15 PM

更多格式化輸出符號請檢視附錄格式化符號表

時間獲取

// 獲取本年總天數
carbon.Parse("2019-08-05 13:14:15").DaysInYear() // 365
carbon.Parse("2020-08-05 13:14:15").DaysInYear() // 366
// 獲取本月總天數
carbon.Parse("2020-02-01 13:14:15").DaysInMonth() // 29
carbon.Parse("2020-04-01 13:14:15").DaysInMonth() // 30
carbon.Parse("2020-08-01 13:14:15").DaysInMonth() // 31
// 獲取本年第幾天
carbon.Parse("2020-08-05 13:14:15").DayOfYear() // 218
// 獲取本年第幾周
carbon.Parse("2019-12-31 13:14:15").WeekOfYear() // 1
carbon.Parse("2020-08-05 13:14:15").WeekOfYear() // 32
// 獲取本月第幾天
carbon.Parse("2020-08-05 13:14:15").DayOfMonth() // 5
// 獲取本月第幾周
carbon.Parse("2020-08-05 13:14:15").WeekOfMonth() // 1
// 獲取本週第幾天
carbon.Parse("2020-08-05 13:14:15").DayOfWeek() // 3
// 獲取當前年
carbon.Parse("2020-08-05 13:14:15").Year() // 2020
// 獲取當前季度
carbon.Parse("2020-08-05 13:14:15").Quarter() // 3
// 獲取當前月
carbon.Parse("2020-08-05 13:14:15").Month() // 8
// 獲取當前日
carbon.Parse("2020-08-05 13:14:15").Day() // 5
// 獲取當前時
carbon.Parse("2020-08-05 13:14:15").Hour() // 13
// 獲取當前分
carbon.Parse("2020-08-05 13:14:15").Minute() // 14
// 獲取當前秒
carbon.Parse("2020-08-05 13:14:15").Second() // 15
// 獲取當前毫秒
carbon.Parse("2020-08-05 13:14:15").Millisecond() // 1596604455000
// 獲取當前微秒
carbon.Parse("2020-08-05 13:14:15").Microsecond() // 1596604455000000
// 獲取當前納秒
carbon.Parse("2020-08-05 13:14:15").Nanosecond() // 1596604455000000000
// 獲取時區
carbon.SetTimezone(carbon.PRC).Timezone() // PRC
carbon.SetTimezone(carbon.Tokyo).Timezone() // Asia/Tokyo
// 獲取年齡
carbon.Parse("2002-01-01 13:14:15").Age() // 17
carbon.Parse("2002-12-31 13:14:15").Age() // 18

關於第幾周的計算如有疑惑請檢視 ISO8601 標準

農曆支援

// 獲取生肖年
carbon.Parse("2020-08-05 13:14:15").ToAnimalYear() // 鼠
// 獲取農曆年
carbon.Parse("2020-08-05 13:14:15").ToLunarYear() // 庚子
// 是否是鼠年
carbon.Parse("2020-08-05 13:14:15").IsYearOfRat() // true
// 是否是牛年
carbon.Parse("2020-08-05 13:14:15").IsYearOfOx() // false
// 是否是虎年
carbon.Parse("2020-08-05 13:14:15").IsYearOfTiger() // false
// 是否是兔年
carbon.Parse("2020-08-05 13:14:15").IsYearOfRabbit() // false
// 是否是龍年
carbon.Parse("2020-08-05 13:14:15").IsYearOfDragon() // false
// 是否是蛇年
carbon.Parse("2020-08-05 13:14:15").IsYearOfSnake() // false
// 是否是馬年
carbon.Parse("2020-08-05 13:14:15").IsYearOfHorse() // false
// 是否是羊年
carbon.Parse("2020-08-05 13:14:15").IsYearOfGoat() // false
// 是否是猴年
carbon.Parse("2020-08-05 13:14:15").IsYearOfMonkey() // false
// 是否是雞年
carbon.Parse("2020-08-05 13:14:15").IsYearOfRooster() // false
// 是否是狗年
carbon.Parse("2020-08-05 13:14:15").IsYearOfDog() // false
// 是否是豬年
carbon.Parse("2020-08-05 13:14:15").IsYearOfPig() // false

資料庫支援

假設資料表為 users，欄位有 id(int)、name(varchar)、age(int)、birthday(datetime)、graduated_at(datetime)、created_at(datetime)、updated_at(datetime)、date_time1(datetime)、date_time2(datetime)、date_time3(datetime)、date_time4(datetime)

定義模型

type UserModel struct {
 ID  int64  `json:"id"` Name string `json:"name"` Age int `json:"age"` Birthday carbon.ToDateTimeString `json:"birthday"` GraduatedAt carbon.ToDateString `json:"graduated_at"` CreatedAt carbon.ToTimeString `json:"created_at"` UpdatedAt carbon.ToTimestamp `json:"updated_at"` DateTime1 carbon.ToTimestampWithSecond `json:"date_time1"` DateTime2 carbon.ToTimestampWithMillisecond `json:"date_time2"` DateTime3 carbon.ToTimestampWithMicrosecond `json:"date_time3"` DateTime4 carbon.ToTimestampWithNanosecond `json:"date_time4"`}

例項化模型

user := UserModel {
 ID: 1153, Name: "勾國印", Age: 18, Birthday: carbon.ToDateTimeString{carbon.Now().SubYears(18)}, GraduatedAt: carbon.ToDateString{carbon.Parse("2012-09-09")}, CreatedAt: carbon.ToTimeString{carbon.Now()}, UpdatedAt: carbon.ToTimestamp{carbon.Now()}, DateTime1: carbon.ToTimestampWithSecond{carbon.Now()}, DateTime2: carbon.ToTimestampWithMillisecond{carbon.Now()}, DateTime3: carbon.ToTimestampWithMicrosecond{carbon.Now()}, DateTime4: carbon.ToTimestampWithNanosecond{carbon.Now()},}

輸出模型欄位

user.ID // 1153
user.Name // 勾國印
user.Age // 18
user.Birthday.ToDateTimeString() // 2012-08-05 13:14:15
user.GraduatedAt.ToDateString() // 2012-09-09
user.CreatedAt.ToTimeString() // 13:14:15
user.UpdatedAt.ToTimestamp() // 1596604455
user.DateTime1.ToTimestampWithSecond() // 1596604455
user.DateTime2.ToTimestampWithMillisecond() // 1596604455000
user.DateTime3.ToTimestampWithMicrosecond() // 1596604455000000
user.DateTime4.ToTimestampWithNanosecond() // 1596604455000000000

JSON 輸出模型

data, _ := json.Marshal(&user)
fmt.Print(string(data))
// 輸出
{
 "id": 1153, "name": "勾國印", "age": 18, "birthday": "2012-08-05 13:14:15", "graduated_at": "2012-09-09", "created_at": "13:14:15", "updated_at": 1596604455, "date_time1": 1596604455, "date_time2": 1596604455000, "date_time3": 1596604455000000, "date_time4": 1596604455000000000,}

輸出自定義格式

// 定義輸出格式
type ToRssString struct {
 carbon.Carbon}
// 定義模型
type UserModel struct {
 Birthday carbon.ToRssString `json:"birthday"`}
// 例項化模型
user := UserModel {
 Birthday: carbon.ToRssString{carbon.Now()},}
// 重寫MarshalJSON方法
func (c ToRssString) MarshalJSON() ([]byte, error) {
 return []byte(fmt.Sprintf(`"%s"`, c.ToRssString())), nil}
// json.Marshal(&user)輸出
{
 "birthday": "Wed, 05 Aug 2020 13:14:15 +0800",}

錯誤處理

如果有多個錯誤發生，只返回第一個錯誤資訊，前一個錯誤排除後才返回下一個錯誤資訊

場景一

c := carbon.SetTimezone(PRC).Parse("123456")
if c.Error != nil {
 // 錯誤處理... fmt.Println(c.Error)}
fmt.Println(c.ToDateTimeString())
// 輸出
the value "123456" can't parse string as time

場景二

c := carbon.SetTimezone("XXXX").Parse("2020-08-05")
if c.Error != nil {
 // 錯誤處理... fmt.Println(c.Error)}
fmt.Println(c.ToDateTimeString())
// 輸出
invalid timezone "XXXX", please see the $GOROOT/lib/time/zoneinfo.zip file for all valid timezone

場景三

c := carbon.SetTimezone("XXXX").Parse("12345678")
if c.Error != nil {
 // 錯誤處理... fmt.Println(c.Error)}
fmt.Println(c.ToDateTimeString())
// 輸出
invalid timezone "XXXX", please see the $GOROOT/lib/time/zoneinfo.zip file for all valid timezone

建議使用 SetTimezone()、Parse()、ParseByFormat()、AddDuration()、SubDuration() 等方法時先進行錯誤處理判斷，除非你能確保傳入引數無誤

附錄

格式化符號表

符號	描述	長度	範圍	示例
d	月份中的第幾天，有前導零	2	01-31	05
D	縮寫單詞表示的周幾	3	Mon-Sun	Wed
j	月份中的第幾天，沒有前導零	1/2	1-31	5
S	月份中的第幾天，英文縮寫字尾，一般和 j 配合使用	2	st/nd/rd/th	th
l	完整單詞表示的周幾	-	Monday-Sunday	Wednesday
F	完整單詞表示的月份	-	January-December	August
m	數字表示的月份，有前導零	2	01-12	08
M	縮寫單詞表示的月份	3	Jan-Dec	Aug
n	數字表示的月份，沒有前導零	1/2	1-12	8
y	年份，有前導零	2	00-99	20
Y	年份	4	0000-9999	2020
a	小寫的上下午縮寫字母	2	am/pm	pm
A	大寫的上下午縮寫字母	2	AM/PM	PM
g	小時，12 小時格式，沒有前導零	1/2	1-12	1
G	小時，24 小時格式，沒有前導零	1/2	0-23	15
h	小時，12 小時格式，有前導零	2	00-11	03
H	小時，24 小時格式，有前導零	2	00-23	15
i	分鐘，有前導零	2	01-59	14
s	秒數，有前導零	2	01-59	15
c	ISO8601 格式的日期	-	-	2020-08-05T15:19:21+00:00
r	RFC822 格式的日期	-	-	Thu, 21 Dec 2020 16:01:07 +0200
O	與格林威治時間相差的小時數	-	-	+0200
P	與格林威治時間相差的小時數，小時和分鐘之間有冒號分隔	-	-	+02:00
T	時區縮寫	-	-	EST
W	ISO-8601 格式數字表示的年份中的第幾周	1/2	1-52	42
N	ISO-8601 格式數字表示的星期中的第幾天	1	1-7	6
L	是否為閏年，如果是閏年為 1，否則為 0	1	0-1	1
U	秒級時間戳	10	-	1611818268
u	毫秒	-	-	999
w	數字表示的周幾	1	0-6	6
t	月份中的總天數	2	28-31	30
z	年份中的第幾天	1/2/3	0-365	15
e	時區標識	-	-	America/New_York

更多原創文章乾貨分享，請關注公眾號

加微信實戰群請加微信(註明:實戰群)：gocnio

golang版carbon日期時間處理庫,PHP開發者的福利
2020-09-07
GolangPHP
go-carbon 1.1.0版本釋出了，php carbon時間處理庫的golang版，增加對gorm的支援
2020-09-10
PHPGolangORM
go-carbon 2.1.9 版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-08-03
Golang
go-carbon 2.1.6 版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-05-09
Golang
go-carbon 2.2.0 版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-10-27
Golang
go-carbon 2.1.1 版本釋出，輕量級、語義化、對開發者友好的golang時間處理庫
2022-04-18
Golang
go-carbon 2.1.8 版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-05-24
Golang
go-carbon 2.1.7 版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-05-20
Golang
Golang每日一庫之regex
2023-05-10
Golang
Golang每日一庫之bcrypt
2023-04-27
Golang
go-carbon 2.2.2版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-11-07
Golang
go-carbon 2.2.1版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-10-31
Golang
go-carbon 2.1.2版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-04-20
Golang
go-carbon 2.1.4版本釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-04-25
Golang
Go 每日一庫之 godotenv
2020-02-12
Go
Go 每日一庫之 cobra
2020-01-18
Go
Go 每日一庫之 jj
2020-03-26
Go
Go 每日一庫之 gopsutil
2020-04-06
Go
Go 每日一庫之 validator
2020-04-05
Go
Go 每日一庫之 bitset
2022-07-17
Go
Go 每日一庫之 go-flags
2020-01-13
Go
（轉）Go 每日一庫之 cast
2024-05-22
GoAST
go-carbon v2.1.5 五一特別版釋出，輕量級、語義化、對開發者友好的Golang時間處理庫
2022-05-05
Golang
字串和日期時間的處理
2020-11-30
字串
日期時間處理包 Carbon
2018-10-10
教你如何優雅處理Golang中的異常
2023-03-04
Golang
[譯]Go如何優雅的處理異常
2019-05-29
Go
一個日期處理類庫moment.js
2018-04-01
JS
6 個 Python 的日期時間庫
2018-05-25
Python
Pandas中時間和日期處理
2019-02-16
Laravel日期時間處理包 Carbon
2020-10-02
Laravel
Golang 一日一庫之jwt-go
2023-04-11
GolangJWT
NPM酷庫：moment，時間物件處理
2019-02-16
NPM物件
Python3優雅操作-時間處理與定時任務
2018-12-07
Python
Golang 圖片處理 — image 庫
2021-07-02
Golang
LocalDateTime替代Date操作處理日期時間
2024-07-21
LDA
Java8新特性探索之新日期時間庫
2020-12-14
Java
如何優雅的在Golang中進行錯誤處理
2019-07-26
Golang