clock

Documentation

Overview

Package clock specifies a time of day with resolution to the nearest millisecond.

Index

• Variables
• func ValueAsNumber(c Clock) driver.Value
• func ValueAsString(c Clock) driver.Value
• type Clock
  • func MustParse(hms string) Clock
  • func New(hour, minute, second, millisec int) Clock
  • func NewAt(t time.Time) Clock
  • func Parse(hms string) (clock Clock, err error)
  • func SinceMidnight(d time.Duration) Clock
  • func (c Clock) Add(h, m, s, ms int) Clock
  • func (c Clock) AddDuration(d time.Duration) Clock
  • func (c Clock) AddPeriod(p period.Period) (Clock, bool)
  • func (c Clock) Days() int
  • func (c Clock) DurationSinceMidnight() time.Duration
  • func (c Clock) Hh() string
  • func (c Clock) Hh12() string
  • func (c Clock) HhMm() string
  • func (c Clock) HhMm12() string
  • func (c Clock) HhMmSs() string
  • func (c Clock) HhMmSs12() string
  • func (c Clock) Hour() int
  • func (c Clock) HourMinuteSecond() (int, int, int)
  • func (c Clock) IsInOneDay() bool
  • func (c Clock) IsMidnight() bool
  • func (c Clock) MarshalBinary() (b []byte, err error)
  • func (c Clock) MarshalText() ([]byte, error)
  • func (c Clock) Millisecond() int
  • func (c Clock) Minute() int
  • func (c Clock) Mod24() Clock
  • func (c Clock) ModSubtract(c2 Clock) time.Duration
  • func (c Clock) Nanosecond() int
  • func (c *Clock) Scan(value interface{}) (err error)
  • func (c Clock) Second() int
  • func (c Clock) String() string
  • func (c Clock) TruncateMillisecond() Clock
  • func (c *Clock) UnmarshalBinary(data []byte) error
  • func (c *Clock) UnmarshalText(data []byte) (err error)
  • func (c Clock) Value() (driver.Value, error)

Variables

var Valuer = ValueAsNumber

Valuer is a pluggable function for writing Clock values to a DB.

Functions

func ValueAsNumber

func ValueAsNumber(c Clock) driver.Value

ValueAsNumber simply returns the numeric value of a Clock.

func ValueAsString

func ValueAsString(c Clock) driver.Value

ValueAsString returns the string value of a Clock.

Types

type Clock

type Clock int64

Clock specifies a time of day. It complements the existing time.Duration, applying that to the time since midnight (on some arbitrary day in some arbitrary timezone). The resolution is to the nearest nanosecond, like time.Duration.

It is not intended that Clock be used to represent periods greater than 24 hours nor negative values. However, for such lengths of time, a fixed 24 hours per day is assumed and a modulo operation Mod24 is provided to discard whole multiples of 24 hours.

Clock is a type of integer (actually int64), so values can be compared and sorted as per other integers. The constants Second, Minute, Hour and Day can be added and subtracted with obvious outcomes.

See https://en.wikipedia.org/wiki/ISO_8601#Times

const (
	// Millisecond is one millisecond; it has a similar meaning to time.Millisecond.
	Millisecond Clock = Clock(time.Millisecond)

	// Second is one second; it has a similar meaning to time.Second.
	Second Clock = Clock(time.Second)

	// Minute is one minute; it has a similar meaning to time.Minute.
	Minute Clock = Clock(time.Minute)

	// Hour is one hour; it has a similar meaning to time.Hour.
	Hour Clock = Clock(time.Hour)

	// Day is a fixed period of 24 hours. This does not take account of daylight savings,
	// so is not fully general.
	Day Clock = Clock(time.Hour * 24)
)

Common durations - second, minute, hour and day.

const Midnight Clock = 0

Midnight is the zero value of a Clock.

const Noon Clock = Hour * 12

Noon is at 12pm.

const Undefined Clock = Clock(math.MinInt64)

Undefined is provided because the zero value of a Clock *is* defined (i.e. Midnight). So a special value is chosen, which is math.MinInt64.

func MustParse

func MustParse(hms string) Clock

MustParse is as per Parse except that it panics if the string cannot be parsed. This is intended for setup code; don't use it for user inputs.

func New

func New(hour, minute, second, millisec int) Clock

New returns a new Clock with specified hour, minute, second and millisecond. To set sub-millisecond digits, chain this with AddDuration.

func NewAt

func NewAt(t time.Time) Clock

NewAt returns a new Clock with specified hour, minute, seconds (to nanosecond resolution).

func Parse

func Parse(hms string) (clock Clock, err error)

Parse converts a string representation to a Clock. Acceptable representations are as per ISO-8601 - see https://en.wikipedia.org/wiki/ISO_8601#Times

Also, conventional AM- and PM-based strings are parsed, such as "2am", "2:45pm". Remember that 12am is midnight and 12pm is noon.

func SinceMidnight

func SinceMidnight(d time.Duration) Clock

SinceMidnight returns a new Clock based on a duration since some arbitrary midnight.

func (Clock) Add

func (c Clock) Add(h, m, s, ms int) Clock

Add returns a new Clock offset from this clock specified hour, minute, second and millisecond. The parameters can be negative.

If required, use Mod24() to correct any overflow or underflow.

func (Clock) AddDuration

func (c Clock) AddDuration(d time.Duration) Clock

AddDuration returns a new Clock offset from this clock by a duration. The parameter can be negative.

If required, use Mod24() to correct any overflow or underflow.

func (Clock) AddPeriod

func (c Clock) AddPeriod(p period.Period) (Clock, bool)

AddPeriod returns a new Clock offset from this clock by a time period. The parameter can be negative.

If required, use Mod24() to correct any overflow or underflow.

The boolean flag is true when the result is precise and false if an approximation.

func (Clock) Days

func (c Clock) Days() int

Days gets the number of whole days represented by the Clock, assuming that each day is a fixed 24 hour period. Negative values are treated so that the range -23h59m59s to -1s is fully enclosed in a day numbered -1, and so on. This means that the result is zero only for the clock range 0s to 23h59m59s, for which IsInOneDay() returns true.

func (Clock) DurationSinceMidnight

func (c Clock) DurationSinceMidnight() time.Duration

DurationSinceMidnight convert a clock to a time.Duration since some arbitrary midnight.

func (Clock) Hh

func (c Clock) Hh() string

Hh gets the clock-face number of hours as a two-digit string. It is calculated from the modulo time; see Mod24. Note the special case of midnight at the end of a day is "24".

func (Clock) Hh12

func (c Clock) Hh12() string

Hh12 gets the clock-face number of hours as a one- or two-digit string, followed by am or pm. Remember that midnight is 12am, noon is 12pm. It is calculated from the modulo time; see Mod24.

func (Clock) HhMm

func (c Clock) HhMm() string

HhMm gets the clock-face number of hours and minutes as a five-character ISO-8601 time string. It is calculated from the modulo time; see Mod24. Note the special case of midnight at the end of a day is "24:00".

func (Clock) HhMm12

func (c Clock) HhMm12() string

HhMm12 gets the clock-face number of hours and minutes, followed by am or pm. Remember that midnight is 12am, noon is 12pm. It is calculated from the modulo time; see Mod24.

func (Clock) HhMmSs

func (c Clock) HhMmSs() string

HhMmSs gets the clock-face number of hours, minutes, seconds as an eight-character ISO-8601 time string. It is calculated from the modulo time; see Mod24. Note the special case of midnight at the end of a day is "24:00:00".

func (Clock) HhMmSs12

func (c Clock) HhMmSs12() string

HhMmSs12 gets the clock-face number of hours, minutes and seconds, followed by am or pm. Remember that midnight is 12am, noon is 12pm. It is calculated from the modulo time; see Mod24.

func (Clock) Hour

func (c Clock) Hour() int

Hour gets the clock-face number of hours (calculated from the modulo time, see Mod24).

func (Clock) HourMinuteSecond

func (c Clock) HourMinuteSecond() (int, int, int)

HourMinuteSecond gets the hours, minutes and seconds values (calculated from the modulo time, see Mod24).

func (Clock) IsInOneDay

func (c Clock) IsInOneDay() bool

IsInOneDay tests whether a clock time is in the range 0 to 24 hours, inclusive. Inside this range, a Clock is generally well-behaved. But outside it, there may be errors due to daylight savings. Note that 24:00:00 is included as a special case as per ISO-8601 definition of midnight.

func (Clock) IsMidnight

func (c Clock) IsMidnight() bool

IsMidnight tests whether a clock time is midnight. This is shorthand for c.Mod24() == 0. For large values, this assumes that every day has 24 hours.

func (Clock) MarshalBinary

func (c Clock) MarshalBinary() (b []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (Clock) MarshalText

func (c Clock) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (Clock) Millisecond

func (c Clock) Millisecond() int

Millisecond gets the clock-face number of milliseconds within the second specified by c (calculated from the modulo time, see Mod24), in the range [0, 999]. For example, for 10:20:30.456 this will return 456.

func (Clock) Minute

func (c Clock) Minute() int

Minute gets the clock-face number of minutes (calculated from the modulo time, see Mod24). For example, for 22:35 this will return 35.

func (Clock) Mod24

func (c Clock) Mod24() Clock

Mod24 calculates the remainder vs 24 hours using Euclidean division, in which the result will be less than 24 hours and is never negative. Note that this imposes the assumption that every day has 24 hours (not correct when daylight saving changes in any timezone).

https://en.wikipedia.org/wiki/Modulo_operation

func (Clock) ModSubtract

func (c Clock) ModSubtract(c2 Clock) time.Duration

ModSubtract returns the duration between two clock times.

If c2 is before c (i.e. c2 < c), the result is the duration computed from c - c2.

But if c is before c2, it is assumed that c is after midnight and c2 is before midnight. The result is the sum of the evening time from c2 to midnight with the morning time from midnight to c. This is the same as Mod24(c - c2).

func (Clock) Nanosecond

func (c Clock) Nanosecond() int

Nanosecond gets the clock-face number of nanoseconds within the second specified by c (calculated from the modulo time, see Mod24), in the range [0, 999999999]. For example, for 10:20:30.456111222 this will return 456111222.

func (*Clock) Scan

func (c *Clock) Scan(value interface{}) (err error)

Scan parses some value. It implements sql.Scanner, https://golang.org/pkg/database/sql/#Scanner

func (Clock) Second

func (c Clock) Second() int

Second gets the clock-face number of seconds (calculated from the modulo time, see Mod24). For example, for 10:20:30 this will return 30.

func (Clock) String

func (c Clock) String() string

String gets the clock-face number of hours, minutes, seconds and fraction as an ISO-8601 time string.

If the clock value has more than 24 hours, the excess is discarded (see Mod24).

The number of decimal places depends on the clock value. If microsecond and nanosecond digits are non-zero, the result is given to nanosecond precision. Otherwise, a shorter form is used that only has millisecond precision.

See TruncateMillisecond to obtain the shorter form always.

The special case of midnight at the end of a day is "24:00:00.000".

func (Clock) TruncateMillisecond

func (c Clock) TruncateMillisecond() Clock

TruncateMillisecond discards any fractional digits within the millisecond represented by c. For example, for 10:20:30.456111222 this will return 10:20:30.456. This method will force the String method to limit its output to three decimal places.

func (*Clock) UnmarshalBinary

func (c *Clock) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*Clock) UnmarshalText

func (c *Clock) UnmarshalText(data []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (Clock) Value

func (c Clock) Value() (driver.Value, error)

Value converts the value to an int64 or a string. It implements driver.Valuer, Alter the representation by altering the Valuer function. https://golang.org/pkg/database/sql/driver/#Valuer