Easy date manipulation in Golang with Godate
Add to bookmarksWed May 15 2019
I have always been and always will be a fan of Carbon and how easy it is to get date manipulation done so efficiently. Being a fan of Carbon and also being a fan of Golang I thought why not write a library called godate, to do for golang what carbon does for Php and in this article I would be going into explaining how to use it.
Package Breakdown
The package is mostly a GoDate
struct with its available helper methods, which acts as a wrapper to a Time
struct. It also includes some functions for initializing e.g Now
Tomorrow
.
Usage
Installation
go get github.com/kofoworola/godate
It also supports go’s new module system so you can simply import it into your project and run go will attempt to install the latest version of the package, which is v1.2.0 as of the time of writing this.
Usage
Create a new GoDate struct with any of the methods currently available
now := godate.Now(time.UTC) //Tue Apr 30 14:43:05 +0000 UTC 2019
tomorrow := godate.Tomorrow(time.UTC) //Wed May 1 14:43:05 +0000 UTC 2019
yesterday := godate.Yesterday(time.UTC) //Mon Apr 29 14:43:05 +0000 UTC 2019
timeBased := godate.Create(time.Now()) //Tue Apr 30 15:43:05 +0100 WAT 2019
easy peasy
Note the difference in Timezone, which is why I recommend creating a GoDate struct with a time.Location
object passed.
Once you have a struct you can easily chain methods on the struct to achieve your result like so:
newDate := tomorrow.StartOfDay().Add(5,godate.DAY).Sub(1,godate.HOUR)
// will output Sun May 5 23:00:00 +0000 UTC 2019
Available Methods
Compare
The available compare methods are IsBefore
, IsBefore
and IsWeekend
. The method names explain what they do:
now.IsAfter(now.Sub(1,godate.DAY)) //true
now.IsBefore(now.Add(1,godate.DAY)) //true
now.IsBefore(now.Sub(1,godate.DAY)) //false
now.IsWeekend() //false
Difference
The most important Difference methods are highlighted below, although the more methods are included that are also used in the logic of these:
now.DifferenceForHumans(yesterday.Sub(1, godate.MINUTE))) //1 day before
yesterday.Sub(10, godate.DAY).DifferenceFromNowForHumans()) //1 week ago
now.Difference(now.Add(12, godate.DAY), godate.WEEK)) //-1
now.DifferenceAsFloat(now.Add(13, godate.DAY), godate.WEEK)) //-1.8571428571428572
The Difference
methods that take another goDate
as a parameter calculates the difference as methodOwner — parameter
. A negative difference means the parameter occurs after the methodOwner
, the opposite is true
String Formatting
These are the current available String formatting methods. You can also format(you might want to read that if you’re new to dates in golang) this your way by calling the Format()
method
now.ToDateString()) //2019-04-30
now.ToTimeString()) //15:27:59
now.ToFormattedDateString()) //Apr 30, 2019
now.ToDateTimeString()) //2019-04-30 15:27:59
now.ToDayTimeString()) //Tue, Apr 30, 2019 03:27 PM
Helper
Some of the extra helper methods and their outputs are listed below:
now.SetFirstDay(time.Wednesday)
fmt.Println(now) //Tue Apr 30 15:31:58 +0000 UTC 2019
fmt.Println(now.StartOfHour()) //Tue Apr 30 15:00:00 +0000 UTC 2019
fmt.Println(now.StartOfDay()) //Tue Apr 30 00:00:00 +0000 UTC 2019
fmt.Println(now.StartOfWeek()) //Wed May 1 00:00:00 +0000 UTC 2019
fmt.Println(now.StartOfQuarter()) //Mon Apr 1 00:00:00 +0000 UTC 2019
fmt.Println(now.StartOfMonth()) //Mon Apr 1 00:00:00 +0000 UTC 2019
fmt.Println(now.StartOfYear()) //Tue Jan 1 00:00:00 +0000 UTC 2019
fmt.Println(now.EndOfHour()) //Tue Apr 30 15:59:59 +0000 UTC 2019
fmt.Println(now.EndOfDay()) //Tue Apr 30 23:59:59 +0000 UTC 2019
fmt.Println(now.EndOfWeek()) //Tue May 7 23:59:59 +0000 UTC 2019
fmt.Println(now.EndOfQuarter()) //Sun Jun 30 23:59:59 +0000 UTC 2019
fmt.Println(now.EndOfMonth()) //Tue Apr 30 23:59:59 +0000 UTC 2019
fmt.Println(now.EndOfYear()) //Thu Jan 31 23:59:59 +0000 UTC 2019
Note the EndOfWeek
and StartOfWeek
methods use time.Sunday
as the default start of the week. This behavior can be changed for the current godate struct by calling now.SetFirstDay(time.Monday)
.
Conclusion
The package is far from complete (and probably never will be) as the aim is to provide a robust date handling api similar and even better (someone’s being ambitious) than Carbon, so you golovers out there like me should make it rain PRs on the repo (and stars :)