Goment is a port of the popular Javascript datetime library Moment.js. It follows the Moment.js API closely, with some changes to make it more Go-like (e.g. using nanoseconds instead of milliseconds).

Goment is still a work in progress. Please feel free to fork and contribute missing methods, locale/languages functionality, or just provide more idiomatic Go if you see some areas to improve. I have a list of things that need added/fixed in TODO.md, but will create issues for them at some point.

• Parsing
• Get+Set
• Manipulate
• Display
• Query
• i18n

Creates a Goment object for the current local time returned by time.Now().

goment.New()

Creates a Goment object by parsing the string as an ISO 8601 date time. The timezone will be UTC unless supplied in the string.

goment.New('2013-02-08 09:30:26')

Creates a Goment object by parsing the string using the supplied format. The timezone will be the local timezone unless supplied in the string.

The parsing tokens are similar to the formatting tokens used in Goment#Format.

Goment's parser is strict, and defaults to being accurate over forgiving.

goment.New("12-25-1995", "MM-DD-YYYY")

For these, the lowercase tokens use the locale aware week start days, and the uppercase tokens use the ISO week date start days.

As of Goment 1.2.0, a locale can now be supplied to parse locale-specific dates and times.

goment.New("2 de septiembre de 1999 12:30", "LLL", "es")

Creates a Goment object from the Unix nanoseconds since the Unix Epoch.

goment.New(time.Now().UnixNano())

Creates a Goment object from the Unix timestamp (seconds since the Unix Epoch).

goment.Unix(1318781876)

Creates a Goment object from the supplied Go time object.

goment.New(time.Date(2015, 11, 10, 5, 30, 0, 0, time.UTC))

Creates a Goment object from a clone of the supplied Goment object.

goment.New(goment.New('2011-05-08'))

Creates a Goment object from a Goment DateTime object.

goment.New(DateTime{
    Year:  2015,
    Month: 1,
    Day:   25,
    Hour:  10,
})

Get is a string getter using the supplied units.

• y, year, years
• M, month, months
• D, date, dates
• h, hour, hours
• m, minute, minutes
• s, second, seconds
• ms, millisecond, milliseconds
• ns, nanosecond, nanoseconds

g.Get('hours') // 22

Gets the nanoseconds of the Goment object.

g.Nanosecond() // 600

Gets the milliseconds of the Goment object.

g.Millisecond() // 330

Gets the seconds of the Goment object.

g.Second() // 33

Gets the minutes of the Goment object.

g.Minute() // 45

Gets the hours of the Goment object.

g.Hour() // 22

Gets the day of the month of the Goment object.

g.Date() // 19

Gets the day of the week (Sunday = 0...) of the Goment object.

g.Day() // 2

Gets the day of the week according to the locale of the Goment object.

g.Weekday() // 3

Gets the Goment object ISO day of the week with 1 being Monday and 7 being Sunday.

g.ISOWeekday() // 4

Gets the day of the year of the Goment object.

g.DayOfYear() // 100

Gets the localized week of the year for the Goment object.

The week of the year varies depending on which day is the first day of the week (Sunday, Monday, etc), and which week is the first week of the year.

For example, in the United States, Sunday is the first day of the week. The week with January 1st in it is the first week of the year.

In France, Monday is the first day of the week, and the week with January 4th is the first week of the year.

The output of g.Week() will depend on the locale for the Goment object.

g.Week() // 52

Gets the ISO week of the year of the Goment object.

g.ISOWeek() // 6

Gets the month (January = 1...) of the Goment object.

g.Month() // 2

Gets the quarter (1 to 4) of the Goment object.

g.Quarter() // 1

Gets the year of the Goment object.

g.Year() // 2013

Gets the week-year according to the Goment object's locale.

Because the first day of the first week does not always fall on the first day of the year, sometimes the week-year will differ from the month year.

For example, in the US, the week that contains Jan 1 is always the first week. In the US, weeks also start on Sunday. If Jan 1 was a Monday, Dec 31 would belong to the same week as Jan 1, and thus the same week-year as Jan 1. Dec 30 would have a different week-year than Dec 31.

g.WeekYear() // 2012

Gets the ISO week-year of the Goment object.

g.ISOWeekYear() // 2013

Gets the number of weeks according to locale in the current Goment's year.

g.WeekYear() // 53

Gets the number of weeks in the current Goment's year, according to ISO weeks.

g.ISOWeeksInYear() // 52

Set is a generic setter, accepting units as the first argument, and value as the second.

• y, year, years
• M, month, months
• D, date, dates
• h, hour, hours
• m, minute, minutes
• s, second, seconds
• ms, millisecond, milliseconds
• ns, nanosecond, nanoseconds

g.Set(6, 'hour')

Sets the nanoseconds for the Goment object.

g.SetNanosecond(60000)

Sets the milliseconds for the Goment object.

g.SetMillisecond(5000)

Sets the seconds for the Goment object.

g.SetSecond(55)

Sets the minutes for the Goment object.

g.SetMinute(15)

Sets the hours for the Goment object.

g.SetHour(5)

Sets the day of the month for the Goment object. If the date passed in is greater than the number of days in the month, then the day is set to the last day of the month.

g.SetDate(21)

Sets the day of the week (Sunday = 0...) for the Goment object.

g.SetDay(1)

As of 1.3.0, a day name is also supported. This is parsed in the Goment object's locale.

g.SetDay("lunes")

Sets the day of the week according to the locale of the Goment object.

If the locale assigns Monday as the first day of the week, g.SetWeekday(0) will be Monday. If Sunday is the first day of the week, g.SetWeekday(0) will be Sunday.

g.SetWeekday(0)

Sets the Goment object ISO day of the week with 1 being Monday and 7 being Sunday.

g.SetISOWeekday(2)

Sets the day of the year for the Goment object. For non-leap years, 366 is treated as 365.

g.SetDayOfYear(100)

Sets the localized week of the year for the Goment object. When setting the week of the year, the day of the week is retained.

get.SetWeek(50)

Sets the ISO week of the year for the Goment object.

When setting the week of the year, the day of the week is retained.

g.SetISOWeek(52)

Sets the month (January = 1...) of the Goment object. If new month has less days than current month, the date is pinned to the end of the target month.

g.SetMonth(3)

Sets the quarter (1 to 4) for the Goment object.

g.SetQuarter(2)

Sets the year for the Goment object.

g.SetYear(2010)

Sets the week-year according to the Goment object's locale.

g.SetWeekYear(2014)

Sets the ISO week-year of the Goment object.

g.SetISOWeekYear(2018)

Add mutates the Goment object by adding time. The first argument can either be a time.Duration, or an integer representing the number of the unit to add. The second argument should be a unit.

• y, year, years
• Q, quarter, quarters
• M, month, months
• w, week, weeks
• d, day, days
• h, hour, hours
• m, minute, minutes
• s, second, seconds
• ms, millisecond, milliseconds
• ns, nanosecond, nanoseconds

g.Add(1, 'days')

Subtract mutates the Goment object by subtracting time. The first argument can either be a time.Duration, or an integer representing the number of the unit to add. The second argument should be a unit.

• y, year, years
• Q, quarter, quarters
• M, month, months
• w, week, weeks
• d, day, days
• h, hour, hours
• m, minute, minutes
• s, second, seconds
• ms, millisecond, milliseconds
• ns, nanosecond, nanoseconds

g.Subtract(5, 'hours')

StartOf mutates the Goment object by setting it to the start of a unit of time.

• y, year, years
• Q, quarter, quarters
• M, month, months
• w, week, weeks
• W, isoWeek, isoWeeks
• d, day, days
• h, hour, hours
• m, minute, minutes
• s, second, seconds

g.StartOf('day')

EndOf mutates the Goment object by setting it to the end of a unit of time.

• y, year, years
• Q, quarter, quarters
• M, month, months
• w, week, weeks
• W, isoWeek, isoWeeks
• d, day, days
• h, hour, hours
• m, minute, minutes
• s, second, seconds

g.EndOf('month')

Local will set the Goment to use local time.

g.Local()

UTC will set the Goment to use UTC time.

g.UTC()

UTCOffset gets the Goment's UTC offset in minutes.

g.UTCOffset() // -6

SetUTCOffset sets the Goment's UTC offset in minutes. If the offset is less than 16 and greater than -16, the value is treated as hours.

g.SetUTCOffset(120)

Format takes a string of tokens and replaces them with their corresponding values to display the Goment.

g.Format('YYYY-MM-DD') // 2020-05-01

FromNow returns the relative time from now to the Goment time.

g.FromNow() // 10 months ago

ToNow returns the relative time to now to the Goment time.

g.ToNow() // minutes

From returns the relative time from the supplied time to the Goment time.

g.From(goment.New()) // a day ago

To returns the relative time from the Goment time to the supplied time.

g.To(goment.New()) // in a minute

Calendar displays time relative to a given referenceTime (defaults to now).

g.Calendar() // Today at 1:00 PM

Diff returns the difference between two Goments as an integer.

g.Diff(goment.New(), 'years') // 3

ToUnix returns the Unix timestamp (the number of seconds since the Unix Epoch).

g.ToUnix() // 1360310950

DaysInMonth returns the number of days in the set month.

g.DaysInMonth() // 28

ToTime returns the time.Time object that is wrapped by Goment.

g.ToTime()

ToArray returns an array that mirrors the parameters from time.Date().

g.ToArray() // [2013 2 8 8 9 10 0]

ToDateTime returns a Goment.DateTime struct.

g.ToDateTime() // {2013 2 8 8 9 10 0 UTC}

ToString returns an English string representation of the Goment time.

g.ToString() // 2006-01-02 15:04:05.999999999 -0700 MST

ToISOString returns a ISO8601 standard representation of the Goment time.

g.ToISOString() // 2016-04-12T19:46:47.286Z

IsBefore will check if a Goment is before another Goment. Works with Goment struct or pointer to struct.

g.IsBefore(goment.New()) // true

IsAfter will check if a Goment is after another Goment. Works with Goment struct or pointer to struct.

g.IsAfter(goment.New()) // false

IsSame will check if a Goment is the same as another Goment. Works with Goment struct or pointer to struct.

g.IsSame(goment.New()) // true

IsSameOrBefore will check if a Goment is before or the same as another Goment. Works with Goment struct or pointer to struct.

g.IsSameOrBefore(goment.New()) // true

IsSameOrAfter will check if a Goment is after or the same as another Goment. Works with Goment struct or pointer to struct.

g.IsSameOrAfter(goment.New()) // false

IsBetween will check if a Goment is between two other Goments. Works with Goment struct or pointer to struct.

g.IsBetween(goment.New(), goment.New().Add(5, 'days)) // true

IsDST checks if the Goment is in daylight saving time.

g.IsDST() // true

IsLeapYear returns true if the Goment's year is a leap year, and false if it is not.

g.IsLeapYear() // false

IsTime will check if a variable is a time.Time object.

g.IsTime(time.Now()) // true

IsGoment will check if a variable is a Goment object. Works with Goment struct or pointer to struct.

g.IsGoment(goment.New()) // true

Goment has support for internationalization.

In addition to assigning a global locale, you can assign a locale to a specific Goment object.

* Currently, only formatting functions like Format, To, From, ToNow, FromNow & Calendar use locales. Only English (United States) datetime formats are able to be parsed at this time.

By default, Goment uses English (United States) locale strings. Changing the global locale does not affect existing Goment instances.

SetLocale("es")

Locale() // es

g.SetLocale("fr")

g.Locale() // fr

Returns a list of weekdays in the current locale. If the parameter provided is a bool value of true, the list returned will take the current locale's first day of week into consideration. If no true parameter is provided, the first day will always be Sunday for the locale.

g.SetLocale("en")
g.Weekdays() // [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ]

g.SetLocale("es")
g.Weekdays(true) // ["lunes", "martes", "miércoles", "jueves", "viernes", "sábado", "domingo"]
g.Weekdays() // ["domingo", "lunes", "martes", "miércoles", "jueves", "viernes", "sábado"]

Returns a list of abbreviated weekdays in the current locale. If the parameter provided is a bool value of true, the list returned will take the current locale's first day of week into consideration. If no true parameter is provided, the first day will always be Sunday for the locale.

g.SetLocale("en")
g.WeekdaysShort() // [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]

g.SetLocale("es")
g.WeekdaysShort(true) // ["lun.", "mar.", "mié.", "jue.", "vie.", "sáb.", "dom."]
g.WeedaysShort() // ["dom.", "lun.", "mar.", "mié.", "jue.", "vie.", "sáb."]

Returns a list of abbreviated weekdays in the current locale. If the parameter provided is a bool value of true, the list returned will take the current locale's first day of week into consideration. If no true parameter is provided, the first day will always be Sunday for the locale.

g.SetLocale("en")
g.WeekdaysMin() // [ "Su", "Mo", "Tu", "We", "Th", "Fr", "Sa" ]

g.SetLocale("es")
g.WeekdaysMin(true) // ["lu", "ma", "mi", "ju", "vi", "sá", "do"]
g.WeedaysMin() // ["do", "lu", "ma", "mi", "ju", "vi", "sá"]

Returns the weekday name by number in the current locale. If the first parameter is a bool value of true, the name returned will take the current locale's first day of week into consideration. If no true parameter is provided, the first day will always be Sunday for the locale.

g.SetLocale("en")
g.WeekdayByNumber(0) // "Sunday"
g.WeekdayByNumber(true, 0) // "Sunday"

g.SetLocale("es")
g.WeekdayByNumber(0) // "domingo"
g.WeekdayByNumber(true, 0) // "lunes"

Returns a list of months in the current locale.

g.Months() // [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ]

Returns the month name by number in the current locale.

g.MonthByNumber(1) // "January"

Returns a list of abbreviated month names in the current locale.

g.MonthsShort() // [ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ]

Returns the abbreviated month name by number in the current locale.

g.MonthShortByNumber(2) // "Feb"

To add a new locale, there are a few steps to follow. You must first add a new file in the /locales folder. This should be named the locale code, e.g. fr.go. Inside this file, you need to create a new LocaleDetails object and provide the required values for month names, weekday names, ordinal function, etc. Please use one of the existing locales for reference.

After you've created the locale file, add a line to locale.go in the supportedLocales map. This should be a map from the locale code to an instance of the LocaleDetails object you created above.

Lastly, please add test cases to locale_test.go that test the different datetime formats, and the relative time formats.