Go-carbon,a simple,semantic and developer-friendly golang package for datetime

Carbon

A simple,semantic and developer-friendly golang package for datetime

If you think it is helpful, please give me a star

Installation

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

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

Usage and example

The default timezone is Local, assuming the current time is 2020-08-05 13:14:15

Yesterday,today and tomorrow
// Datetime of today
carbon.Now().ToDateTimeString() // 2020-08-05 13:14:15
// Date of today
carbon.Now().ToDateString() // 2020-08-05
// Time of today
carbon.Now().ToTimeString() // 13:14:15
// Timestamp with second of today
carbon.Now().ToTimestamp() // 1596604455
carbon.Now().ToTimestampWithSecond() // 1596604455
// Timestamp with millisecond of today
carbon.Now().ToTimestampWithMillisecond() // 1596604455000
// Timestamp with microsecond of today
carbon.Now().ToTimestampWithMicrosecond() // 1596604455000000
// Timestamp with nanosecond of today
carbon.Now().ToTimestampWithNanosecond() // 1596604455000000000
// Datetime of today in other timezone
carbon.SetTimezone(Carbon.NewYork).Now().ToDateTimeString() // 2020-08-05 01:14:15

// Datetime of yesterday 
carbon.Yesterday().ToDateTimeString() // 2020-08-04 13:14:15
// Date of yesterday
carbon.Yesterday().ToDateString() // 2020-08-04
// Time of yesterday
carbon.Yesterday().ToTimeString() // 13:14:15
// Timestamp with second of yesterday
carbon.Yesterday().ToTimestamp() // 1596518055
carbon.Yesterday().ToTimestampWithSecond() // 1596518055
// Timestamp with millisecond of yesterday
carbon.Yesterday().ToTimestampWithMillisecond() // 1596518055000
// Timestamp with microsecond of yesterday
carbon.Yesterday().ToTimestampWithMicrosecond() // 1596518055000000
// Timestamp with nanosecond of yesterday
carbon.Yesterday().ToTimestampWithNanosecond() // 1596518055000000000
// Datetime of yesterday in other timezone
carbon.SetTimezone(Carbon.NewYork).Yesterday().ToDateTimeString() // 2020-08-04 01:14:15
// Datetime of yesterday in other day
carbon.Parse("2021-01-28 13:14:15").Yesterday().ToDateTimeString() // 2021-01-27 13:14:15

// Datetime of tomorrow
carbon.Tomorrow().ToDateTimeString() // 2020-08-06 13:14:15
// Date of tomorrow
carbon.Tomorrow().ToDateString() // 2020-08-06
// Time of tomorrow
carbon.Tomorrow().ToTimeString() // 13:14:15
// Timestamp with second of tomorrow
carbon.Tomorrow().ToTimestamp() // 1596690855
carbon.Tomorrow().ToTimestampWithSecond() // 1596690855
// Timestamp with millisecond of tomorrow
carbon.Tomorrow().ToTimestampWithMillisecond() // 1596690855000
// Timestamp with microsecond of tomorrow
carbon.Tomorrow().ToTimestampWithMicrosecond() // 1596690855000000
// Timestamp with nanosecond of tomorrow
carbon.Tomorrow().ToTimestampWithNanosecond() // 1596690855000000000
// Datetime of tomorrow in other timezone
carbon.SetTimezone(Carbon.NewYork).Tomorrow().ToDateTimeString() // 2020-08-06 01:14:15
// Datetime of tomorrow in other day
carbon.Parse("2021-01-28 13:14:15").Tomorrow().ToDateTimeString() // 2021-01-29 13:14:15
Create carbon instance
// Create Carbon instance from timestamp with second
carbon.CreateFromTimestamp(1596604455).ToDateTimeString() // 2020-08-05 13:14:15
// Create Carbon instance from timestamp with millisecond
carbon.CreateFromTimestamp(1596604455000).ToDateTimeString() // 2020-08-05 13:14:15
// Create Carbon instance from timestamp with microsecond
carbon.CreateFromTimestamp(1596604455000000).ToDateTimeString() // 2020-08-05 13:14:15
// Create Carbon instance from timestamp with nanosecond
carbon.CreateFromTimestamp(1596604455000000000).ToDateTimeString() // 2020-08-05 13:14:15

// Create Carbon instance from year,month,day,hour,minute and second
carbon.CreateFromDateTime(2020, 8, 5, 13, 14, 15).ToDateTimeString() // 2020-08-05 13:14:15
// Create Carbon instance from year,month and day
carbon.CreateFromDate(2020, 8, 5).ToDateTimeString() // 2020-08-05 13:14:15
// Create Carbon instance from hour,minute and second
carbon.CreateFromTime(13, 14, 15).ToDateTimeString() // 2020-08-05 13:14:15
Parse standard time format string
carbon.Parse("").ToDateTimeString() // empty string
carbon.Parse("0000-00-00 00:00:00").ToDateTimeString() // empty string
carbon.Parse("0000-00-00").ToDateTimeString() // empty string
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
Parse by format string as 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
Convert between carbon and time.Time
// Time.time convert to Carbon
carbon.Time2Carbon(time.Now())
// Carbon convert to Time.time
carbon.Now().Carbon2Time() or carbon.Now().Time
Time setter
// Set timezone
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

// Set year
carbon.Parse("2019-08-05").SetYear(2020).ToDateString() // 2020-08-05
carbon.Parse("2020-02-29").SetYear(2019).ToDateString() // 2019-03-01

// Set month
carbon.Parse("2020-01-31").SetMonth(2).ToDateString() // 2020-03-02
carbon.Parse("2020-08-05").SetMonth(2).ToDateString() // 2020-02-05

// Set day
carbon.Parse("2019-08-05").SetDay(31).ToDateString() // 2020-08-31
carbon.Parse("2020-02-01").SetDay(31).ToDateString() // 2020-03-02

// Set hour
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

// Set minute
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

// Set second
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

For more timezone constants, please see the const.go file

Start and end
// Start of the year
carbon.Parse("2020-08-05 13:14:15").StartOfYear().ToDateTimeString() // 2020-01-01 00:00:00
// End of the year
carbon.Parse("2020-08-05 13:14:15").EndOfYear().ToDateTimeString() // 2020-12-31 23:59:59

// Start of the month
carbon.Parse("2020-08-05 13:14:15").StartOfMonth().ToStartTimeString() // 2020-08-01 00:00:00
// End of the month
carbon.Parse("2020-08-05 13:14:15").EndOfMonth().ToDateTimeString() // 2020-08-31 23:59:59

// Start of the week
carbon.Parse("2020-08-05 13:14:15").StartOfWeek().ToDateTimeString() // 2020-08-03 00:00:00
// End of the week
carbon.Parse("2020-08-05 13:14:15").LastOfWeek().ToDateTimeString() // 2020-08-09 23:59:59

// Start of the day
carbon.Parse("2020-08-05 13:14:15").StartOfDay().ToDateTimeString() // 2020-08-05 00:00:00
// End of the day
carbon.Parse("2020-08-05 13:14:15").EndOfDay().ToDateTimeString() // 2020-08-05 23:59:59

// Start of the hour
carbon.Parse("2020-08-05 13:14:15").StartOfHour().ToDateTimeString() // 2020-08-05 13:00:00
// End of the hour
carbon.Parse("2020-08-05 13:14:15").EndOfHour().ToDateTimeString() // 2020-08-05 13:59:59

// Start of the minute
carbon.Parse("2020-08-05 13:14:15").StartOfMinute().ToDateTimeString() // 2020-08-05 13:14:00
// End of the minute
carbon.Parse("2020-08-05 13:14:15").EndOfMinute().ToDateTimeString() // 2020-08-05 13:14:59
Difference in time
// Difference in weeks
carbon.Parse("2020-08-05 13:14:15").DiffInWeeks(carbon.Parse("2020-07-28 13:14:15")) // -1
// Difference in weeks with absolute value
carbon.Parse("2020-08-05 13:14:15").DiffInWeeksWithAbs(carbon.Parse("2020-07-28 13:14:15")) // 1

// Difference in days
carbon.Parse("2020-08-05 13:14:15").DiffInDays(carbon.Parse("2020-08-04 13:14:15")) // -1
// Difference in days with absolute value
carbon.Parse("2020-08-05 13:14:15").DiffInDaysWithAbs(carbon.Parse("2020-08-04 13:14:15")) // 1

// Difference in hours
carbon.Parse("2020-08-05 13:14:15").DiffInHours(carbon.Parse("2020-08-05 12:14:15")) // -1
// Difference in hours with absolute value
carbon.Parse("2020-08-05 13:14:15").DiffInHoursWithAbs(carbon.Parse("2020-08-05 12:14:15")) // 1

// Difference in minutes
carbon.Parse("2020-08-05 13:14:15").DiffInMinutes(carbon.Parse("2020-08-05 13:13:15")) // -1
// Difference in minutes with absolute value
carbon.Parse("2020-08-05 13:14:15").DiffInMinutesWithAbs(carbon.Parse("2020-08-05 13:13:15")) // 1

// Difference in seconds
carbon.Parse("2020-08-05 13:14:15").DiffInSeconds(carbon.Parse("2020-08-05 13:14:14")) // -1
// Difference in seconds with absolute value
carbon.Parse("2020-08-05 13:14:15").DiffInSecondsWithAbs(carbon.Parse("2020-08-05 13:14:14")) // 1
Time compare
// greater than
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

// less than
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

// equal
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

// not equal
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

// greater than or equal
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

// less than or equal
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

// between
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

// Between included start time
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

// Between included end time
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

// Between included both
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
Time judgment
// Is zero time
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

// Is now time
carbon.Now().IsNow() // true
// Is future time
carbon.Tomorrow().IsFuture() // true
// Is pass time
carbon.Yesterday().IsPast() // true

// Is leap year
carbon.Parse("2020-08-05 13:14:15").IsLeapYear() // true
// Is long year
carbon.Parse("2020-08-05 13:14:15").IsLongYear() // true

// Is january 
carbon.Parse("2020-08-05 13:14:15").IsJanuary() // false
// Is february
carbon.Parse("2020-08-05 13:14:15").IsFebruary() // false
// Is march
carbon.Parse("2020-08-05 13:14:15").IsMarch() // false
// Is april
carbon.Parse("2020-08-05 13:14:15").IsApril()  // false
// Is may
carbon.Parse("2020-08-05 13:14:15").IsMay() // false
// Is june
carbon.Parse("2020-08-05 13:14:15").IsJune() // false
// Is july
carbon.Parse("2020-08-05 13:14:15").IsJuly() // false
// Is august
carbon.Parse("2020-08-05 13:14:15").IsAugust() // false
// Is september
carbon.Parse("2020-08-05 13:14:15").IsSeptember() // true
// Is october
carbon.Parse("2020-08-05 13:14:15").IsOctober() // false
// Is november
carbon.Parse("2020-08-05 13:14:15").IsNovember() // false
// Is december
carbon.Parse("2020-08-05 13:14:15").IsDecember() // false

// Is monday
carbon.Parse("2020-08-05 13:14:15").IsMonday() // false
// Is tuesday
carbon.Parse("2020-08-05 13:14:15").IsTuesday() // true
// Is wednesday
carbon.Parse("2020-08-05 13:14:15").IsWednesday() // false
// Is thursday
carbon.Parse("2020-08-05 13:14:15").IsThursday()  // false
// Is friday
carbon.Parse("2020-08-05 13:14:15").IsFriday() // false
// Is saturday
carbon.Parse("2020-08-05 13:14:15").IsSaturday() // false
// Is sunday
carbon.Parse("2020-08-05 13:14:15").IsSunday() // false
// Is weekday
carbon.Parse("2020-08-05 13:14:15").IsWeekday() // false
// Is weekend
carbon.Parse("2020-08-05 13:14:15").IsWeekend() // true

// Is yesterday
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
// Is today
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
// Is tomorrow
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
Time output
// To timestamp with second
carbon.Parse("2020-08-05 13:14:15").ToTimestamp() // 1596604455
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithSecond() // 1596604455
// To timestamp with millisecond
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithMillisecond() // 1596604455000
// To timestamp with microsecond
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithMicrosecond() // 1596604455000000
// To timestamp with nanosecond
carbon.Parse("2020-08-05 13:14:15").ToTimestampWithNanosecond() // 1596604455000000000

// To string of datetime format
carbon.Parse("2020-08-05 13:14:15").ToDateTimeString() // 2020-08-05 13:14:15
// To string of date format
carbon.Parse("2020-08-05 13:14:15").ToDateString() // 2020-08-05
// To string of time format
carbon.Parse("2020-08-05 13:14:15").ToTimeString() // 13:14:15

// To string of Ansic format
carbon.Parse("2020-08-05 13:14:15").ToAnsicString() // Wed Aug  5 13:14:15 2020
// To string of Atom format
carbon.Parse("2020-08-05 13:14:15").ToAtomString() // Wed Aug  5 13:14:15 2020
// To string of UnixDate format  
carbon.Parse("2020-08-05 13:14:15").ToUnixDateString() // Wed Aug  5 13:14:15 CST 2020
// To string of RubyDate format 
carbon.Parse("2020-08-05 13:14:15").ToRubyDateString() // Wed Aug 05 13:14:15 +0800 2020
// To string of Kitchen format
carbon.Parse("2020-08-05 13:14:15").ToKitchenString() // 1:14PM
// To string of Cookie format
carbon.Parse("2020-08-05 13:14:15").ToCookieString() // Wednesday, 05-Aug-2020 13:14:15 CST
// To string of DayDateTime format
carbon.Parse("2020-08-05 13:14:15").ToDayDateTimeString() // Wed, Aug 5, 2020 1:14 PM
// To string of RSS format
carbon.Parse("2020-08-05 13:14:15").ToRssString() // Wed, 05 Aug 2020 13:14:15 +0800
// To string of W3C format
carbon.Parse("2020-08-05 13:14:15").ToW3cString() // 2020-08-05T13:14:15+08:00

// To string of RFC822 format
carbon.Parse("2020-08-05 13:14:15").ToRfc822String() // 05 Aug 20 13:14 CST
// To string of RFC822Z format
carbon.Parse("2020-08-05 13:14:15").ToRfc822zString() // 05 Aug 20 13:14 +0800
// To string of RFC850 format
carbon.Parse("2020-08-05 13:14:15").ToRfc850String() // Wednesday, 05-Aug-20 13:14:15 CST
// To string of RFC1036 format
carbon.Parse("2020-08-05 13:14:15").ToRfc1036String() // Wed, 05 Aug 20 13:14:15 +0800
// To string of RFC1123 format
carbon.Parse("2020-08-05 13:14:15").ToRfc1123String() // Wed, 05 Aug 2020 13:14:15 CST
// To string of RFC2822 format
carbon.Parse("2020-08-05 13:14:15").ToRfc2822String() // Wed, 05 Aug 2020 13:14:15 +0800
// To string of RFC3339 format 
carbon.Parse("2020-08-05 13:14:15").ToRfc3339String() // 2020-08-05T13:14:15+08:00
// To string of RFC7231 format
carbon.Parse("2020-08-05 13:14:15").ToRfc7231String() // Wed, 05 Aug 2020 05:14:15 GMT

// To string
carbon.Parse("2020-08-05 13:14:15").Time.String() // 2020-08-05 13:14:15 +0800 CST
// To string of layout formatļ¼ŒToFormatString() abbreviated as Format()
carbon.Parse("2020-08-05 13:14:15").ToFormatString("YmdHis") // 20200805131415
carbon.Parse("2020-08-05 13:14:15").Format("YmdHis") // 20200805131415
carbon.Parse("2020-08-05 13:14:15").Format("l jS \\o\\f F Y h:i:s A") // Wednesday 5th of August 2020 01:14:15 PM

For more format signs, please see the format sign table

Time getter
// Get total days of the year
carbon.Parse("2019-08-05 13:14:15").DaysInYear() // 365
carbon.Parse("2020-08-05 13:14:15").DaysInYear() // 366
// Get total days of the month
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

// Get day of the year
carbon.Parse("2020-08-05 13:14:15").DayOfYear() // 218
// Get week of the year
carbon.Parse("2020-08-05 13:14:15").WeekOfYear() // 32
// Get day of the month
carbon.Parse("2020-08-05 13:14:15").DayOfMonth() // 5
// Get week of the month
carbon.Parse("2020-08-05 13:14:15").WeekOfMonth() // 1
// Get day of the week
carbon.Parse("2020-08-05 13:14:15").DayOfWeek() // 3

// Get current year
carbon.Parse("2020-08-05 13:14:15").Year() // 2020
// Get current quarter
carbon.Parse("2020-08-05 13:14:15").Quarter() // 3
// Get current month
carbon.Parse("2020-08-05 13:14:15").Month() // 8
// Get current day
carbon.Parse("2020-08-05 13:14:15").Day() // 5
// Get current hour
carbon.Parse("2020-08-05 13:14:15").Hour() // 13
// Get current minute
carbon.Parse("2020-08-05 13:14:15").Minute() // 14
// Get current second
carbon.Parse("2020-08-05 13:14:15").Second() // 15
// Get current millisecond
carbon.Parse("2020-08-05 13:14:15").Millisecond() // 1596604455000
// Get current microsecond
carbon.Parse("2020-08-05 13:14:15").Microsecond() // 1596604455000000
// Get current nanosecond
carbon.Parse("2020-08-05 13:14:15").Nanosecond() // 1596604455000000000

// Get timezone name
carbon.SetTimezone(carbon.PRC).Timezone() // PRC
carbon.SetTimezone(carbon.Tokyo).Timezone() // Asia/Tokyo

// Get current age
carbon.Parse("2002-01-01 13:14:15").Age() // 17
carbon.Parse("2002-12-31 13:14:15").Age() // 18
Database

Assuming the database table is users, its fields have 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)

Define model
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"`
}
Instantiate model
user := UserModel {
    ID: 1153,
    Name: "gouguoyin",
    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()},
}
Output fields
user.ID // 1153
user.Name // gouguoyin
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
Output model by json
data, _ := json.Marshal(&user)
fmt.Print(string(data))
// Output
{
    "id": 1153,
    "name": "gouguoyin",
    "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,
}
Output custom format
// Define format
type ToRssString struct {
    carbon.Carbon
}

// Define model
type UserModel struct {
    Birthday carbon.ToRssString `json:"birthday"`
}

// Instantiate model
user := UserModel {
    Birthday: carbon.ToRssString{carbon.Now()},
}

// Overload MarshalJSON method
func (c ToRssString) MarshalJSON() ([]byte, error) {
	return []byte(fmt.Sprintf(`"%s"`, c.ToRssString())), nil
}

// Output model by json.Marshal(&user)
{
    "birthday": "Wed, 05 Aug 2020 13:14:15 +0800",
}
Error handling

If more than one error occurs, only the first error message is returned

Scene one
c := carbon.SetTimezone(PRC).Parse("123456")
if c.Error != nil {
    // Error handle...
    fmt.Println(c.Error)
}
fmt.Println(c.ToDateTimeString())
// output
the value "123456" can't parse string as time
Scene two
c := carbon.SetTimezone("XXXX").Parse("2020-08-05")
if c.Error != nil {
    // Error handle...
    fmt.Println(c.Error)
}
fmt.Println(c.ToDateTimeString())
// Output
invalid timezone "XXXX", please see the $GOROOT/lib/time/zoneinfo.zip file for all valid timezone
Scene three
c := carbon.SetTimezone("XXXX").Parse("12345678")
if c.Error != nil {
    // Error handle...
    fmt.Println(c.Error)
}
fmt.Println(c.ToDateTimeString())
// Output
invalid timezone "XXXX", please see the $GOROOT/lib/time/zoneinfo.zip file for all valid timezone

Appendix

Format sign table
sign desc length range example
d Day of the month, 2 digits with leading zeros 2 01-31 05
D A textual representation of a day, three letters 3 Mon-Sun Wed
j Day of the month without leading zeros 1/2 1-31 5
S English ordinal suffix for the day of the month, 2 characters. Eg: st, nd, rd or th. Works well with j 2 st/nd/rd/th th
l A full textual representation of the day of the week - Monday-Sunday Wednesday
F A full textual representation of a month - January-December August
m Numeric representation of a month, with leading zeros 2 01-12 08
M A short textual representation of a month, three letters 3 Jan-Dec Aug
n Numeric representation of a month, without leading zeros 1/2 1-12 8
y A two digit representation of a year 2 00-99 20
Y A full numeric representation of a year, 4 digits 4 0000-9999 2020
a A full numeric representation of a year, 4 digits 2 am/pm pm
A Uppercase Ante meridiem and Post meridiem 2 AM/PM PM
g 12-hour format of an hour without leading zeros 1/2 1-12 1
G 24-hour format of an hour without leading zeros 1/2 0-23 15
h 12-hour format of an hour with leading zeros 2 00-11 03
H 24-hour format of an hour with leading zeros 2 00-23 15
i Minutes with leading zeros 2 01-59 14
s Seconds with leading zeros 2 01-59 15
c ISO 8601 date - - 2020-08-05T15:19:21+00:00
r RFC 2822 date - - Thu, 21 Dec 2020 16:01:07 +0200
O Difference to Greenwich time (GMT) without colon between hours and minutes - - +0200
P Difference to Greenwich time (GMT) with colon between hours and minutes - - +02:00
T Timezone abbreviation - - EST
W ISO-8601 numeric representation of the week of the year 1/2 1-52 42
N ISO-8601 numeric representation of the day of the week 1 1-7 6
L Whether itā€™s a leap year 1 0-1 1
U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) 10 - 1611818268
u Microseconds - - 999
w Numeric representation of the day of the week 1 0-6 6
t Number of days in the given month 2 28-31 30
z The day of the year (starting from 0) 1/2/3 0-365 15
e Timezone identifier - - America/New_York
1 Like

recommended

Your recommendation has no value. You are the #1 contributor to the Go carbon package.

Contributors to golang-module/carbon Ā· GitHub

gouguoyin #1
87 commits