pgdate

package
v0.0.0-...-1b6ad0c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2020 License: Apache-2.0 Imports: 15 Imported by: 3

Documentation

Overview

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

Constants

This section is empty.

Variables

View Source 
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

View Source 
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 */}
)

Functions

func ParseTime 

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 

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 

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 

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

Types

type Date 

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 

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 

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 

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

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

func MakeDateFromUnixEpoch 

func MakeDateFromUnixEpoch(days int64) (Date, error)

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

func ParseDate 

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 

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

AddDays adds days to d with overflow and bounds checking.

func (Date) Compare 

func (d Date) Compare(other Date) int

Compare compares two dates.

func (Date) Format 

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

Format formats d as a string.

func (Date) IsFinite 

func (d Date) IsFinite() bool

IsFinite returns whether d is finite.

func (Date) PGEpochDays 

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 

func (d Date) String() string

func (Date) SubDays 

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

SubDays subtracts days from d with overflow and bounds checking.

func (Date) ToTime 

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

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

func (Date) UnixEpochDays 

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 

func (d Date) UnixEpochDaysWithOrig() int64

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

type ParseMode 

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 

func (i ParseMode) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.