A tiny date object in Go. Tinydate uses 4 bytes of memory vs the 24 bytes of a standard time.Time{}

A tinydate only has day precision. It has no knowledge of hours, minutes, seconds, or timezones.

⚙️ Installation

go get

🚀 Quick Start

package main

import (
    tinydate ""

func main(){
    td, err := tinydate.New(2020, 04, 3)
	if err != nil {
    td = td.Add(time.Hour * 48)
    // prints 2020-04-05

Need Second Precision? Go-TinyTime

I've had people ask why go-tinydate doesn't use unix time as the underlying data, rather than day-month-year. Day-month-year supports dates from year 0 to year 65535. Unix timestamps only supports dates from 1970 to 2106. If you need more precision, take a look at go-tinytime which uses unix time underneath and supports second precision.


If you don't have resource constraints, then don't use tinydate! Use the standard time pacakge.

go-tinydate works well in the following situations:

  • You are working in embedded systems where memory is a luxury
  • You are storing many dates and smaller memory footprint is desired
  • You are 101% sure you don't need more than date precision


I needed to store many thousands of dates in memory in order to keep track of which IDs I had seen in the last X number of days. As such, I had a giant map[int]time.Time. Switching from map[int]time.Time to map[int]tinydate.TinyDate reduced my program's memory from an average ~1GB to ~200MB.

💬 Contact

Twitter Follow

Submit an issue (above in the issues tab)



Tinydate mirrors the time.Time API for the most part. The only methods that are not included are the ones that makes no sense with only day precision, or without timezones apart from UTC.


All formatting is done via the time.Time package's formatting capabilites, but anything besides date data will be zeroed out for obvious reasons.

Transient Dependencies

None! And it will stay that way, except of course for the standard library.

Note: Currently the testify package is used only for testing, but that dependency will be removed in coming updates.

👏 Contributing

I love help! Contribute by forking the repo and opening pull requests. Please ensure that your code passes the existing tests and linting, and write tests to test your changes if applicable.

All pull requests should be submitted to the "master" branch.

go test
go fmt




This section is empty.


This section is empty.


This section is empty.


type TinyDate

type TinyDate struct {
	// contains filtered or unexported fields

    TinyDate -

    func FromTime

    func FromTime(t time.Time) (TinyDate, error)

      FromTime converts a time.Time into a TinyDate all tinyTinyDate.TinyDates are UTC timezone, so that conversion will be made here

      func New

      func New(year, month, day int) (TinyDate, error)

        New creates a new TinyDate, similar to the time.Time package, months are specifed from 1-12, and days are specified 1-31, depending on the month

        func Now

        func Now() TinyDate

          Now returns the current date

          func Parse

          func Parse(layout, value string) (TinyDate, error)

            Parse a layout into a TinyDate, truncating any non-date information

            func ParseInLocation

            func ParseInLocation(layout, value string, loc *time.Location) (TinyDate, error)

              ParseInLocation parses a layout into a TinyDate including a location. The input is converted into UTC

              func Unix

              func Unix(sec int64, nsec int64) TinyDate

                Unix creates a tinydate from seconds and nanoseconds. As usual, this is truncated to the nearest day

                func (TinyDate) Add

                func (td TinyDate) Add(d time.Duration) TinyDate

                  Add a duration to a TinyDate. Will only have an effect if more than 1 day is added

                  func (TinyDate) AddDate

                  func (td TinyDate) AddDate(years int, months int, days int) TinyDate

                    AddDate returns the time corresponding to adding the given number of years, months, and days to t. For example, AddDate(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.

                    func (TinyDate) After

                    func (td TinyDate) After(tu TinyDate) bool

                      After returns true if td is after tu

                      func (TinyDate) AppendFormat

                      func (td TinyDate) AppendFormat(b []byte, layout string) []byte

                        AppendFormat is like Format but appends the textual representation to b and returns the extended buffer

                        func (TinyDate) Before

                        func (td TinyDate) Before(tu TinyDate) bool

                          Before returns true if td is before tu

                          func (TinyDate) Date

                          func (td TinyDate) Date() (year int, month time.Month, day int)

                            Date returns the readable numerical values of the date

                            func (TinyDate) Day

                            func (td TinyDate) Day() int

                              Day retruns the day of the month as an integer

                              func (TinyDate) Equal

                              func (td TinyDate) Equal(tu TinyDate) bool

                                Equal returns true if the dates are exactly the same

                                func (TinyDate) Format

                                func (td TinyDate) Format(layout string) string

                                  Format returns a formatted date, as specified by the standard time library

                                  func (*TinyDate) GobDecode

                                  func (td *TinyDate) GobDecode(data []byte) error

                                    GobDecode implements the gob.GobDecoder interface

                                    func (TinyDate) GobEncode

                                    func (td TinyDate) GobEncode() ([]byte, error)

                                      GobEncode implements the gob.GobEncoder interface

                                      func (TinyDate) ISOWeek

                                      func (td TinyDate) ISOWeek() (year, week int)

                                        ISOWeek returns the ISO 8601 year and week number in which t occurs. Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1 of year n+1.

                                        func (TinyDate) IsZero

                                        func (td TinyDate) IsZero() bool

                                          IsZero returns true if the date represents the first day, January 01, 0000

                                          func (TinyDate) MarshalBinary

                                          func (td TinyDate) MarshalBinary() ([]byte, error)

                                            MarshalBinary implements the encoding.BinaryMarshaler interface

                                            func (TinyDate) MarshalJSON

                                            func (td TinyDate) MarshalJSON() ([]byte, error)

                                              MarshalJSON implements the json.Marshaler interface

                                              func (TinyDate) MarshalText

                                              func (td TinyDate) MarshalText() ([]byte, error)

                                                MarshalText implements the encoding.TextMarshaler interface. The time is formatted in RFC 3339 format, with sub-second precision added if present.

                                                func (TinyDate) Month

                                                func (td TinyDate) Month() time.Month

                                                  Month returns the month of the date 1-12

                                                  func (TinyDate) String

                                                  func (td TinyDate) String() string

                                                    String returns the month formatted as a readable string

                                                    func (TinyDate) Sub

                                                    func (td TinyDate) Sub(tu TinyDate) time.Duration

                                                      Sub returns the duration (in days) between td and tu

                                                      func (TinyDate) ToTime

                                                      func (td TinyDate) ToTime() time.Time

                                                        ToTime converts a tinyTinyDate.TinyDate to a time.Time, always UTC

                                                        func (TinyDate) Unix

                                                        func (td TinyDate) Unix() int64

                                                          Unix returns the date as a Unix timestamp where the precision is only to the day. Hours, minutes, and seconds are just padded zeros

                                                          func (TinyDate) UnixNano

                                                          func (td TinyDate) UnixNano() int64

                                                            UnixNano returns the date as a Unix timestamp in nanoseconds where the precision is only to the day. Hours, minutes, seconds and nanoseconds are just padded zeros

                                                            func (*TinyDate) UnmarshalBinary

                                                            func (td *TinyDate) UnmarshalBinary(data []byte) error

                                                              UnmarshalBinary implements the encoding.BinaryUnmarshaler interface

                                                              func (*TinyDate) UnmarshalJSON

                                                              func (td *TinyDate) UnmarshalJSON(data []byte) error

                                                                UnmarshalJSON implements the json.Unmarshaler interface.

                                                                func (*TinyDate) UnmarshalText

                                                                func (td *TinyDate) UnmarshalText(data []byte) error

                                                                  UnmarshalText implements the encoding.TextUnmarshaler interface. The time is expected to be in RFC 3339 format.

                                                                  func (TinyDate) Weekday

                                                                  func (td TinyDate) Weekday() time.Weekday

                                                                    Weekday returns the day of the week

                                                                    func (TinyDate) Year

                                                                    func (td TinyDate) Year() int

                                                                      Year returns the year as the readable numerical value e.g. 2020

                                                                      func (TinyDate) YearDay

                                                                      func (td TinyDate) YearDay() int

                                                                        YearDay returns the day of the year specified by t, in the range [1,365] for non-leap years, and [1,366] in leap years


                                                                        Path Synopsis