timestamp

README

timestamp

The timestamp package provides a time.Time "compatible" way of keeping time stamps, using less space (single int64) and no pointers.

It implements most of time.Time functions, so switching to it should require only minimal work (most of the time the only thing required is replacing time.Time with timestamp.TS and time.Now() with timestamp.Now()).

Functions are provided for converting between time.Time and timestamp.TS (timestamp.Timestamp(t)) and vice-versa (timestamp.Time()).

The time stamp is kept in nanoseconds.

Limitations

• timestamps are limited to ~ 1970 +/- 292 years

• to check for out-of-range when converting from a time.Time value, one has to compare both with timestamp.MinTS and timestamp.MaxTS

• string representation uses always UTC (since timezones are not supported). To use a different representation one has to go through time.Time, for example via timestamp.In:

   ts := timestamp.Now()
   fmt.Printf("ts UTC: %s , local: %s\n", ts, ts.In(time.Local))
  

Documentation

Index

• func AtomicStore(ts *TS, v TS)
• func OutOfRange(t time.Time) bool
• type TS
  • func AtomicLoad(ts *TS) TS
  • func DurationToTS(d time.Duration) TS
  • func Now() TS
  • func Timestamp(t time.Time) TS
  • func Unix(sec int64, nsec int64) TS
  • func Zero() TS
  • func (ts TS) Add(d time.Duration) TS
  • func (ts TS) AddDate(years, months, days int) TS
  • func (ts TS) AddTS(ts2 TS) TS
  • func (ts TS) After(ts2 TS) bool
  • func (ts TS) AfterTime(t time.Time) bool
  • func (ts TS) Before(ts2 TS) bool
  • func (ts TS) BeforeTime(t time.Time) bool
  • func (ts TS) Duration() time.Duration
  • func (ts TS) Equal(ts2 TS) bool
  • func (ts TS) EqualTS(ts2 TS) bool
  • func (ts TS) EqualTime(t time.Time) bool
  • func (ts TS) Format(layout string) string
  • func (ts TS) In(loc *time.Location) time.Time
  • func (ts TS) IsZero() bool
  • func (ts TS) Location() *time.Location
  • func (ts TS) MarshalBinary() ([]byte, error)
  • func (ts TS) MarshalJSON() ([]byte, error)
  • func (ts TS) MarshalText() ([]byte, error)
  • func (ts TS) String() string
  • func (ts TS) Sub(ts2 TS) time.Duration
  • func (ts TS) SubTime(t time.Time) time.Duration
  • func (ts TS) Time() time.Time
  • func (ts TS) Truncate(d time.Duration) TS
  • func (ts TS) TruncateTime(d time.Duration) time.Time
  • func (ts TS) Unix() int64
  • func (ts TS) UnixNano() int64

Functions

func AtomicStore

func AtomicStore(ts *TS, v TS)

AtomicStore changes atomically ts value.

func OutOfRange

func OutOfRange(t time.Time) bool

OutOfRange returns true if t is out of the timestamp representation range ( ~ 1970 +/- 292 years).

Types

type TS

type TS time.Duration

A TS represents a time stamp with nanosecond precision. The zero value (Zero() method) correspond to the 0 unix time: 01.01.1970 00:00:00 UTC.

The timestamp range is approx. the zero unix time (1970) +/- 292 years.

All conversion to time.Time use UTC.

const (
	MaxTS TS = 1<<63 - 1
	MinTS TS = -1 << 63
)

func AtomicLoad

func AtomicLoad(ts *TS) TS

AtomicLoad reads atomically the ts value.

func DurationToTS

func DurationToTS(d time.Duration) TS

DurationToTS returns the time stamp corresponding to a given time.Duration.

func Now

func Now() TS

Now returns the current time as a time stamp.

func Timestamp

func Timestamp(t time.Time) TS

Timestamp returns the time stamp corresponding to the given time (time.Time).// If it exceeds the maximum TS range it will return MaxTS or MinTS. The zero time.Time is specially handled and converted to a 0 timestamp (otherwise would be an out-of-range value).

func Unix

func Unix(sec int64, nsec int64) TS

Unix returns the local time stamp corresponding to the given unix time. See time.Unix for more details.

func Zero

func Zero() TS

Zero returns the time stamp corresponding to the zero value

func (TS) Add

func (ts TS) Add(d time.Duration) TS

Add returns the time stamp corresponding to ts+d.

func (TS) AddDate

func (ts TS) AddDate(years, months, days int) TS

AddDate returns the time stamp corresponding to ts + date.

func (TS) AddTS

func (ts TS) AddTS(ts2 TS) TS

AddTS returns the time stamp corresponding to ts+ts2.

func (TS) After

func (ts TS) After(ts2 TS) bool

After returns true if ts > ts.

func (TS) AfterTime

func (ts TS) AfterTime(t time.Time) bool

After returns true if ts > t, where t is a time.Time. Note that the result is undefined if t is outside the timestamp representation range.

func (TS) Before

func (ts TS) Before(ts2 TS) bool

Before returns if ts < ts2.

func (TS) BeforeTime

func (ts TS) BeforeTime(t time.Time) bool

Before returns if ts < t, where t is a time.Time Note that the result is undefined if t is outside the timestamp representation range.

func (TS) Duration

func (ts TS) Duration() time.Duration

Duration returns the time stamp converted to duration.

func (TS) Equal

func (ts TS) Equal(ts2 TS) bool

Equal returns if ts == ts2.

func (TS) EqualTS

func (ts TS) EqualTS(ts2 TS) bool

EqualTS returns if ts == ts2

func (TS) EqualTime

func (ts TS) EqualTime(t time.Time) bool

EqualTime returns if ts == t, where t is a time.Time. Note that the result is undefined if t is outside the timestamp representation range.

func (TS) Format

func (ts TS) Format(layout string) string

Format returns a string representation of ts using time.Format(layout).

func (TS) In

func (ts TS) In(loc *time.Location) time.Time

In returns the time stamp converted to time in the specified location. See also Time() and time.In(loc).

func (TS) IsZero

func (ts TS) IsZero() bool

IsZero returns if ts represents the zero timestamp.

func (TS) Location

func (ts TS) Location() *time.Location

Location returns the time zone information associated to the timestamp. It will always return UTC, since timestamps use only UTC.

func (TS) MarshalBinary

func (ts TS) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (TS) MarshalJSON

func (ts TS) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (TS) MarshalText

func (ts TS) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (TS) String

func (ts TS) String() string

Sting returns the default string representation for the timestamp. (see time.String for more details) Since timestamps do not store a timezone, the string representation will always use UTC.

func (TS) Sub

func (ts TS) Sub(ts2 TS) time.Duration

Sub returns the difference ts - ts2.

func (TS) SubTime

func (ts TS) SubTime(t time.Time) time.Duration

Sub returns the difference ts - t., where t is a time.Time. Note that the result is undefined if t is outside the timestamp representation range.

func (TS) Time

func (ts TS) Time() time.Time

Time returns the time stamp converted to time. The 0 timestamp value is specially handled and converted to the zero time.Time (since otherwise the 0 timestamp would correpond to time.Unix(0,0).UTC()).

func (TS) Truncate

func (ts TS) Truncate(d time.Duration) TS

Truncate returns the result of rounding ts down to d (see time.Truncate() for more details).

func (TS) TruncateTime

func (ts TS) TruncateTime(d time.Duration) time.Time

Truncate returns the result of rounding ts down to d (see time.Truncate() for more details).

func (TS) Unix

func (ts TS) Unix() int64

Unix returns ts as Unix time (number of seconds since January 1, 1970 UTC)

func (TS) UnixNano

func (ts TS) UnixNano() int64

UnixNanno returns ts as Unix time (number of nanoseconds since January 1, 1970 UTC)