README
¶
epochdate
epochdate is a small library for storing contemporary dates (without time-of-day information) in 2 bytes per date, instead of the 16-20 bytes that are used by a time.Time value from the Go standard library.
epochdate.Date is a uint16 value representing the number of days since Jan 1 1970. The maximum representable date is Jun 6 2149. Arithmetical operations react predictably.
import (
"github.com/extemporalgenome/epochdate"
"time"
)
var (
today = epochdate.Today()
yesterday = today - 1
tomorrow = today + 1
fortnight = today + 7*2
)
Converting to Date values
assert := func(condition bool) { if !condition { panic("assertion failed") } }
d1, _ := epochdate.Parse(epochdate.RFC3339, "2012-03-10")
d2, _ := epochdate.NewFromDate(2012, 3, 10)
assert(d1 == d2)
times := []string{
// Any time of the same day forms an equivalent epochdate value
"2012-03-10T00:00:00Z",
"2012-03-10T23:59:59Z",
// And this is relative to location -- even locations that are
// 26 hours apart (politics) will result in the same epochdate value
// (in each location, the date at the given instant *is* 2012-03-10)
"2012-03-10T00:00:00-12:00",
"2012-03-10T00:00:00+14:00",
}
for _, str := range times {
t, _ := time.Parse(time.RFC3339, str)
d, _ := epochdate.NewFromTime(t)
assert(d == d1)
}
t1, _ := time.Parse(time.RFC3339, "2012-03-10T00:00:00-12:00")
t2, _ := time.Parse(time.RFC3339, "2012-03-10T00:00:00+14:00")
d1, _ := epochdate.NewFromUnix(t1.Unix())
d2, _ := epochdate.NewFromUnix(t2.Unix())
// t1.Unix() returns seconds since the Unix epoch relative to UTC!
// Because t1 and t2 represent very different time instants
// (26 hours apart), don't expect passing those timestamps to NewFromUnix
// to result in the same date; unless you know what you're doing, use the
// other "New" functions instead, which normalize timezones.
assert(d1 != d2)
Converting from Date values
var (
d, _ = epochdate.Parse(epochdate.RFC3339, "2012-03-10")
t, _ = time.Parse(time.RFC3339, "2012-03-10T00:00:00Z")
year1, month1, day1 = d.Date()
year2, month2, day2 = t.Date()
)
assert(year1 == year2 && month1 == month2 && day1 == day2)
assert(t.Equal(d.UTC()) == true)
// epochdate's Local and In methods return times adjusted to midnight on
// that date in the given timezone.
assert(t.Equal(d.Local()) == false)
// So if you want the local time at the instant that it was midnight on
// that date relative to UTC, do d.UTC().Local(). Conversely, the UTC time
// at the instant that it was midnight on the given date in the local
// timezone is expressed as: d.Local().UTC()
// Date values print nicely
assert(d.String() == "2012-03-10")
Documentation
¶
Overview ¶
Represents dates from Jan 1 1970 - Jun 6 2149 as days since the Unix epoch. This format requires 2 bytes (it's a uint16), in contrast to the 16 or 20 byte representations (on 32 or 64-bit systems, respectively) used by the standard time package.
Timezone is accounted for when applicable; when converting from standard time format into a Date, the date relative to the time value's zone is retained. Times at any point during a given day (relative to timezone) are normalized to the same date.
Conversely, conversions back to standard time format may be done using the Local, UTC, and In methods (semantically corresponding to the same-named Time methods), but with the result normalized to midnight (the beginning of the day) relative to that timezone.
All functions and methods with the same names as those found in the stdlib time package have identical semantics in epochdate, with the exception that epochdate truncates time-of-day information.
Index ¶
- Constants
- Variables
- func UnixInRange(seconds int64) bool
- type Date
- func (d Date) AddDate(years int, months int, days int) Date
- func (d Date) After(date Date) bool
- func (d Date) AfterTime(t time.Time) bool
- func (d Date) Before(date Date) bool
- func (d Date) BeforeTime(t time.Time) bool
- func (d Date) Date() (year int, month time.Month, day int)
- func (d Date) Equals(date Date) bool
- func (d Date) EqualsTime(t time.Time) bool
- func (d Date) Format(layout string) string
- func (d Date) In(loc *time.Location) time.Time
- func (d Date) Local() time.Time
- func (d Date) MarshalJSON() ([]byte, error)
- func (d *Date) Scan(value interface{}) error
- func (d Date) String() string
- func (d Date) UTC() time.Time
- func (d Date) UTCTime(hour int, min int, sec int, nsec int) time.Time
- func (d Date) Unix() int64
- func (d Date) UnixNano() int64
- func (d *Date) UnmarshalJSON(data []byte) (err error)
- func (d Date) Value() (driver.Value, error)
- func (d Date) Weekday() time.Weekday
Constants ¶
const ( RFC3339 = "2006-01-02" AmericanShort = "1-2-06" AmericanCommon = "01-02-06" )
Variables ¶
var ErrOutOfRange = errors.New("The given date is out of range")
Functions ¶
func UnixInRange ¶
UnixInRange is true if the provided Unix timestamp is in Date's representable range. The timestamp is interpreted according to the semantics used by NewFromUnix. You probably won't need to use this, since this will only return false if NewFromUnix returns an error of ErrOutOfRange.
Types ¶
type Date ¶
type Date uint16
func NewFromDate ¶
NewFromDate returns a Date value corresponding to the supplied year, month, and day.
func NewFromTime ¶
NewFromTime returns a Date equivalent to NewFromDate(t.Date()), where t is a time.Time object.
func NewFromUnix ¶
NewFromUnix creates a Date from a Unix timestamp, relative to any location Specifically, if you pass in t.Unix(), where t is a time.Time value with a non-UTC zone, you may receive an unexpected Date. Unless this behavior is specifically desired (returning the date in one location at the given time instant in another location), it's best to use epochdate.NewFromTime(t), which normalizes the resulting Date value by adjusting for zone offsets.
func Parse ¶
Parse follows the same semantics as time.Parse, but ignores time-of-day information and returns a Date value.
func Today ¶
func Today() Date
Today returns the local date at this instant. If the local date does not fall within the representable range, then then zero value will be returned (1970-01-01).
func TodayUTC ¶
func TodayUTC() Date
TodayUTC returns the date at this instant, relative to UTC. If the UTC date does not fall within the representable range, then then zero value will be returned (1970-01-01).
func (Date) AddDate ¶
AddDate is semantically identical to the behavior of t.AddDate(), where t is a time.Time value.
func (Date) BeforeTime ¶
Returns whether the date d is before t
func (Date) Date ¶
Date is semantically identical to the behavior of t.Date(), where t is a time.Time value.
func (Date) EqualsTime ¶
Returns whether the date is into the time (between 00:00:00 and 23:59:59)
func (Date) Format ¶
Identical to time.Time.Format, except that any time-of-day format specifiers that are used will be equivalent to "00:00:00Z".
func (Date) MarshalJSON ¶
func (Date) Unix ¶
Unix returns the number of seconds elapsed since Jan 1 1970 UTC, from the start of the given date value. In this case, the date is considered to be a UTC date, rather than a location-independent date.
func (Date) UnixNano ¶
UnixNano is semantically identical to the Unix method, except that it returns elapsed nanoseconds.
Source Files