clock

Documentation

Overview

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

Index

• 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) 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) Hours() int
  • func (c Clock) IsInOneDay() bool
  • func (c Clock) IsMidnight() bool
  • func (c Clock) MarshalBinary() ([]byte, error)
  • func (c Clock) MarshalText() ([]byte, error)
  • func (c Clock) Millisec() int
  • func (c Clock) Minutes() int
  • func (c Clock) Mod24() Clock
  • func (c Clock) ModSubtract(c2 Clock) time.Duration
  • func (c *Clock) Scan(value interface{}) (err error)
  • func (c Clock) Seconds() int
  • func (c Clock) String() string
  • func (c *Clock) UnmarshalBinary(data []byte) error
  • func (c *Clock) UnmarshalText(data []byte) (err error)
  • func (c Clock) Value() (driver.Value, error)

Types

type Clock

type Clock int32

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 millisecond, unlike time.Duration (which has nanosecond resolution).

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 int32), 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 (
	// Second is one second; it has a similar meaning to time.Second.
	Second Clock = Clock(time.Second / time.Millisecond)

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

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

	// 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 / time.Millisecond)
)

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.MinInt32)

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

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.

func NewAt

func NewAt(t time.Time) Clock

NewAt returns a new Clock with specified hour, minute, second and millisecond.

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 parameters can be negative.

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

AddDuration is also useful for adding period.Period values.

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

func (c Clock) Hours() int

Hours gets the clock-face number of hours (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() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (Clock) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface.

func (Clock) Millisec

func (c Clock) Millisec() int

Millisec gets the clock-face number of milliseconds (calculated from the modulo time, see Mod24). For example, for 10:20:30.456 this will return 456.

func (Clock) Minutes

func (c Clock) Minutes() int

Minutes 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) 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) Seconds

func (c Clock) Seconds() int

Seconds 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 milliseconds as a 12-character ISO-8601 time string (calculated from the modulo time, see Mod24), specified to the nearest millisecond. Note the special case of midnight at the end of a day is "24:00:00.000".

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. It implements driver.Valuer, https://golang.org/pkg/database/sql/driver/#Valuer