carbon

Introduction to Carbon

Carbon is a straightforward, semantic, and developer-friendly Go package designed for handling and manipulating time. It's been recognized for its utility and versatility by being included in the awesome-go list. Carbon provides an intuitive API, enabling developers to work with dates and times effortlessly, making it an excellent tool for projects where precise time management is crucial.

Installation

For Go Version >= 1.17 (Recommended)

To install Carbon, simply use Go's built-in package management:

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

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

// Alternatively, install via Gitee
go get -u gitee.com/golang-module/carbon/v2

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

For Go Version < 1.17 (Required)

// Install via GitHub
go get -u github.com/golang-module/carbon

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

// Alternatively, install via Gitee
go get -u gitee.com/golang-module/carbon

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

To get a better understanding of the differences between version 1 and version 2, refer to the FAQ section, noting that version 1 is no longer updated, only maintained.

Usage and Examples

Imagine that the current time is 2020-08-05 13:14:15. Carbon provides several ways to manage and manipulate time instances, as described below.

Setting Global Default Values

Carbon allows for global default settings to be configured, ensuring consistent behavior across your application. It is suggested to place this configuration in a central location, like main.go:

carbon.SetDefault(carbon.Default{
  Layout: carbon.DateTimeLayout,
  Timezone: carbon.Local,
  WeekStartsAt: carbon.Sunday,
  Locale: "en",
})

Converting Between Carbon and time.Time

Seamlessly convert between time.Time and Carbon instances:

// Convert a standard time.Time to a Carbon instance
carbon.CreateFromStdTime(time.Now())
// Convert a Carbon instance to a standard time.Time
carbon.Now().StdTime()

Yesterday, Today, and Tomorrow

Carbon makes it easy to work with dates such as yesterday, today, and tomorrow:

// Get today's date and time
fmt.Printf("%s", carbon.Now()) // Output: 2020-08-05 13:14:15

// Get yesterday's date and time
fmt.Printf("%s", carbon.Yesterday()) // Output: 2020-08-04 13:14:15

// Get tomorrow's date and time
fmt.Printf("%s", carbon.Tomorrow()) // Output: 2020-08-06 13:14:15

Creating a Carbon Instance

Carbon provides various methods for creating instances from timestamps, dates, times, or a combination of these, ensuring flexibility to suit different needs:

// Create an instance from a specific timestamp
carbon.CreateFromTimestamp(1649735755).ToString() // 2022-04-12 11:55:55 +0800 CST

// Create an instance from a specific date and time
carbon.CreateFromDateTime(2020, 8, 5, 13, 14, 15).ToString() // 2020-08-05 13:14:15 +0800 CST

Parsing a Time String

Carbon can parse various time formats into a Carbon instance, providing robust parsing capabilities:

carbon.Parse("2020-08-05").ToString() // 2020-08-05 00:00:00 +0800 CST
carbon.ParseByFormat("2020|08|05 13|14|15", "Y|m|d H|i|s").ToDateTimeString() // 2020-08-05 13:14:15

Working with Time Boundaries

Carbon allows operations at different time boundaries, such as start and end of the century, decade, year, quarter, month, and week:

// Get the start of the year
carbon.Parse("2020-08-05 13:14:15").StartOfYear().ToDateTimeString() // 2020-01-01 00:00:00

// Get the end of the year
carbon.Parse("2020-08-05 13:14:15").EndOfYear().ToDateTimeString() // 2020-12-31 23:59:59

These features make Carbon an essential tool for developers who need to manage time and dates effectively in their Go applications. With its simple and intuitive API, Carbon streamlines work with time, reducing common headaches and improving productivity.