hlc

Documentation

Overview

Package hlc contains a trivial representation of CockroachDB's hybrid logical clock timestamp.

Index

• func Compare(a, b Time) int
• type Range
  • func RangeEmpty() Range
  • func RangeEmptyAt(ts Time) Range
  • func RangeExcluding(startInclusive, endExclusive Time) Range
  • func RangeIncluding(start, end Time) Range
  • func (r Range) Contains(t Time) bool
  • func (r Range) Empty() bool
  • func (r Range) Extend(include Time) Range
  • func (r Range) Max() Time
  • func (r Range) MaxInclusive() Time
  • func (r Range) Min() Time
  • func (r Range) String() string
  • func (r Range) WithMin(min Time) Range
• type Time
  • func From(t time.Time) Time
  • func New(nanos int64, logical int) Time
  • func Parse(timestamp string) (Time, error)
  • func Zero() Time
  • func (t Time) Before() Time
  • func (t Time) Logical() int
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t Time) Nanos() int64
  • func (t Time) Next() Time
  • func (t *Time) Scan(src any) error
  • func (t Time) String() string
  • func (t *Time) UnmarshalJSON(data []byte) error
  • func (t Time) Value() (driver.Value, error)

Functions

func Compare

func Compare(a, b Time) int

Compare two timestamps.

Types

type Range

type Range [2]Time

Range represents a half-open range of HLC values, inclusive of Min and exclusive of Max. For code readability, prefer using RangeEmpty or RangeIncluding to construct ranges instead of directly creating a Range.

func RangeEmpty

func RangeEmpty() Range

RangeEmpty returns an empty range.

func RangeEmptyAt

func RangeEmptyAt(ts Time) Range

RangeEmptyAt returns a Range that starts at the given time, but for which Range.Empty will return true.

func RangeExcluding

func RangeExcluding(startInclusive, endExclusive Time) Range

RangeExcluding returns a Range that includes the start time and excludes the end time.

func RangeIncluding

func RangeIncluding(start, end Time) Range

RangeIncluding returns the smallest range that includes both the start and end times.

func (Range) Contains

func (r Range) Contains(t Time) bool

Contains returns true if the time provided is within this range.

func (Range) Empty

func (r Range) Empty() bool

Empty returns true if the Min time is greater than or equal to the Max value.

func (Range) Extend

func (r Range) Extend(include Time) Range

Extend returns a range that contains the given time by adjusting either the minimum or the maximum time as necessary.

func (Range) Max

func (r Range) Max() Time

Max returns the exclusive, maximum value.

func (Range) MaxInclusive

func (r Range) MaxInclusive() Time

MaxInclusive returns the maximum value that is within the range. That is, it returns one tick before the exclusive end bound.

func (Range) Min

func (r Range) Min() Time

Min returns the inclusive, minimum value.

func (Range) String

func (r Range) String() string

func (Range) WithMin

func (r Range) WithMin(min Time) Range

WithMin returns a new range that includes the minimum. If the new minimum is equal to or beyond the end of the range, this is equivalent to calling RangeEmptyAt.

type Time

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

Time is a representation of the hybrid logical clock timestamp used by CockroachDB. This is an immutable value type, suitable for use as a map key.

func From

func From(t time.Time) Time

From constructs an HLC time from a wall time.

func New

func New(nanos int64, logical int) Time

New constructs a new Time with wall and logical parts.

func Parse

func Parse(timestamp string) (Time, error)

Parse splits a timestmap of the format NNNN.LLL into an int64 for the nanos and an int for the logical component.

func Zero

func Zero() Time

Zero returns a zero-valued Time.

func (Time) Before

func (t Time) Before() Time

Before returns the time minus one logical tick. If the time has a zero logical component, the previous nanosecond will be returned.

func (Time) Logical

func (t Time) Logical() int

Logical returns the logical counter.

func (Time) MarshalJSON

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

MarshalJSON represents the time as a JSON string. This is used when logging timestamps.

func (Time) Nanos

func (t Time) Nanos() int64

Nanos returns the nanosecond wall time.

func (Time) Next

func (t Time) Next() Time

Next returns the time plus one logical tick.

func (*Time) Scan

func (t *Time) Scan(src any) error

Scan implements sql.Scanner and attempts to parse the input as a decimal-formatted string. This method also has a special case to handle a single "0" as input.

func (Time) String

func (t Time) String() string

String returns the Time as a decimal-formatted string.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON restores the timestamp from a string representation.

func (Time) Value

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

Value implements driver.Valuer, which allows the time to be represented as a decimal string.