cockroach: github.com/cockroachdb/cockroach/pkg/util/timeutil/pgdate Index | Files

package pgdate

import "github.com/cockroachdb/cockroach/pkg/util/timeutil/pgdate"

Package pgdate contains parsing functions and types for dates and times in a manner that is compatible with PostgreSQL.

The implementation here is inspired by the following https://github.com/postgres/postgres/blob/REL_10_5/src/backend/utils/adt/datetime.c

The general approach is to take each input string and break it into contiguous runs of alphanumeric characters. Then, we attempt to interpret the input in order to populate a collection of date/time fields. We track which fields have been set in order to be able to apply various parsing heuristics to map the input chunks into date/time fields.

Index

Package Files

field_extract.go field_string.go fields.go math.go parsemode_string.go parsing.go pgdate.go setters.go zone_cache.go

Variables

var (
    TimeEpoch = timeutil.Unix(0, 0)
    // TimeInfinity represents the "highest" possible time.
    // TODO (#41564): this should actually behave as infinity, i.e. any operator
    // leaves this as infinity. This time should always be greater than any other time.
    // We should probably use the next microsecond after this value, i.e. timeutil.Unix(9224318016000, 0).
    // Postgres uses math.MaxInt64 microseconds as the infinity value.
    // See: https://github.com/postgres/postgres/blob/42aa1f0ab321fd43cbfdd875dd9e13940b485900/src/include/datatype/timestamp.h#L107.
    TimeInfinity = timeutil.Unix(9224318016000-1, 999999000)
    // TimeNegativeInfinity represents the "lowest" possible time.
    // TODO (#41564): this should actually behave as -infinity, i.e. any operator
    // leaves this as -infinity. This time should always be less than any other time.
    // We should probably use the next microsecond before this value, i.e. timeutil.Unix(9224318016000-1, 999999000).
    // Postgres uses math.MinInt64 microseconds as the -infinity value.
    // See: https://github.com/postgres/postgres/blob/42aa1f0ab321fd43cbfdd875dd9e13940b485900/src/include/datatype/timestamp.h#L107.
    TimeNegativeInfinity = timeutil.Unix(-210866803200, 0)
)

These are sentinel values for handling special values: https://www.postgresql.org/docs/10/static/datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-TABLE

var (
    // LowDate is the lowest non-infinite Date.
    LowDate = Date{/* contains filtered or unexported fields */}
    // HighDate is the highest non-infinite Date.
    HighDate = Date{/* contains filtered or unexported fields */}
    // PosInfDate is the positive infinity Date.
    PosInfDate = Date{/* contains filtered or unexported fields */}
    // NegInfDate is the negative infinity date.
    NegInfDate = Date{/* contains filtered or unexported fields */}
)

func ParseTime Uses

func ParseTime(
    now time.Time, mode ParseMode, s string,
) (_ time.Time, dependsOnContext bool, _ error)

ParseTime converts a string into a time value on the epoch day.

The dependsOnContext return value indicates if we had to consult the given `now` value (either for the time or the local timezone).

func ParseTimeWithoutTimezone Uses

func ParseTimeWithoutTimezone(
    now time.Time, mode ParseMode, s string,
) (_ time.Time, dependsOnContext bool, _ error)

ParseTimeWithoutTimezone converts a string into a time value on the epoch day, dropping any timezone information. The returned time always has UTC location.

Any specified timezone is inconsequential. Examples:

- "now": parses to the local time of day (in the current timezone)
- "01:09:15.511971" and "01:09:15.511971-05" parse to the same result

The dependsOnContext return value indicates if we had to consult the given `now` value (either for the time or the local timezone).

func ParseTimestamp Uses

func ParseTimestamp(
    now time.Time, mode ParseMode, s string,
) (_ time.Time, dependsOnContext bool, _ error)

ParseTimestamp converts a string into a timestamp.

The dependsOnContext return value indicates if we had to consult the given `now` value (either for the time or the local timezone).

func ParseTimestampWithoutTimezone Uses

func ParseTimestampWithoutTimezone(
    now time.Time, mode ParseMode, s string,
) (_ time.Time, dependsOnContext bool, _ error)

ParseTimestampWithoutTimezone converts a string into a timestamp, stripping away any timezone information. Any specified timezone is inconsequential. The returned time always has UTC location.

For example, all these inputs return 2020-06-26 01:02:03 +0000 UTC:

- '2020-06-26 01:02:03';
- '2020-06-26 01:02:03+04';
- 'now', if the local local time (in the current timezone) is
  2020-06-26 01:02:03. Note that this does not represent the same time
  instant, but the one that "reads" the same in UTC.

The dependsOnContext return value indicates if we had to consult the given `now` value (either for the time or the local timezone).

type Date Uses

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

Date is a postgres-compatible date implementation. It stores the number of days from the postgres epoch (2000-01-01). Its properties are unexported so that it cannot be misused by external packages. This package takes care to prevent silent problems like overflow that can occur when adding days or converting to and from a time.Time.

func MakeCompatibleDateFromDisk Uses

func MakeCompatibleDateFromDisk(unixDays int64) Date

MakeCompatibleDateFromDisk creates a Date from the number of days since the Unix epoch. If it is out of range of LowDate and HighDate, positive or negative infinity dates are returned. This function should be used only by the on-disk decoder to maintain backward compatibility. It retains the origin days argument which is returned by UnixEpochDaysWithOrig.

func MakeDateFromPGEpoch Uses

func MakeDateFromPGEpoch(days int32) (Date, error)

MakeDateFromPGEpoch creates a Date from the number of days since 2000-01-01. MaxInt32 or MinInt32 represent the positive and negative infinity dates.

func MakeDateFromTime Uses

func MakeDateFromTime(t time.Time) (Date, error)

MakeDateFromTime creates a Date from the specified time. The timezone-relative date is used.

func MakeDateFromUnixEpoch Uses

func MakeDateFromUnixEpoch(days int64) (Date, error)

MakeDateFromUnixEpoch creates a Date from the number of days since the Unix epoch.

func ParseDate Uses

func ParseDate(now time.Time, mode ParseMode, s string) (_ Date, dependsOnContext bool, _ error)

ParseDate converts a string into Date.

Any specified timezone is inconsequential. Examples:

- "now": parses to the local date (in the current timezone)
- "2020-06-26 01:09:15.511971": parses to '2020-06-26'
- "2020-06-26 01:09:15.511971-05": parses to '2020-06-26'

The dependsOnContext return value indicates if we had to consult the given `now` value (either for the time or the local timezone).

func (Date) AddDays Uses

func (d Date) AddDays(days int64) (Date, error)

AddDays adds days to d with overflow and bounds checking.

func (Date) Compare Uses

func (d Date) Compare(other Date) int

Compare compares two dates.

func (Date) Format Uses

func (d Date) Format(buf *bytes.Buffer)

Format formats d as a string.

func (Date) IsFinite Uses

func (d Date) IsFinite() bool

IsFinite returns whether d is finite.

func (Date) PGEpochDays Uses

func (d Date) PGEpochDays() int32

PGEpochDays returns the number of days since 2001-01-01. This value can also be MinInt32 or MaxInt32, indicating negative or positive infinity.

func (Date) String Uses

func (d Date) String() string

func (Date) SubDays Uses

func (d Date) SubDays(days int64) (Date, error)

SubDays subtracts days from d with overflow and bounds checking.

func (Date) ToTime Uses

func (d Date) ToTime() (time.Time, error)

ToTime returns d as a time.Time. Non finite dates return an error.

func (Date) UnixEpochDays Uses

func (d Date) UnixEpochDays() int64

UnixEpochDays returns the number of days since the Unix epoch. Infinite dates are converted to MinInt64 or MaxInt64.

func (Date) UnixEpochDaysWithOrig Uses

func (d Date) UnixEpochDaysWithOrig() int64

UnixEpochDaysWithOrig returns the original on-disk representation if present, otherwise UnixEpochDays().

type ParseMode Uses

type ParseMode uint

ParseMode controls the resolution of ambiguous date formats such as `01/02/03`.

const (
    ParseModeYMD ParseMode = iota
    ParseModeDMY
    ParseModeMDY
)

These are the various parsing modes that determine in which order we should look for years, months, and date. ParseModeYMD is the default value.

func (ParseMode) String Uses

func (i ParseMode) String() string

Package pgdate imports 15 packages (graph) and is imported by 16 packages. Updated 2020-07-03. Refresh now. Tools for package owners.