Easy date manipulation in Golang with Godate

Easy date manipulation in Golang with Godate

Add to bookmarks

Wed 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 .



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.


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


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


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


Some of the extra helper methods and their outputs are listed below:

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) .


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 :)