timeofday

README

Value

The timeofday.Value type represents a "clock time" identified by hour, minute, second and fraction components. Internally, the value is a time.Duration made up of the sum of the four component values with the following formula:

value = (hh * 3.6e12) + (mm * 6e10) + (ss * 1e9) + fff)

The supported range of values is 00:00:00 (midnight) - 23:59:59.999999999 (one nanosecond before midnight). For simplicity, Value only supports 24-hour clocks.

Purpose

We provide an implementation of a "clock time" separate from the Go standard library's time.Time type because that type always includes both a date and time, time zone metadata in the Location field, and an internal monotonic clock. Most of that is unnecessary, and often unwanted, to simply represent a time of "08:30 am".

Using Value also avoids any complications for times that occur twice, or not at all, on Daylight Savings Time boundaries. A Value value of 01:45:00 always exists at exactly one point in the day. It does not occur twice when transitioning from STD to DST and it is not skipped when moving from DST to STD since there is no concept of Standard Time versus Daylight Savings Time.

Usage

Value values can be constructed from individual component values via the FromUnits() function or from a time.Duration value via FromDuration().

Below is a simple example of using a Value value:

package main

import (
    "fmt"
    "github.com/dylan-bourque/go-types/timeofday"
)

func main() {
    // create a value representing 1:30 am
    // . ignore the error because FromUnits() will never fail with valid unit values
    tod, _ := timeofday.FromUnits(1, 30, 0, 0)
    fmt.Println("The clock shows:", tod)
}

See the package documentation for more specific usage details.

Integration

For compatibility and integration with other packages, Value also implements the following standard interfaces:

• fmt.Stringer
• database/sql/driver.Valuer and database/sql.Scanner
• encoding.BinaryMarshaler and encoding.BinaryUnmarshaler
• encoding.TextMarshaler and encoding.TextUnmarshaler
• encoding/json.Marshaler and encoding/json.Unmarshaler

We also provide the NullTimeOfDay type that follows the conventions of database/sql.NullString for compatibility with database drivers that support NULL values.

Documentation

Index

• Variables
• func IsValid(t Value) bool
• func IsValidDuration(d time.Duration) bool
• func IsValidUnits(h, m, s int, ns int64) bool
• func ToDuration(t Value) time.Duration
• type NullTimeOfDay
  • func (t NullTimeOfDay) MarshalJSON() ([]byte, error)
  • func (t *NullTimeOfDay) Scan(src interface{}) error
  • func (t *NullTimeOfDay) UnmarshalJSON(d []byte) error
  • func (t NullTimeOfDay) Value() (driver.Value, error)
• type Value
  • func FromDuration(d time.Duration) (Value, error)
  • func FromUnits(h, m, s int, ns int64) (Value, error)
  • func Must(t Value, err error) Value
  • func ParseDuration(s string) (Value, error)
  • func ParseTime(s string) (Value, error)
  • func (t Value) Add(d time.Duration) Value
  • func (t Value) IsValid() bool
  • func (t Value) MarshalBinary() ([]byte, error)
  • func (t Value) MarshalJSON() ([]byte, error)
  • func (t Value) MarshalText() ([]byte, error)
  • func (t *Value) Scan(src interface{}) error
  • func (t Value) String() string
  • func (t Value) Sub(d time.Duration) Value
  • func (t Value) ToDateTimeInLocation(year int, month time.Month, day int, loc *time.Location) time.Time
  • func (t Value) ToDateTimeLocal(year int, month time.Month, day int) time.Time
  • func (t Value) ToDateTimeUTC(year int, month time.Month, day int) time.Time
  • func (t Value) ToUnits() (h, m, s int, ns int64)
  • func (t *Value) UnmarshalBinary(data []byte) error
  • func (t *Value) UnmarshalJSON(p []byte) error
  • func (t *Value) UnmarshalText(text []byte) error
  • func (t Value) Value() (driver.Value, error)

Variables

var (
	// ErrInvalidBinaryDataLen is returned from timeofday.Value.UnmarshalBinary() then the passed-in byte slice
	// is not exactly 8 bytes long
	ErrInvalidBinaryDataLen = errors.Errorf("timeofday.Value: binary data must be 8 bytes")
	// ErrInvalidTextDataLen is returned from timeofday.Value.UnmarshalText() when the passed-in byte slice
	// is not between 8 and 18 bytes long
	ErrInvalidTextDataLen = errors.Errorf("timeofday.Value: text data must be bewteen 8 and 18 bytes")
	// ErrInvalidTextData is returned from timeofday.Value.UnmarshalJSON() when the passed-in byte slice
	// does not contain a string
	ErrInvalidTextData = errors.Errorf("timeofday.Value: can only decode JSON strings")
	// ErrInvalidTimeFormat is returned from timeofday.Value.UnmarshalText() when the passed-in byte slice
	// is not formatted correctly
	ErrInvalidTimeFormat = errors.Errorf("timeofday.Value: text data was not in the correct format")
)

var (
	// Zero defines a "zero" clock time, which is equivalent to clock.Min
	Zero = Value{}
	// Min defines the minimum supported clock time, which is midnight (00:00:00)
	Min = Value{/* contains filtered or unexported fields */}
	// Max defines the maximum supported clock time, which is 1 nanosecond before midnight (23:59:59.999999999)
	Max = Value{/* contains filtered or unexported fields */}
)

var (
	// ErrInvalidUnit indicates that one or more of the specified unit values are out of the allowed range
	ErrInvalidUnit = errors.Errorf("One or more of the specified unit values are outside the valid range")
	// ErrInvalidDuration indicates that a time.Duration value cannot be converted to a Value value
	ErrInvalidDuration = errors.Errorf("The specified duration is outside the valid range for a Value value")
)

var (
	// ErrUnsupportedSourceType is returned by .Scan() when the provided value cannot be converted to
	// a timeofday.Value value
	ErrUnsupportedSourceType = errors.Errorf("Cannot convert the source data to a timeofday.Value value")
)

Functions

func IsValid

func IsValid(t Value) bool

IsValid returns true if t is a valid clock.Value value in the range [00:00:00 .. 24:00:00), false otherwise

func IsValidDuration

func IsValidDuration(d time.Duration) bool

IsValidDuration returns whether or not the specified time.Duration value can be used as a Value

func IsValidUnits

func IsValidUnits(h, m, s int, ns int64) bool

IsValidUnits returns whether or not the specified unit values are valid for a Value value

func ToDuration

func ToDuration(t Value) time.Duration

ToDuration returns a time.Duration value that is equivalent to summing the hours, minutes, seconds, and nanoseconds in t, or a duration of -1 nanosecond if t is invalid.

Types

type NullTimeOfDay

type NullTimeOfDay struct {
	TimeOfDay Value
	Valid     bool
}

NullTimeOfDay can be used with the standard sql package to represent a Value value that can be NULL in the database.

func (NullTimeOfDay) MarshalJSON

func (t NullTimeOfDay) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for NullTimeOfDay values

func (*NullTimeOfDay) Scan

func (t *NullTimeOfDay) Scan(src interface{}) error

Scan implements the sql.Scanner interface for NullTimeOfDay values

func (*NullTimeOfDay) UnmarshalJSON

func (t *NullTimeOfDay) UnmarshalJSON(d []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for NullTimeOfDay values

func (NullTimeOfDay) Value

func (t NullTimeOfDay) Value() (driver.Value, error)

Value implements the driver.Valuer interface for NullTimeOfDay values

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value defines a clock time (hh:mm:ss.fffffffff), independent of any date, time zone, Daylight Savings Time, etc. considerations.

Internally, the value is stored as a time.Duration value in the range [0ns...24h). The clock time is derived by partitioning the total duration into hours, minutes, seconds and nanoseconds.

func FromDuration

func FromDuration(d time.Duration) (Value, error)

FromDuration constructs a Value value from the specified duration

If the provided duration is outside of the supported range - [00:00:00 - 24:00:00) - an error is returned.

func FromUnits

func FromUnits(h, m, s int, ns int64) (Value, error)

FromUnits constructs a Value value from the provided unit values

If the specified units cannot be converted to a time.Duration or is outside of the supported range - [00:00:00 - 24:00:00) - an error is returned

func Must

func Must(t Value, err error) Value

Must is a helper that wraps a call to a function that returns (clock.Value, error) and panics if err is non-nil.

func ParseDuration

func ParseDuration(s string) (Value, error)

ParseDuration constructs a value from the specified duration string

func ParseTime

func ParseTime(s string) (Value, error)

ParseTime constructs a Value value from the specified time of day string

func (Value) Add

func (t Value) Add(d time.Duration) Value

Add adds the specified duration to t, normalizing the result to [00:00:00...24:00:00)

func (Value) IsValid

func (t Value) IsValid() bool

IsValid returns true if t is a valid clock.Value value in the range [00:00:00 .. 24:00:00), false otherwise

func (Value) MarshalBinary

func (t Value) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface for timeofday.Value values.

The resulting data is a 64-bit integer in big-endian byte order that contains the number of nanoseconds in the underlying time.Duration value.

func (Value) MarshalJSON

func (t Value) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface for timeofday.Value values. The JSON encoding is the same as MarshalText().

func (Value) MarshalText

func (t Value) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface for timeofday.Value values.

The encoded value is the same as is returned by the String() method

func (*Value) Scan

func (t *Value) Scan(src interface{}) error

Scan implements the sql.Scanner interface for Value values.

An 8-byte slice is handled by UnmarshalBinary() and a string is handled by UnmarshalText(). All other values will return an error

func (Value) String

func (t Value) String() string

String returns a string representation of the Value value, formatted as "hh:mm:ss.fffffffff", with the fractional portion omitted if it is zero or trailing zeros trimmed otherwise

func (Value) Sub

func (t Value) Sub(d time.Duration) Value

Sub adds the specified duration from t, normalizing the result to [00:00:00...24:00:00)

func (Value) ToDateTimeInLocation

func (t Value) ToDateTimeInLocation(year int, month time.Month, day int, loc *time.Location) time.Time

ToDateTimeInLocation composes the current timeofday.Value value with the specified year, month, day and location/time zone to generate a full time.Time value.

func (Value) ToDateTimeLocal

func (t Value) ToDateTimeLocal(year int, month time.Month, day int) time.Time

ToDateTimeLocal composes a timeofday.Value value with the specified year, month and day in the current local time zone.

func (Value) ToDateTimeUTC

func (t Value) ToDateTimeUTC(year int, month time.Month, day int) time.Time

ToDateTimeUTC composes a timeofday.Value value with the specified year, month and day in the UTC time zone.

func (Value) ToUnits

func (t Value) ToUnits() (h, m, s int, ns int64)

ToUnits returns the hour, minute, second and fractional components of a Value value

func (*Value) UnmarshalBinary

func (t *Value) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface for timeofday.Value values.

The provided value must be 8 bytes and contain a 64-bit integer value in big-endian byte order between 0 (00:00:00) and 86,399,999,000,000 (23:59:59.999999999).

If data is not 8 bytes, ErrInvalidBinaryDataLen is returned. If the unmarshalled integer value is out of range, ErrInvalidDuration is returned.

func (*Value) UnmarshalJSON

func (t *Value) UnmarshalJSON(p []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for timeofday.Value values.

If the value is the special JSON null token, t is set to timeofday.Zero. All other values are delegated to UnmarshalText().

func (*Value) UnmarshalText

func (t *Value) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for timeofday.Value values.

The supported format is "hh:mm:ss.ffffffff" with the following constraints: . "hh" must be 2 decimal digits between 00 and 23, representing the hour of the day . "mm" must be 2 decimal digits between 00 and 59, representing the minute of the hour . "ss" must be 2 decimal digits between 00 and 59, representing the second of the minute . ".fffffffff" is optional, if specified it must be between 1 and 9 decimal digits, respresenting

the fractional seconds up to nanosecond-level resolution

func (Value) Value

func (t Value) Value() (driver.Value, error)

Value implements the driver.Valuer interface for Value values. The returned value is the default string encoding, hh:mm:ss.fffffffff.