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

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

⚙️ Installation

go get

🚀 Quick Start

package main

import (
    tinytime ""

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

Need More Date Ranges? Go-TinyTime

Unix timestamps only supports dates from 1970 to 2106. Day-month-year supports dates from year 0 to year 65535. If you need a larger date range, take a look at go-tinydate which uses day-month-year underneath. Keep in mind go-tinydate doesn't support more than day precision.


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

go-tinytime 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 a date range larger than 1970-2106

💬 Contact

Twitter Follow

Submit an issue (above in the issues tab)



Tinytime mirrors the time.Time API for the most part. The only methods that are not included are the ones that makes no sense without timezone support.


All formatting is done via the time.Time package's formatting capabilites.

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
Expand ▾ Collapse ▴




This section is empty.


This section is empty.


This section is empty.


type TinyTime

type TinyTime struct {
	// contains filtered or unexported fields

    TinyTime -

    func FromTime

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

      FromTime converts a time.Time into a TinyTime all tinyTinyTime.TinyTimes are UTC timezone, so that conversion will be made here

      func New

      func New(unixSeconds uint32) TinyTime

        New creates a new TinyTime, 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() TinyTime

          Now returns the current time

          func Parse

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

            Parse a layout into a TinyTime

            func ParseInLocation

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

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

              func Unix

              func Unix(sec int64, nsec int64) TinyTime

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

                func (TinyTime) Add

                func (tt TinyTime) Add(d time.Duration) TinyTime

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

                  func (TinyTime) AddDate

                  func (tt TinyTime) AddDate(years int, months int, days int) TinyTime

                    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 (TinyTime) After

                    func (tt TinyTime) After(tu TinyTime) bool

                      After returns true if tt is after tu

                      func (TinyTime) AppendFormat

                      func (tt TinyTime) AppendFormat(b []byte, layout string) []byte

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

                        func (TinyTime) Before

                        func (tt TinyTime) Before(tu TinyTime) bool

                          Before returns true if tt is before tu

                          func (TinyTime) Clock

                          func (tt TinyTime) Clock() (hour, min, sec int)

                            Clock returns the hour, minute, and second within the day specified by tt

                            func (TinyTime) Date

                            func (tt TinyTime) Date() (year int, month time.Month, day int)

                              Date returns the readable numerical values of the date

                              func (TinyTime) Day

                              func (tt TinyTime) Day() int

                                Day retruns the day of the month as an integer

                                func (TinyTime) Equal

                                func (tt TinyTime) Equal(tu TinyTime) bool

                                  Equal returns true if the times are exactly the same

                                  func (TinyTime) Format

                                  func (tt TinyTime) Format(layout string) string

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

                                    func (*TinyTime) GobDecode

                                    func (tt *TinyTime) GobDecode(data []byte) error

                                      GobDecode implements the gob.GobDecoder interface

                                      func (TinyTime) GobEncode

                                      func (tt TinyTime) GobEncode() ([]byte, error)

                                        GobEncode implements the gob.GobEncoder interface

                                        func (TinyTime) Hour

                                        func (tt TinyTime) Hour() int

                                          Hour returns the hour within the day specified by tt, in the range [0, 23]

                                          func (TinyTime) ISOWeek

                                          func (tt TinyTime) 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 (TinyTime) IsZero

                                            func (tt TinyTime) IsZero() bool

                                              IsZero returns true if the time represents the the unix epoch time

                                              func (TinyTime) MarshalBinary

                                              func (tt TinyTime) MarshalBinary() ([]byte, error)

                                                MarshalBinary implements the encoding.BinaryMarshaler interface

                                                func (TinyTime) MarshalJSON

                                                func (tt TinyTime) MarshalJSON() ([]byte, error)

                                                  MarshalJSON implements the json.Marshaler interface

                                                  func (TinyTime) MarshalText

                                                  func (tt TinyTime) 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 (TinyTime) Minute

                                                    func (tt TinyTime) Minute() int

                                                      Minute returns the minute offset within the hour specified by tt, in the range [0, 59]

                                                      func (TinyTime) Month

                                                      func (tt TinyTime) Month() time.Month

                                                        Month returns the month 1-12

                                                        func (TinyTime) Round

                                                        func (tt TinyTime) Round(d time.Duration) time.Time

                                                          Round returns the result of rounding t to the nearest multiple of d (since the zero time). The rounding behavior for halfway values is to round up. If d <= 0, Round returns t stripped of any monotonic clock reading but otherwise unchanged.

                                                          Round operates on the time as an absolute duration since the zero time; it does not operate on the presentation form of the time. Thus, Round(Hour) may return a time with a non-zero minute, depending on the time's Location.

                                                          func (TinyTime) Second

                                                          func (tt TinyTime) Second() int

                                                            Second returns the second offset within the minute specified by tt, in the range [0, 59]

                                                            func (TinyTime) String

                                                            func (tt TinyTime) String() string

                                                              String returns the month formatted as a readable string

                                                              func (TinyTime) Sub

                                                              func (tt TinyTime) Sub(tu TinyTime) time.Duration

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

                                                                func (TinyTime) ToTime

                                                                func (tt TinyTime) ToTime() time.Time

                                                                  ToTime converts a tinyTinyTime.TinyTime to a time.Time, always UTC

                                                                  func (TinyTime) Truncate

                                                                  func (tt TinyTime) Truncate(d time.Duration) time.Time

                                                                    Truncate returns the result of rounding t down to a multiple of d (since the zero time). If d <= 0, Truncate returns t stripped of any monotonic clock reading but otherwise unchanged.

                                                                    Truncate operates on the time as an absolute duration since the zero time; it does not operate on the presentation form of the time. Thus, Truncate(Hour) may return a time with a non-zero minute, depending on the time's Location.

                                                                    func (TinyTime) Unix

                                                                    func (tt TinyTime) Unix() int64

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

                                                                      func (TinyTime) UnixNano

                                                                      func (tt TinyTime) UnixNano() int64

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

                                                                        func (*TinyTime) UnmarshalBinary

                                                                        func (tt *TinyTime) UnmarshalBinary(data []byte) error

                                                                          UnmarshalBinary implements the encoding.BinaryUnmarshaler interface

                                                                          func (*TinyTime) UnmarshalJSON

                                                                          func (tt *TinyTime) UnmarshalJSON(data []byte) error

                                                                            UnmarshalJSON implements the json.Unmarshaler interface.

                                                                            func (*TinyTime) UnmarshalText

                                                                            func (tt *TinyTime) UnmarshalText(data []byte) error

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

                                                                              func (TinyTime) Weekday

                                                                              func (tt TinyTime) Weekday() time.Weekday

                                                                                Weekday returns the day of the week

                                                                                func (TinyTime) Year

                                                                                func (tt TinyTime) Year() int

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

                                                                                  func (TinyTime) YearDay

                                                                                  func (tt TinyTime) 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