Documentation
¶
Overview ¶
Package clock specifies a time of day with resolution to the nearest nanosecond.
Index ¶
- Variables
- func ValueAsNumber(c Clock) driver.Value
- func ValueAsString(c Clock) driver.Value
- type 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) ToTime(year int, month time.Month, day int) time.Time
- 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)
Constants ¶
This section is empty.
Variables ¶
var Valuer = ValueAsNumber
Valuer is a pluggable function for writing Clock values to a DB.
Functions ¶
func ValueAsNumber ¶
ValueAsNumber simply returns the numeric 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 Clock.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.
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 ¶
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 ¶
New returns a new Clock with specified hour, minute, second and millisecond. To set sub-millisecond digits, chain this with Clock.AddDuration.
func NewAt ¶
NewAt returns a new Clock with specified hour, minute, seconds (to nanosecond resolution). The date and timezone information is discarded.
func Parse ¶
Parse converts a string representation to a Clock. Acceptable representations are as per ISO-8601.
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 ¶
SinceMidnight returns a new Clock based on a duration since midnight.
func (Clock) Add ¶
Add returns a new Clock offset from this clock specified hour, minute, second and millisecond. The parameters can be negative.
If required, use Clock.Mod24 to correct any overflow or underflow.
func (Clock) AddDuration ¶
AddDuration returns a new Clock offset from this clock by a duration. The parameter can be negative.
If required, use Clock.Mod24 to correct any overflow or underflow.
func (Clock) AddPeriod ¶
AddPeriod returns a new Clock offset from this clock by a time period. The parameter can be negative.
If required, use Clock.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 ¶
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 Clock.IsInOneDay returns true.
func (Clock) DurationSinceMidnight ¶
DurationSinceMidnight convert a Clock to a time.Duration since midnight.
func (Clock) Hh ¶
Hh gets the clock-face number of hours as a two-digit string. It is calculated from the modulo time; see Clock.Mod24. Note the special case of midnight at the end of a day is "24".
func (Clock) Hh12 ¶
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 Clock.Mod24.
func (Clock) HhMm ¶
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 Clock.Mod24. Note the special case of midnight at the end of a day is "24:00".
func (Clock) HhMm12 ¶
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 Clock.Mod24.
func (Clock) HhMmSs ¶
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 Clock.Mod24. Note the special case of midnight at the end of a day is "24:00:00".
func (Clock) HhMmSs12 ¶
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 Clock.Mod24.
func (Clock) Hour ¶
Hour gets the clock-face number of hours (calculated from the modulo time, see Clock.Mod24).
func (Clock) HourMinuteSecond ¶
HourMinuteSecond gets the hours, minutes and seconds values (calculated from the modulo time, see Clock.Mod24).
func (Clock) IsInOneDay ¶
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 ¶
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 ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (Clock) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (Clock) Millisecond ¶
Millisecond gets the clock-face number of milliseconds within the second specified by c (calculated from the modulo time, see Clock.Mod24), in the range [0, 999]. For example, for 10:20:30.456 this will return 456.
func (Clock) Minute ¶
Minute gets the clock-face number of minutes (calculated from the modulo time, see Clock.Mod24). For example, for 22:35 this will return 35.
func (Clock) Mod24 ¶
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).
func (Clock) ModSubtract ¶
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 ¶
Nanosecond gets the clock-face number of nanoseconds within the second specified by c (calculated from the modulo time, see Clock.Mod24), in the range [0, 999999999]. For example, for 10:20:30.456111222 this will return 456111222.
func (Clock) Second ¶
Second gets the clock-face number of seconds (calculated from the modulo time, see Clock.Mod24). For example, for 10:20:30 this will return 30.
func (Clock) 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 Clock.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 Clock.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) ToTime ¶ added in v2.3.0
ToTime converts the clock and a given date to a time.Time. For example, given a date.Date d, use c.ToTime(d.Date()).
func (Clock) TruncateMillisecond ¶
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 also force the Clock.String method to limit its output to three decimal places.
func (*Clock) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
func (*Clock) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
Source Files