Skip to content
Docs
Modules
carbon

carbon

The carbon module provides a convenient set of utilities for working with dates and times. These functions are meant to aid writing more readable and maintainable date/time code.

The core functionality is provided by github.com/golang-module/carbon (opens in a new tab).

Module

Function signature
carbon(input ...object)

The carbon module object itself is callable in order to provide a shorthand for initializing a new carbon object.

Three input variations are supported:

  • No input: Returns the current time as a carbon object.
  • A string input: Parses the string into a carbon object.
  • A time input: Converts the time into a carbon object.
Example
>>> carbon()
carbon.carbon(2024-02-03 12:03:55)
>>> carbon("2015-03-01 12:01:00")
carbon.carbon(2015-03-01 12:01:00)
>>> carbon(time.now())
carbon.carbon(2024-02-03 12:03:55)

Functions

now

Function signature
now(timezone ...string) carbon

Returns the current time as a carbon object. A timezone string may optionally be provided.

Example
>>> carbon.now()
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.now("America/Sao_Paulo").timezone()
"-03"

parse

Function signature
parse(value, timezone ...string) carbon

Parses the time string into a carbon object. A timezone may optionally be provided. If the time string is invalid, an error is raised.

Example
>>> carbon.parse("2021-03-20")
carbon.carbon(2021-03-20 00:00:00)
>>> carbon.parse("2024-02-03 12:03:55")
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.parse("2024-02-03 12:03:55", "America/Sao_Paulo")
carbon.carbon(2024-02-03 12:03:55)
>>> carbon.parse("oops")
// value error: invalid time string (got "oops")

yesterday

Function signature
yesterday(timezone ...string) carbon

Returns a time object for yesterday, at the current time of day. A timezone may optionally be provided.

Example
>>> carbon.yesterday()
carbon.carbon(2024-02-02 12:03:55)

tomorrow

Function signature
tomorrow(timezone ...string) carbon

Returns a time object for tomorrow, at the current time of day. A timezone may optionally be provided.

Example
>>> carbon.tomorrow()
carbon.carbon(2024-02-04 12:03:55)

Types

carbon

The carbon object represents a point in time and offers a variety of helper methods for performing date and time operations. Many of the operations reflect ways humans think about dates and times, such as "add a day" or "get the age".

Methods

add_day
Method signature
add_day() carbon

Returns a new carbon object with the day incremented by one.

Example
>>> c := carbon.now()
>>> c.add_day()
carbon.carbon(2024-02-04 12:03:55)
add_days
Method signature
add_days(days int) carbon

Returns a new carbon object with the day incremented by the specified number of days.

Example
>>> c := carbon.now()
>>> c.add_days(7)
carbon.carbon(2024-02-10 12:03:55)
sub_day
Method signature
sub_day() carbon

Returns a new carbon object with the day decremented by one.

Example
>>> c := carbon.now()
>>> c.sub_day()
carbon.carbon(2024-02-02 12:03:55)
sub_days
Method signature
sub_days(days int) carbon

Returns a new carbon object with the day decremented by the specified number of days.

Example
>>> c := carbon.now()
>>> c.sub_days(7)
carbon.carbon(2024-01-27 12:03:55)
timezone
Method signature
timezone(tz string) carbon

Returns a new carbon object with the timezone set to the specified timezone string.

Example
>>> c := carbon.now()
>>> c.timezone("America/New_York")
carbon.carbon(2024-02-03 07:03:55)
age
Method signature
age(other carbon) int

Returns the age (in years) between the current carbon object and the specified carbon object.

Example
>>> c1 := carbon.parse("2000-01-01")
>>> c2 := carbon.now()
>>> c2.age(c1)
24
days_in_month
Method signature
days_in_month() int

Returns the number of days in the month of the current carbon object.

Example
>>> c := carbon.parse("2024-02-15")
>>> c.days_in_month()
29
days_in_year
Method signature
days_in_year() int

Returns the number of days in the year of the current carbon object.

Example
>>> c := carbon.parse("2024-02-15")
>>> c.days_in_year()
366
week_of_month
Method signature
week_of_month() int

Returns the week of the month for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15")
>>> c.week_of_month()
3
week_of_year
Method signature
week_of_year() int

Returns the week of the year for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15")
>>> c.week_of_year()
7
timestamp
Method signature
timestamp() int64

Returns the Unix timestamp (in seconds) for the current carbon object.

Example
>>> c := carbon.now()
>>> c.timestamp()
1677886635
string
Method signature
string() string

Returns the string representation of the current carbon object in the format "YYYY-MM-DD HH:MM:SS".

Example
>>> c := carbon.now()
>>> c.string()
"2024-02-03 12:03:55"
is_valid
Method signature
is_valid() bool

Returns true if the current carbon object represents a valid date and time, false otherwise.

Example
>>> c1 := carbon.parse("2024-02-29")
>>> c1.is_valid()
false
>>> c2 := carbon.parse("2024-02-28")
>>> c2.is_valid()
true
is_am
Method signature
is_am() bool

Returns true if the current carbon object represents a time in the AM (before noon), false otherwise.

Example
>>> c1 := carbon.parse("2024-02-03 08:00:00")
>>> c1.is_am()
true
>>> c2 := carbon.parse("2024-02-03 15:00:00")
>>> c2.is_am()
false
is_pm
Method signature
is_pm() bool

Returns true if the current carbon object represents a time in the PM (after noon), false otherwise.

Example
>>> c1 := carbon.parse("2024-02-03 08:00:00")
>>> c1.is_pm()
false
>>> c2 := carbon.parse("2024-02-03 15:00:00")
>>> c2.is_pm()
true
is_leap_year
Method signature
is_leap_year() bool

Returns true if the year of the current carbon object is a leap year, false otherwise.

Example
>>> c1 := carbon.parse("2024-02-29")
>>> c1.is_leap_year()
true
>>> c2 := carbon.parse("2023-02-28")
>>> c2.is_leap_year()
false
is_future
Method signature
is_future() bool

Returns true if the current carbon object represents a time in the future (after the current time), false otherwise.

Example
>>> c1 := carbon.parse("2024-02-03 15:00:00")
>>> c1.is_future()
true
>>> c2 := carbon.now()
>>> c2.is_future()
false
is_past
Method signature
is_past() bool

Returns true if the current carbon object represents a time in the past (before the current time), false otherwise.

Example
>>> c1 := carbon.parse("2024-02-03 15:00:00")
>>> c1.is_past()
false
>>> c2 := carbon.now().sub_days(1)
>>> c2.is_past()
true
is_today
Method signature
is_today() bool

Returns true if the current carbon object represents a time on the current day, false otherwise.

Example
>>> c1 := carbon.now()
>>> c1.is_today()
true
>>> c2 := carbon.parse("2024-02-02 15:00:00")
>>> c2.is_today()
false
is_yesterday
Method signature
is_yesterday() bool

Returns true if the current carbon object represents a time on the previous day, false otherwise.

Example
>>> c1 := carbon.now()
>>> c1.is_yesterday()
false
>>> c2 := carbon.yesterday()
>>> c2.is_yesterday()
true
day
Method signature
day() int

Returns the day of the month for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.day()
15
month
Method signature
month() int

Returns the month for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.month()
2
year
Method signature
year() int

Returns the year for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.year()
2024
hour
Method signature
hour() int

Returns the hour for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:00:00")
>>> c.hour()
12
minute
Method signature
minute() int

Returns the minute for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:30:00")
>>> c.minute()
30
second
Method signature
second() int

Returns the second for the current carbon object.

Example
>>> c := carbon.parse("2024-02-15 12:30:45")
>>> c.second()
45
diff_for_humans
Method signature
diff_for_humans(other carbon) string

Returns a human-readable string representing the difference between the current carbon object and the specified carbon object.

Example
>>> c1 := carbon.now()
>>> c2 := c1.add_days(7)
>>> c2.diff_for_humans(c1)
"1 week"
std_time
Method signature
std_time() time.Time

Returns a time.Time object representing the current carbon object.

Example
>>> c := carbon.now()
>>> t := c.std_time()
>>> fmt.Println(t)
2024-02-03 12:03:55 +0000 UTC
to_date_string
Method signature
to_date_string() string

Returns a string representation of the current carbon object in the format "YYYY-MM-DD".

Example
>>> c := carbon.now()
>>> c.to_date_string()
"2024-02-03"
to_time_string
Method signature
to_time_string() string

Returns a string representation of the current carbon object in the format "HH:MM:SS".

Example
>>> c := carbon.parse("2024-02-03 12:30:45")
>>> c.to_time_string()
"12:30:45"
to_datetime_string
Method signature
to_datetime_string() string

Returns a string representation of the current carbon object in the format "YYYY-MM-DD HH:MM:SS".

Example
>>> c := carbon.parse("2024-02-03 12:30:45")
>>> c.to_datetime_string()
"2024-02-03 12:30:45"