epochdate

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 30, 2016 License: BSD-3-Clause Imports: 3 Imported by: 5

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

View Source
const (
	RFC3339        = "2006-01-02"
	AmericanShort  = "1-2-06"
	AmericanCommon = "01-02-06"
)

Variables

View Source
var ErrOutOfRange = errors.New("The given date is out of range")

Functions

func UnixInRange

func UnixInRange(seconds int64) bool

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

func NewFromDate(year int, month time.Month, day int) (Date, error)

NewFromDate returns a Date value corresponding to the supplied year, month, and day.

func NewFromTime

func NewFromTime(t time.Time) (Date, error)

NewFromTime returns a Date equivalent to NewFromDate(t.Date()), where t is a time.Time object.

func NewFromUnix

func NewFromUnix(seconds int64) (d Date, err error)

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

func Parse(layout, value string) (d Date, err error)

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

func (d Date) AddDate(years int, months int, days int) Date

AddDate is semantically identical to the behavior of t.AddDate(), where t is a time.Time value.

func (Date) After

func (d Date) After(date Date) bool

Returns whether the date d is after date

func (Date) AfterTime

func (d Date) AfterTime(t time.Time) bool

Returns whether the date d is after t

func (Date) Before

func (d Date) Before(date Date) bool

Returns whether the date d is before date

func (Date) BeforeTime

func (d Date) BeforeTime(t time.Time) bool

Returns whether the date d is before t

func (Date) Date

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

Date is semantically identical to the behavior of t.Date(), where t is a time.Time value.

func (Date) Equals

func (d Date) Equals(date Date) bool

Returns whether the dates are equals

func (Date) EqualsTime

func (d Date) EqualsTime(t time.Time) bool

Returns whether the date is into the time (between 00:00:00 and 23:59:59)

func (Date) Format

func (d Date) Format(layout string) string

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

func (d Date) In(loc *time.Location) time.Time

In returns a location-relative Time object set to 00:00:00 on the given date.

func (Date) Local

func (d Date) Local() time.Time

Local returns a local Time object set to 00:00:00 on the given date.

func (Date) MarshalJSON

func (d Date) MarshalJSON() ([]byte, error)

func (*Date) Scan

func (d *Date) Scan(value interface{}) error

Scan implements the Scanner interface.

func (Date) String

func (d Date) String() string

Returns an RFC3339/ISO-8601 date string, of the form "2006-01-02".

func (Date) UTC

func (d Date) UTC() time.Time

UTC returns a UTC Time object set to 00:00:00 on the given date.

func (Date) UTCTime

func (d Date) UTCTime(hour int, min int, sec int, nsec int) time.Time

UTC returns a UTC Time object set to 00:00:00 on the given date.

func (Date) Unix

func (d Date) Unix() int64

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

func (d Date) UnixNano() int64

UnixNano is semantically identical to the Unix method, except that it returns elapsed nanoseconds.

func (*Date) UnmarshalJSON

func (d *Date) UnmarshalJSON(data []byte) (err error)

func (Date) Value

func (d Date) Value() (driver.Value, error)

Value implements the driver Valuer interface.

func (Date) Weekday

func (d Date) Weekday() time.Weekday

Calculate WeekDay

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL