Documentation ¶
Index ¶
- Constants
- func Join(src ...string) string
- func NullTimeLess(val ...NullTime) bool
- func NullTimeLessOrEqual(val ...NullTime) bool
- func NullTimeOrder(src []NullTime, fun func(NullTime, NullTime) bool) bool
- func NullTimeSince(val NullTime) time.Duration
- type AppenderTo
- type Decodable
- type Encodable
- type Getter
- type Interval
- func (self Interval) Add(val Interval) Interval
- func (self Interval) AddDays(val int) Interval
- func (self Interval) AddHours(val int) Interval
- func (self Interval) AddMinutes(val int) Interval
- func (self Interval) AddMonths(val int) Interval
- func (self Interval) AddSeconds(val int) Interval
- func (self Interval) AddYears(val int) Interval
- func (self Interval) AppendTo(buf []byte) []byte
- func (self Interval) Date() (years int, months int, days int)
- func (self Interval) Duration() time.Duration
- func (self Interval) Get() any
- func (self Interval) HasDate() bool
- func (self Interval) HasTime() bool
- func (self Interval) IsNull() bool
- func (self Interval) IsZero() bool
- func (self Interval) MarshalJSON() ([]byte, error)
- func (self Interval) MarshalText() ([]byte, error)
- func (self Interval) Neg() Interval
- func (self Interval) OnlyDate() Interval
- func (self Interval) OnlyTime() Interval
- func (self *Interval) Parse(src string) error
- func (self *Interval) Scan(src any) error
- func (self *Interval) Set(src any)
- func (self *Interval) SetDuration(val time.Duration)
- func (self Interval) String() string
- func (self Interval) Sub(val Interval) Interval
- func (self *Interval) UnmarshalJSON(src []byte) error
- func (self *Interval) UnmarshalText(src []byte) error
- func (self Interval) Value() (driver.Value, error)
- func (self Interval) WithDays(val int) Interval
- func (self Interval) WithHours(val int) Interval
- func (self Interval) WithMinutes(val int) Interval
- func (self Interval) WithMonths(val int) Interval
- func (self Interval) WithSeconds(val int) Interval
- func (self Interval) WithYears(val int) Interval
- func (self *Interval) Zero()
- type NullDate
- func (self NullDate) AddDate(years int, months int, days int) NullDate
- func (self NullDate) AppendTo(buf []byte) []byte
- func (self NullDate) Date() (year int, month time.Month, day int)
- func (self NullDate) Get() any
- func (self NullDate) GoString() string
- func (self NullDate) IsNull() bool
- func (self NullDate) IsZero() bool
- func (self NullDate) MarshalJSON() ([]byte, error)
- func (self NullDate) MarshalText() ([]byte, error)
- func (self NullDate) NullTimeIn(loc *time.Location) NullTime
- func (self NullDate) NullTimeUTC() NullTime
- func (self *NullDate) Parse(src string) error
- func (self *NullDate) Scan(src any) error
- func (self *NullDate) Set(src any)
- func (self *NullDate) SetTime(src time.Time)
- func (self NullDate) String() string
- func (self NullDate) TimeIn(loc *time.Location) time.Time
- func (self NullDate) TimeUTC() time.Time
- func (self *NullDate) UnmarshalJSON(src []byte) error
- func (self *NullDate) UnmarshalText(src []byte) error
- func (self NullDate) Value() (driver.Value, error)
- func (self *NullDate) Zero()
- type NullFloat
- func (self NullFloat) AppendTo(buf []byte) []byte
- func (self NullFloat) Float64() float64
- func (self NullFloat) Get() any
- func (self *NullFloat) GetPtr() any
- func (self NullFloat) IsNull() bool
- func (self NullFloat) IsZero() bool
- func (self NullFloat) MarshalJSON() ([]byte, error)
- func (self NullFloat) MarshalText() ([]byte, error)
- func (self *NullFloat) Parse(src string) error
- func (self *NullFloat) Scan(src any) error
- func (self *NullFloat) Set(src any)
- func (self NullFloat) String() string
- func (self *NullFloat) UnmarshalJSON(src []byte) error
- func (self *NullFloat) UnmarshalText(src []byte) error
- func (self NullFloat) Value() (driver.Value, error)
- func (self *NullFloat) Zero()
- type NullInt
- func (self NullInt) AppendTo(buf []byte) []byte
- func (self NullInt) Get() any
- func (self *NullInt) GetPtr() any
- func (self NullInt) Int64() int64
- func (self NullInt) IsNull() bool
- func (self NullInt) IsZero() bool
- func (self NullInt) MarshalJSON() ([]byte, error)
- func (self NullInt) MarshalText() ([]byte, error)
- func (self *NullInt) Parse(src string) error
- func (self *NullInt) Scan(src any) error
- func (self *NullInt) Set(src any)
- func (self NullInt) String() string
- func (self *NullInt) UnmarshalJSON(src []byte) error
- func (self *NullInt) UnmarshalText(src []byte) error
- func (self NullInt) Value() (driver.Value, error)
- func (self *NullInt) Zero()
- type NullInterval
- func DateNullInterval(years int, months int, days int) NullInterval
- func DurationNullInterval(src time.Duration) (val NullInterval)
- func NullIntervalFrom(years int, months int, days, hours, mins, secs int) NullInterval
- func ParseNullInterval(src string) (val NullInterval)
- func TimeNullInterval(hours, mins, secs int) NullInterval
- func (self NullInterval) Add(val NullInterval) NullInterval
- func (self NullInterval) AddDays(val int) NullInterval
- func (self NullInterval) AddHours(val int) NullInterval
- func (self NullInterval) AddMinutes(val int) NullInterval
- func (self NullInterval) AddMonths(val int) NullInterval
- func (self NullInterval) AddSeconds(val int) NullInterval
- func (self NullInterval) AddYears(val int) NullInterval
- func (self NullInterval) AppendTo(buf []byte) []byte
- func (self NullInterval) Date() (years int, months int, days int)
- func (self NullInterval) Duration() time.Duration
- func (self NullInterval) Get() any
- func (self NullInterval) HasDate() bool
- func (self NullInterval) HasTime() bool
- func (self NullInterval) IsNull() bool
- func (self NullInterval) IsZero() bool
- func (self NullInterval) MarshalJSON() ([]byte, error)
- func (self NullInterval) MarshalText() ([]byte, error)
- func (self NullInterval) Neg() NullInterval
- func (self NullInterval) OnlyDate() NullInterval
- func (self NullInterval) OnlyTime() NullInterval
- func (self *NullInterval) Parse(src string) error
- func (self *NullInterval) Scan(src any) error
- func (self *NullInterval) Set(src any)
- func (self *NullInterval) SetDuration(val time.Duration)
- func (self NullInterval) String() string
- func (self NullInterval) Sub(val NullInterval) NullInterval
- func (self *NullInterval) UnmarshalJSON(src []byte) error
- func (self *NullInterval) UnmarshalText(src []byte) error
- func (self NullInterval) Value() (driver.Value, error)
- func (self NullInterval) WithDays(val int) NullInterval
- func (self NullInterval) WithHours(val int) NullInterval
- func (self NullInterval) WithMinutes(val int) NullInterval
- func (self NullInterval) WithMonths(val int) NullInterval
- func (self NullInterval) WithSeconds(val int) NullInterval
- func (self NullInterval) WithYears(val int) NullInterval
- func (self *NullInterval) Zero()
- type NullString
- func (self NullString) AppendTo(buf []byte) []byte
- func (self NullString) Get() any
- func (self *NullString) GetPtr() any
- func (self NullString) IsNull() bool
- func (self NullString) IsZero() bool
- func (self NullString) Len() int
- func (self NullString) MarshalJSON() ([]byte, error)
- func (self NullString) MarshalText() ([]byte, error)
- func (self *NullString) Parse(src string) error
- func (self *NullString) Scan(src any) error
- func (self *NullString) Set(src any)
- func (self NullString) String() string
- func (self *NullString) UnmarshalJSON(src []byte) error
- func (self *NullString) UnmarshalText(src []byte) error
- func (self NullString) Value() (driver.Value, error)
- func (self *NullString) Zero()
- type NullTime
- func ClockNullTime(hour, min, sec int) NullTime
- func NullDateIn(year int, month time.Month, day int, loc *time.Location) NullTime
- func NullDateUTC(year int, month time.Month, day int) NullTime
- func NullTimeIn(year int, month time.Month, day, hour, min, sec, nsec int, loc *time.Location) NullTime
- func NullTimeNow() NullTime
- func NullTimeUTC(year int, month time.Month, day, hour, min, sec, nsec int) NullTime
- func ParseNullTime(src string) (val NullTime)
- func (self NullTime) Add(val time.Duration) NullTime
- func (self NullTime) AddDate(y, m, d int) NullTime
- func (self NullTime) AddInterval(val Interval) NullTime
- func (self NullTime) AddNullInterval(val NullInterval) NullTime
- func (self NullTime) After(val NullTime) bool
- func (self NullTime) AppendFormat(a []byte, b string) []byte
- func (self NullTime) AppendTo(buf []byte) []byte
- func (self NullTime) Before(val NullTime) bool
- func (self NullTime) Clock() (int, int, int)
- func (self NullTime) Date() (int, time.Month, int)
- func (self NullTime) Day() int
- func (self NullTime) Equal(val NullTime) bool
- func (self NullTime) Format(layout string) string
- func (self NullTime) Get() any
- func (self *NullTime) GetPtr() any
- func (self NullTime) GoString() string
- func (self NullTime) Hour() int
- func (self NullTime) ISOWeek() (int, int)
- func (self NullTime) In(loc *time.Location) NullTime
- func (self NullTime) IsDST() bool
- func (self NullTime) IsNull() bool
- func (self NullTime) IsZero() bool
- func (self NullTime) Less(val NullTime) bool
- func (self NullTime) LessOrEqual(val NullTime) bool
- func (self NullTime) Local() NullTime
- func (self NullTime) Location() *time.Location
- func (self NullTime) MarshalJSON() ([]byte, error)
- func (self NullTime) MarshalText() ([]byte, error)
- func (self NullTime) MaybeTime() *time.Time
- func (self NullTime) Minute() int
- func (self NullTime) Month() time.Month
- func (self NullTime) Nanosecond() int
- func (self NullTime) NullDate() NullDate
- func (self *NullTime) Parse(src string) error
- func (self NullTime) Round(val time.Duration) NullTime
- func (self *NullTime) Scan(src any) error
- func (self NullTime) Second() int
- func (self *NullTime) Set(src any)
- func (self NullTime) String() string
- func (self NullTime) Sub(val NullTime) time.Duration
- func (self NullTime) SubInterval(val Interval) NullTime
- func (self NullTime) SubNullInterval(val NullInterval) NullTime
- func (self NullTime) Time() time.Time
- func (self *NullTime) TimePtr() *time.Time
- func (self NullTime) Truncate(val time.Duration) NullTime
- func (self NullTime) UTC() NullTime
- func (self NullTime) Unix() int64
- func (self NullTime) UnixMicro() int64
- func (self NullTime) UnixMilli() int64
- func (self NullTime) UnixNano() int64
- func (self *NullTime) UnmarshalJSON(src []byte) error
- func (self *NullTime) UnmarshalText(src []byte) error
- func (self NullTime) Value() (driver.Value, error)
- func (self NullTime) Weekday() time.Weekday
- func (self NullTime) Year() int
- func (self NullTime) YearDay() int
- func (self *NullTime) Zero()
- func (self NullTime) Zone() (string, int)
- type NullUint
- func (self NullUint) AppendTo(buf []byte) []byte
- func (self NullUint) Get() any
- func (self *NullUint) GetPtr() any
- func (self NullUint) IsNull() bool
- func (self NullUint) IsZero() bool
- func (self NullUint) MarshalJSON() ([]byte, error)
- func (self NullUint) MarshalText() ([]byte, error)
- func (self *NullUint) Parse(src string) error
- func (self *NullUint) Scan(src any) error
- func (self *NullUint) Set(src any)
- func (self NullUint) String() string
- func (self NullUint) Uint64() uint64
- func (self *NullUint) UnmarshalJSON(src []byte) error
- func (self *NullUint) UnmarshalText(src []byte) error
- func (self NullUint) Value() (driver.Value, error)
- func (self *NullUint) Zero()
- type NullUrl
- func (self NullUrl) AddPath(src ...string) NullUrl
- func (self NullUrl) AppendTo(buf []byte) []byte
- func (self NullUrl) EscapedFragment() string
- func (self NullUrl) EscapedPath() string
- func (self NullUrl) Get() any
- func (self *NullUrl) GetPtr() any
- func (self NullUrl) GoString() string
- func (self NullUrl) Hostname() string
- func (self NullUrl) IsAbs() bool
- func (self NullUrl) IsNull() bool
- func (self NullUrl) IsZero() bool
- func (self NullUrl) MarshalJSON() ([]byte, error)
- func (self NullUrl) MarshalText() ([]byte, error)
- func (self NullUrl) Maybe() *url.URL
- func (self *NullUrl) Parse(src string) error
- func (self NullUrl) ParseIn(ref string) (NullUrl, error)
- func (self NullUrl) Port() string
- func (self NullUrl) Query() url.Values
- func (self NullUrl) Redacted() string
- func (self NullUrl) RequestURI() string
- func (self NullUrl) ResolveReference(ref NullUrl) NullUrl
- func (self *NullUrl) Scan(src any) error
- func (self *NullUrl) Set(src any)
- func (self NullUrl) String() string
- func (self *NullUrl) UnmarshalJSON(src []byte) error
- func (self *NullUrl) UnmarshalText(src []byte) error
- func (self NullUrl) Url() *url.URL
- func (self *NullUrl) UrlPtr() *url.URL
- func (self NullUrl) Value() (driver.Value, error)
- func (self NullUrl) WithFragment(val string) NullUrl
- func (self NullUrl) WithPath(src ...string) NullUrl
- func (self NullUrl) WithQuery(val url.Values) NullUrl
- func (self NullUrl) WithRawQuery(val string) NullUrl
- func (self *NullUrl) Zero()
- type NullUuid
- func (self NullUuid) AppendTo(buf []byte) []byte
- func (self NullUuid) Get() any
- func (self NullUuid) GoString() string
- func (self NullUuid) IsNull() bool
- func (self NullUuid) IsZero() bool
- func (self NullUuid) Less(other NullUuid) bool
- func (self NullUuid) MarshalJSON() ([]byte, error)
- func (self NullUuid) MarshalText() ([]byte, error)
- func (self *NullUuid) Parse(src string) error
- func (self *NullUuid) Scan(src any) error
- func (self *NullUuid) Set(src any)
- func (self NullUuid) String() string
- func (self *NullUuid) UnmarshalJSON(src []byte) error
- func (self *NullUuid) UnmarshalText(src []byte) error
- func (self NullUuid) Value() (driver.Value, error)
- func (self *NullUuid) Zero()
- type Nullable
- type Parser
- type PtrGetter
- type Raw
- func (self Raw) AppendTo(buf []byte) []byte
- func (self Raw) Get() any
- func (self Raw) GoString() string
- func (self Raw) Grow(size int) Raw
- func (self Raw) IsNull() bool
- func (self Raw) IsZero() bool
- func (self Raw) Len() int
- func (self Raw) MarshalJSON() ([]byte, error)
- func (self Raw) MarshalText() ([]byte, error)
- func (self *Raw) Parse(src string) error
- func (self *Raw) Scan(src any) error
- func (self *Raw) Set(src any)
- func (self Raw) String() string
- func (self *Raw) UnmarshalJSON(src []byte) error
- func (self *Raw) UnmarshalText(src []byte) error
- func (self Raw) Value() (driver.Value, error)
- func (self *Raw) Zero()
- type Scanner
- type Setter
- type Ter
- func (self Ter) AppendTo(buf []byte) []byte
- func (self Ter) BoolPtr() *bool
- func (self Ter) EqBool(val bool) bool
- func (self Ter) Get() any
- func (self Ter) GoString() string
- func (self Ter) IsFalse() bool
- func (self Ter) IsNull() bool
- func (self Ter) IsTrue() bool
- func (self Ter) IsZero() bool
- func (self Ter) LaxBool() bool
- func (self Ter) MarshalJSON() ([]byte, error)
- func (self Ter) MarshalText() ([]byte, error)
- func (self *Ter) Parse(src string) (err error)
- func (self *Ter) Scan(src any) error
- func (self *Ter) Set(src any)
- func (self *Ter) SetBool(val bool)
- func (self *Ter) SetBoolPtr(val *bool)
- func (self Ter) String() string
- func (self Ter) TryBool() bool
- func (self *Ter) UnmarshalJSON(src []byte) error
- func (self *Ter) UnmarshalText(src []byte) error
- func (self Ter) Value() (driver.Value, error)
- func (self *Ter) Zero()
- type Uuid
- func (self Uuid) AppendTo(buf []byte) []byte
- func (self Uuid) Get() any
- func (self Uuid) GoString() string
- func (self Uuid) IsNull() bool
- func (self Uuid) IsZero() bool
- func (self Uuid) Less(other Uuid) bool
- func (self Uuid) MarshalJSON() ([]byte, error)
- func (self Uuid) MarshalText() ([]byte, error)
- func (self *Uuid) Parse(src string) (err error)
- func (self *Uuid) Scan(src any) error
- func (self *Uuid) Set(src any)
- func (self Uuid) String() string
- func (self *Uuid) UnmarshalJSON(src []byte) error
- func (self *Uuid) UnmarshalText(src []byte) error
- func (self Uuid) Value() (driver.Value, error)
- func (self *Uuid) Zero()
- type Zeroable
- type Zeroer
Constants ¶
const ( UuidLen = 16 UuidStrLen = UuidLen * 2 )
Variables ¶
This section is empty.
Functions ¶
func Join ¶ added in v0.1.14
Like `path.Join` but with safeguards. Used internally by `gr.NullUrl.WithPath`, exported because it may be useful separately. Differences from `path.Join`:
More efficient if there's only 1 segment.
Panics if any segment is "".
Panics if any segment begins with ".." or "/..".
Combining segments of a URL path is usually done when building a URL for a request. Accidentally calling the wrong endpoint can have consequences much more annoying than a panic during request building.
func NullTimeLess ¶ added in v0.1.19
True if the timestamps are ordered like this: A < B < C < .... Also see `gt.NullTimeLessOrEqual` which uses `<=`.
func NullTimeLessOrEqual ¶ added in v0.1.19
True if the timestamps are ordered like this: A <= B <= C <= .... Also see `gt.NullTimeLess` which uses `<`.
func NullTimeOrder ¶ added in v0.1.19
True if the timestamps are ordered in such a way that the given function returns true for each subsequent pair. If the function is nil, returns false. Otherwise, if length is 0 or 1, returns true.
func NullTimeSince ¶
`gt.NullTime` version of `time.Since`.
Types ¶
type AppenderTo ¶ added in v0.1.21
Implemented by all types in this package, as well as some stdlib types. Appends the default text representation of the receiver to the provided buffer.
type Decodable ¶
type Decodable interface { Setter Zeroer Parser AppenderTo encoding.TextUnmarshaler json.Unmarshaler Scanner }
Implemented by all types in this package. Various methods for mutating the underlying value by decoding or zeroing. All methods must be implemented on pointer types, rather than value types.
type Encodable ¶
type Encodable interface { Getter Zeroable Nullable fmt.Stringer encoding.TextMarshaler json.Marshaler driver.Valuer }
Implemented by all types in this package. Various methods for converting the value to another representation. All methods must be implemented on value types, rather than pointer types.
type Getter ¶
type Getter interface{ Get() any }
Implemented by all types in this package. Returns the underlying value as a "primitive" / "well-known" type, such as `int64`, `string`, `time.Time` depending on the type. All types in this package use `.Get` to implement `sql.Valuer`.
type Interval ¶
type Interval struct { Years int `json:"years" db:"years"` Months int `json:"months" db:"months"` Days int `json:"days" db:"days"` Hours int `json:"hours" db:"hours"` Minutes int `json:"minutes" db:"minutes"` Seconds int `json:"seconds" db:"seconds"` }
Represents an ISO 8601 time interval that has only duration (no timestamps, no range). Supports all six components of ISO 8601 interval: years, months, days, hours, minutes, seconds.
Features:
- Reversible encoding/decoding in text.
- Reversible encoding/decoding in JSON.
- Reversible encoding/decoding in SQL.
Text encoding and decoding uses the standard ISO 8601 format:
P0Y0M0DT0H0M0S
When interacting with a database, to make intervals parsable, configure your DB to always output them in the standard ISO 8601 format.
Limitations:
- Supports only the standard machine-readable format.
- Doesn't support decimal fractions.
For a nullable variant, see `gt.NullInterval`.
func DateInterval ¶
Simplified interval constructor without a time constituent.
func DurationInterval ¶
Uses `.SetDuration` and returns the resulting interval.
func IntervalFrom ¶
Simplified interval constructor.
func ParseInterval ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func TimeInterval ¶
Simplified interval constructor without a date constituent.
func (Interval) Add ¶ added in v0.1.6
Adds every field of one interval to every field of another interval, returning the sum. Does NOT convert different time units, such as seconds to minutes or vice versa.
func (Interval) AddMinutes ¶ added in v0.1.6
Returns a version of this interval with `.Minutes += val`.
func (Interval) AddMonths ¶ added in v0.1.6
Returns a version of this interval with `.Months += val`.
func (Interval) AddSeconds ¶ added in v0.1.6
Returns a version of this interval with `.Seconds += val`.
func (Interval) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (Interval) Date ¶ added in v0.1.10
Returns the date portion of the interval, disregarding the time portion. The result can be passed to `time.Time.AddDate` and `gt.NullTime.AddDate`.
func (Interval) Duration ¶
Returns the duration of ONLY the time portion of this interval. Panics if the interval has a date constituent. To make it clear that you're explicitly disregarding the date part, call `.OnlyTime` first. Warning: there are no overflow checks. Usage example:
someInterval.OnlyTime().Duration()
func (Interval) MarshalJSON ¶
Implement `json.Marshaler`, using the same representation as `.String`.
func (Interval) MarshalText ¶
Implement `encoding.TextMarhaler`, using the same representation as `.String`.
func (Interval) Neg ¶ added in v0.1.6
Returns a version of this interval with every field inverted: positive fields become negative, and negative fields become positive.
func (Interval) OnlyDate ¶ added in v0.1.10
Returns only the date portion of this interval, with other fields set to 0.
func (Interval) OnlyTime ¶ added in v0.1.10
Returns only the time portion of this interval, with other fields set to 0.
func (*Interval) Parse ¶
Implement `gt.Parser`, parsing a valid machine-readable ISO 8601 representation.
func (*Interval) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.Interval` and modifying the receiver. Acceptable inputs:
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `time.Duration` -> use `.SetDuration`
- `gt.Interval` -> assign
- `gt.NullInterval` -> assign
- `gt.Getter` -> scan underlying value
func (*Interval) SetDuration ¶
Sets the interval to an approximate value of the given duration, expressed in hours, minutes, seconds, truncating any fractions that don't fit.
func (Interval) String ¶
Implement `fmt.Stringer`, returning a text representation in the standard machine-readable ISO 8601 format.
func (Interval) Sub ¶ added in v0.1.6
Subtracts every field of one interval from every corresponding field of another interval, returning the difference. Does NOT convert different time units, such as seconds to minutes or vice versa.
func (*Interval) UnmarshalJSON ¶
Implement `json.Unmarshaler`, using the same algorithm as `.Parse`.
func (*Interval) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
func (Interval) WithMinutes ¶ added in v0.1.6
Returns a version of this interval with `.Minutes = val`.
func (Interval) WithMonths ¶ added in v0.1.6
Returns a version of this interval with `.Months = val`.
func (Interval) WithSeconds ¶ added in v0.1.6
Returns a version of this interval with `.Seconds = val`.
type NullDate ¶
type NullDate struct { Year int `json:"year" db:"year"` Month time.Month `json:"month" db:"month"` Day int `json:"day" db:"day"` }
Civil date without time. Corresponds to SQL type `date` and HTML input with `type="date"`. Zero value is considered empty in text, and null in JSON and SQL. Features:
- Reversible encoding/decoding in text. Zero value is "".
- Reversible encoding/decoding in JSON. Zero value is `null`.
- Reversible encoding/decoding in SQL. Zero value is `null`.
- Text encoding uses the ISO 8601 extended calendar date format: "0001-02-03".
- Text decoding supports date-only strings and full RFC3339 timestamps.
- Convertible to and from `gt.NullTime`.
Caution: `gt.NullDate{}` or `gt.NullDate{0, 0, 0}` is considered empty/null, but when converted to `time.Time` or `gt.NullTime`, it's NOT equivalent to the zero time. The equivalent of zero time is `gt.NullDate{1, 1, 1}`.
func NullDateFrom ¶
Shortcut for making a date from a time:
inst := time.Now() date := gt.NullDateFrom(inst.Date())
Reversible:
date == gt.NullDateFrom(date.Date())
Note that `gt.NullDateFrom(0, 0, 0)` returns a zero value which is considered empty/null, but NOT equivalent to `time.Time{}`. The equivalent of zero time is `gt.NullDateFrom(1, 1, 1)`.
func NullDateNow ¶ added in v0.1.11
func NullDateNow() NullDate
Shortcut for `gt.NullTimeNow().NullDate()`.
func ParseNullDate ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func (NullDate) AddDate ¶ added in v0.1.10
Similar to `time.Time.AddDate`. Returns a modified version of the current value, with the year, month, day deltas added to the corresponding fields. The deltas may be negative. Note that `time.Time` and all time-related types in this package have a convenient `.Date` method that returns this tuple. The calculations are performed for the UTC timezone.
As a special case, because the zero value is considered null, calling this on a zero date ALWAYS returns the same zero date. This matches general SQL semantics of operations involving nulls. Note that the equivalent of zero TIME is not `gt.NullDateFrom(0, 0, 0)`, but rather `gt.NullDateFrom(1, 1, 1)`.
func (NullDate) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullDate) Date ¶
Same as `time.Time.Date`. Returns a tuple of the underlying year, month, day.
func (NullDate) Get ¶
Implement `gt.Getter`. If zero, returns `nil`, otherwise uses `.TimeUTC` to return a timestamp suitable for SQL encoding.
func (NullDate) GoString ¶
Implement `fmt.GoStringer`, returning valid Go code that constructs this value.
func (NullDate) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise returns bytes representing a JSON string with the same text as in `.String`.
func (NullDate) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (NullDate) NullTimeIn ¶
Converts to `gt.NullTime` with `T00:00:00` in the provided timezone.
func (NullDate) NullTimeUTC ¶
Converts to `gt.NullTime` with `T00:00:00` in UTC.
func (*NullDate) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise requires an ISO 8601 date representation, one of:
- Extended calendar date: "2006-01-02"
- RFC3339 (default Go timestamp format): "2006-01-02T15:04:05Z07:00"
func (*NullDate) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullDate` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `time.Time` -> use `.SetTime`
- `*time.Time` -> use `.Zero` or `.SetTime`
- `gt.NullTime` -> use `.SetTime`
- `gt.NullDate` -> assign
- `gt.Getter` -> scan underlying value
func (*NullDate) SetTime ¶
If the input is zero, zeroes the receiver. Otherwise uses `time.Time.Date` and assigns the resulting year, month, day to the receiver, ignoring smaller constituents such as hour.
func (NullDate) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise returns a text representation in the standard machine-readable ISO 8601 format.
func (*NullDate) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise parses a JSON string, using the same algorithm as `.Parse`.
func (*NullDate) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type NullFloat ¶
type NullFloat float64
Variant of `float64` where zero value is considered empty in text, and null in JSON and SQL.
Unlike `float64`, encoding/decoding is not always reversible:
JSON 0 → Go 0 → JSON null SQL 0 → Go 0 → SQL null
Also unlike `float64`, this type doesn't use the scientific notation when encoding to a string.
Differences from `"database/sql".NullFloat64`:
- Much easier to use.
- Supports text.
- Supports JSON.
- Fewer states: zero and null are the same.
Caution: like any floating point number, this should not be used for financial columns. Store money as integers or use a specialized decimal type.
func ParseNullFloat ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func (NullFloat) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullFloat) Float64 ¶ added in v0.1.17
Free cast to the underlying `float64`. Sometimes handy when this type is embedded in a struct.
func (NullFloat) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise uses the default `json.Marshal` behavior for `float64`.
func (NullFloat) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (*NullFloat) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise parses the input using `strconv.ParseFloat`.
func (*NullFloat) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullFloat` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `intN` -> convert and assign
- `*intN` -> use `.Zero` or convert and assign
- `floatN` -> convert and assign
- `*floatN` -> use `.Zero` or convert and assign
- `NullFloat` -> assign
- `gt.Getter` -> scan underlying value
func (NullFloat) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise formats using `strconv.FormatFloat`.
func (*NullFloat) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise uses the default `json.Unmarshal` behavior for `*float64`.
func (*NullFloat) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type NullInt ¶
type NullInt int64
Variant of `int64` where zero value is considered empty in text, and null in JSON and SQL. Use this for fields where 0 is not allowed, such as primary and foreign keys, or unique bigserials.
Unlike `int64`, encoding/decoding is not always reversible:
JSON 0 → Go 0 → JSON null SQL 0 → Go 0 → SQL null
Differences from `"database/sql".NullInt64`:
- Much easier to use.
- Supports text.
- Supports JSON.
- Fewer states: null and zero are one.
In your data model, numeric fields should be either:
- Non-nullable; zero value = 0; use `int64`.
- Nullable; zero value = `null`; 0 is not allowed; use `gt.NullInt`.
Avoid `*intN` or `sql.NullIntN`.
func ParseNullInt ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func (NullInt) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullInt) Int64 ¶ added in v0.1.16
Free cast to the underlying `int64`. Sometimes handy when this type is embedded in a struct.
func (NullInt) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise uses the default `json.Marshal` behavior for `int64`.
func (NullInt) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (*NullInt) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise parses the input using `strconv.ParseInt`.
func (*NullInt) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullInt` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `intN` -> convert and assign
- `*intN` -> use `.Zero` or convert and assign
- `NullInt` -> assign
- `gt.Getter` -> scan underlying value
TODO also support uints.
func (NullInt) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise formats using `strconv.FormatInt`.
func (*NullInt) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise uses the default `json.Unmarshal` behavior for `*int64`.
func (*NullInt) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type NullInterval ¶
type NullInterval Interval
Variant of `gt.Interval` where zero value is considered empty in text, and null in JSON and SQL.
func DateNullInterval ¶
func DateNullInterval(years int, months int, days int) NullInterval
Simplified interval constructor without a time constituent.
func DurationNullInterval ¶
func DurationNullInterval(src time.Duration) (val NullInterval)
Uses `.SetDuration` and returns the resulting interval.
func NullIntervalFrom ¶
func NullIntervalFrom(years int, months int, days, hours, mins, secs int) NullInterval
Simplified interval constructor.
func ParseNullInterval ¶
func ParseNullInterval(src string) (val NullInterval)
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func TimeNullInterval ¶
func TimeNullInterval(hours, mins, secs int) NullInterval
Simplified interval constructor without a date constituent.
func (NullInterval) Add ¶ added in v0.1.6
func (self NullInterval) Add(val NullInterval) NullInterval
Adds every field of one interval to every field of another interval, returning the sum. Does NOT convert different time units, such as seconds to minutes or vice versa.
func (NullInterval) AddDays ¶ added in v0.1.6
func (self NullInterval) AddDays(val int) NullInterval
Returns a version of this interval with `.Days += val`.
func (NullInterval) AddHours ¶ added in v0.1.6
func (self NullInterval) AddHours(val int) NullInterval
Returns a version of this interval with `.Hours += val`.
func (NullInterval) AddMinutes ¶ added in v0.1.6
func (self NullInterval) AddMinutes(val int) NullInterval
Returns a version of this interval with `.Minutes += val`.
func (NullInterval) AddMonths ¶ added in v0.1.6
func (self NullInterval) AddMonths(val int) NullInterval
Returns a version of this interval with `.Months += val`.
func (NullInterval) AddSeconds ¶ added in v0.1.6
func (self NullInterval) AddSeconds(val int) NullInterval
Returns a version of this interval with `.Seconds += val`.
func (NullInterval) AddYears ¶ added in v0.1.6
func (self NullInterval) AddYears(val int) NullInterval
Returns a version of this interval with `.Years += val`.
func (NullInterval) AppendTo ¶ added in v0.1.21
func (self NullInterval) AppendTo(buf []byte) []byte
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullInterval) Date ¶ added in v0.1.10
func (self NullInterval) Date() (years int, months int, days int)
Same as `gt.Interval.Date`.
func (NullInterval) Duration ¶ added in v0.1.10
func (self NullInterval) Duration() time.Duration
Same as `gt.Interval.Duration`.
func (NullInterval) Get ¶
func (self NullInterval) Get() any
Implement `gt.Getter`. If zero, returns `nil`, otherwise uses `.String` to return a string representation.
func (NullInterval) HasDate ¶
func (self NullInterval) HasDate() bool
Same as `gt.Interval.HasDate`.
func (NullInterval) HasTime ¶
func (self NullInterval) HasTime() bool
Same as `gt.Interval.HasTime`.
func (NullInterval) IsNull ¶
func (self NullInterval) IsNull() bool
Implement `gt.Nullable`. True if zero.
func (NullInterval) IsZero ¶
func (self NullInterval) IsZero() bool
Implement `gt.Zeroable`. Equivalent to `reflect.ValueOf(self).IsZero()`.
func (NullInterval) MarshalJSON ¶
func (self NullInterval) MarshalJSON() ([]byte, error)
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise returns bytes representing a JSON string with the same text as in `.String`.
func (NullInterval) MarshalText ¶
func (self NullInterval) MarshalText() ([]byte, error)
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (NullInterval) Neg ¶ added in v0.1.6
func (self NullInterval) Neg() NullInterval
Returns a version of this interval with every field inverted: positive fields become negative, and negative fields become positive.
func (NullInterval) OnlyDate ¶ added in v0.1.10
func (self NullInterval) OnlyDate() NullInterval
Same as `gt.Interval.OnlyDate`.
func (NullInterval) OnlyTime ¶ added in v0.1.10
func (self NullInterval) OnlyTime() NullInterval
Same as `gt.Interval.OnlyTime`.
func (*NullInterval) Parse ¶
func (self *NullInterval) Parse(src string) error
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise requires a valid machine-readable ISO 8601 representation.
func (*NullInterval) Scan ¶
func (self *NullInterval) Scan(src any) error
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullInterval` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `time.Duration` -> use `.SetDuration`
- `*time.Duration` -> use `.Zero` or `.SetDuration`
- `gt.Interval` -> assign
- `*gt.Interval` -> use `.Zero` or assign
- `gt.NullInterval` -> assign
- `gt.Getter` -> scan underlying value
func (*NullInterval) Set ¶
func (self *NullInterval) Set(src any)
Implement `gt.Setter`, using `.Scan`. Panics on error.
func (*NullInterval) SetDuration ¶
func (self *NullInterval) SetDuration(val time.Duration)
Same as `(*gt.Interval).SetDuration`.
func (NullInterval) String ¶
func (self NullInterval) String() string
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise returns a text representation in the standard machine-readable ISO 8601 format.
func (NullInterval) Sub ¶ added in v0.1.6
func (self NullInterval) Sub(val NullInterval) NullInterval
Subtracts every field of one interval from every corresponding field of another interval, returning the difference. Does NOT convert different time units, such as seconds to minutes or vice versa.
func (*NullInterval) UnmarshalJSON ¶
func (self *NullInterval) UnmarshalJSON(src []byte) error
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise parses a JSON string, using the same algorithm as `.Parse`.
func (*NullInterval) UnmarshalText ¶
func (self *NullInterval) UnmarshalText(src []byte) error
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
func (NullInterval) Value ¶
func (self NullInterval) Value() (driver.Value, error)
Implement `driver.Valuer`, using `.Get`.
func (NullInterval) WithDays ¶ added in v0.1.6
func (self NullInterval) WithDays(val int) NullInterval
Returns a version of this interval with `.Days = val`.
func (NullInterval) WithHours ¶ added in v0.1.6
func (self NullInterval) WithHours(val int) NullInterval
Returns a version of this interval with `.Hours = val`.
func (NullInterval) WithMinutes ¶ added in v0.1.6
func (self NullInterval) WithMinutes(val int) NullInterval
Returns a version of this interval with `.Minutes = val`.
func (NullInterval) WithMonths ¶ added in v0.1.6
func (self NullInterval) WithMonths(val int) NullInterval
Returns a version of this interval with `.Months = val`.
func (NullInterval) WithSeconds ¶ added in v0.1.6
func (self NullInterval) WithSeconds(val int) NullInterval
Returns a version of this interval with `.Seconds = val`.
func (NullInterval) WithYears ¶ added in v0.1.6
func (self NullInterval) WithYears(val int) NullInterval
Returns a version of this interval with `.Years = val`.
func (*NullInterval) Zero ¶
func (self *NullInterval) Zero()
Implement `gt.Zeroer`, zeroing the receiver.
type NullString ¶
type NullString string
Variant of `string` where zero value is considered empty in text, and null in JSON and SQL. Use this for fields where an empty string is not allowed, such as enums or text foreign keys.
Unlike `string`, encoding/decoding is not always reversible:
JSON "" → Go "" → JSON null SQL '' → Go "" → SQL null
Differences from `"database/sql".NullString`:
- Much easier to use.
- Supports text.
- Supports JSON.
- Fewer states: null and empty string are one.
In your data model, text fields should be either:
- Non-nullable, zero value = empty string -> use `string`.
- Nullable, zero value = `null`, empty string is not allowed -> use `gt.NullString`.
Avoid `*string` or `sql.NullString`.
func (NullString) AppendTo ¶ added in v0.1.21
func (self NullString) AppendTo(buf []byte) []byte
Implement `gt.AppenderTo`, appending the string as-is.
func (NullString) Get ¶
func (self NullString) Get() any
Implement `gt.Getter`. If zero, returns `nil`, otherwise returns `string`.
func (*NullString) GetPtr ¶
func (self *NullString) GetPtr() any
Implement `gt.PtrGetter`, returning `*string`.
func (NullString) IsNull ¶
func (self NullString) IsNull() bool
Implement `gt.Nullable`. True if zero.
func (NullString) IsZero ¶
func (self NullString) IsZero() bool
Implement `gt.Zeroable`. Equivalent to `reflect.ValueOf(self).IsZero()`.
func (NullString) Len ¶ added in v0.1.12
func (self NullString) Len() int
Same as `len(self)`. Sometimes handy when embedding `gt.NullString` in single-field structs.
func (NullString) MarshalJSON ¶
func (self NullString) MarshalJSON() ([]byte, error)
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise uses the default `json.Marshal` behavior for `string`.
func (NullString) MarshalText ¶
func (self NullString) MarshalText() ([]byte, error)
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the string as-is.
func (*NullString) Parse ¶
func (self *NullString) Parse(src string) error
Implement `gt.Parser`, assigning the string as-is.
func (*NullString) Scan ¶
func (self *NullString) Scan(src any) error
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullString` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `NullString` -> assign
- `gt.Getter` -> scan underlying value
func (*NullString) Set ¶
func (self *NullString) Set(src any)
Implement `gt.Setter`, using `.Scan`. Panics on error.
func (NullString) String ¶
func (self NullString) String() string
Implement `fmt.Stringer`, returning the string as-is.
func (*NullString) UnmarshalJSON ¶
func (self *NullString) UnmarshalJSON(src []byte) error
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise uses the default `json.Unmarshal` behavior for `*string`.
func (*NullString) UnmarshalText ¶
func (self *NullString) UnmarshalText(src []byte) error
Implement `encoding.TextUnmarshaler`, assigning the string as-is.
func (NullString) Value ¶
func (self NullString) Value() (driver.Value, error)
Implement `driver.Valuer`, using `.Get`.
func (*NullString) Zero ¶
func (self *NullString) Zero()
Implement `gt.Zeroer`, zeroing the receiver.
type NullTime ¶
Variant of `time.Time` where zero value is considered empty in text, and null in JSON and SQL. Prevents you from accidentally inserting nonsense times like 0001-01-01 or 1970-01-01 into date/time columns, without the hassle of pointers such as `*time.Time` or unusable types such as `sql.NullTime`.
Differences from `time.Time`:
- Zero value is "" in text.
- Zero value is `null` in JSON.
- Zero value is `null` in SQL.
- Default text encoding is RFC3339.
- Text encoding/decoding is automatically reversible.
Differences from `"database/sql".NullTime`:
- Much easier to use.
- Supports text; zero value is "".
- Supports JSON; zero value is `null`.
- Fewer states: null and zero are one.
In your data model, `time.Time` is often the wrong choice, because the zero value of `time.Time` is considered "non-empty". It leads to accidentally inserting junk data. `*time.Time` is a better choice, but it introduces nil pointer hazards without eliminating the invalid state `&time.Time{}`. `sql.NullTime` is unusable due to lack of support for text and JSON encoding. `gt.NullTime` avoids all of those issues.
For civil dates without time, use `gt.NullDate`.
func ClockNullTime ¶ added in v0.1.17
Creates a UTC timestamp with the given time of day for the first day of the Gregorian calendar.
func NullDateIn ¶
Shortcut for `gt.NullTimeIn` with `T00:00:00`.
func NullDateUTC ¶
Shortcut for `gt.NullDateIn` in UTC.
Note: due to peculiarities of civil time, `gt.NullDateUTC(1, 1, 1)` returns a zero value, while `gt.NullDateUTC(0, 0, 0)` returns a "negative" time.
func NullTimeIn ¶
func NullTimeIn(year int, month time.Month, day, hour, min, sec, nsec int, loc *time.Location) NullTime
`gt.NullTime` version of `time.Date`.
func NullTimeUTC ¶
Shortcut for `gt.NullTimeIn` in UTC.
Note: due to peculiarities of civil time, `gt.NullTimeUTC(1, 1, 1, 0, 0, 0, 0)` returns a zero value, while `gt.NullTimeUTC(0, 0, 0, 0, 0, 0, 0)` returns a "negative" time.
func ParseNullTime ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func (NullTime) AddInterval ¶ added in v0.1.10
Adds the interval to the time, returning the modified time. If the interval is a zero value, the resulting time should be identical to the source.
func (NullTime) AddNullInterval ¶ added in v0.1.10
func (self NullTime) AddNullInterval(val NullInterval) NullTime
Same as `gt.NullTime.AddInterval` but for `gt.NullInterval`.
func (NullTime) AppendFormat ¶
`gt.NullTime` version of `time.Time.AppendFormat`.
func (NullTime) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullTime) GoString ¶
Implement `fmt.GoStringer`, returning Go code that constructs this value. For UTC, the resulting code is valid. For non-UTC, the resulting code is invalid, because `*time.Location` doesn't implement `fmt.GoStringer`.
func (NullTime) IsZero ¶
Implement `gt.Zeroable`. Same as `self.Time().IsZero()`. Unlike most implementations of `gt.Zeroable` in this package, this is NOT equivalent to `reflect.ValueOf(self).IsZero()`, but rather a superset of it.
func (NullTime) Less ¶ added in v0.1.19
Alias for `time.Time.Before`. Also see `gt.NullTime.Before` which is variadic.
func (NullTime) LessOrEqual ¶ added in v0.1.19
Equivalent to `self.Equal(val) || self.Less(val)`.
func (NullTime) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise uses the default `json.Marshal` behavior for `time.Time`.
func (NullTime) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (NullTime) Nanosecond ¶
`gt.NullTime` version of `time.Time.Nanosecond`.
func (*NullTime) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise requires either an RFC3339 timestamp (default time parsing format in Go), or a numeric timestamp in milliseconds.
func (*NullTime) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullTime` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `time.Time` -> assign
- `*time.Time` -> use `.Zero` or assign
- `gt.NullTime` -> assign
- `gt.NullDate` -> assume UTC, convert, assign
- `gt.Getter` -> scan underlying value
func (NullTime) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise returns a text representation in the RFC3339 format.
func (NullTime) SubInterval ¶ added in v0.1.23
Subtracts the given interval, returning the modified time. Inverse of `NullTime.AddInterval`.
func (NullTime) SubNullInterval ¶ added in v0.1.23
func (self NullTime) SubNullInterval(val NullInterval) NullTime
Same as `gt.NullTime.SubInterval` but for `gt.NullInterval`.
func (*NullTime) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise uses the default `json.Unmarshal` behavior for `*time.Time`.
func (*NullTime) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type NullUint ¶
type NullUint uint64
Variant of `uint64` where zero value is considered empty in text, and null in JSON and SQL. Use this for fields where 0 is not allowed, such as primary and foreign keys, or unique bigserials.
Unlike `uint64`, encoding/decoding is not always reversible:
JSON 0 → Go 0 → JSON null SQL 0 → Go 0 → SQL null
In your data model, positive numeric fields should be either:
- Non-nullable; zero value = 0; use `uint64`.
- Nullable; zero value = `null`; 0 is not allowed; use `gt.NullUint`.
Avoid `*uintN`.
func ParseNullUint ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func (NullUint) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullUint) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise uses the default `json.Marshal` behavior for `uint64`.
func (NullUint) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (*NullUint) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise parses the input using `strconv.ParseUint`.
func (*NullUint) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullUint` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `uintN` -> convert and assign
- `*uintN` -> use `.Zero` or convert and assign
- `NullUint` -> assign
- `gt.Getter` -> scan underlying value
TODO also support signed ints.
func (NullUint) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise formats using `strconv.FormatUint`.
func (NullUint) Uint64 ¶ added in v0.1.16
Free cast to the underlying `uint64`. Sometimes handy when this type is embedded in a struct.
func (*NullUint) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise uses the default `json.Unmarshal` behavior for `*uint64`.
func (*NullUint) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type NullUrl ¶ added in v0.1.3
Variant of `*url.URL` with a less-atrocious API. Differences from `*url.URL`:
- Used by value, not by pointer.
- Full support for text, JSON, SQL encoding/decoding.
- Zero value is considered empty in text, and null in JSON and SQL.
- Easier to use.
- Fewer invalid states.
func ParseNullUrl ¶ added in v0.1.3
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func ToNullUrl ¶ added in v0.1.3
Safe cast. Like `gt.NullUrl(*src)` but doesn't panic on nil pointer.
func (NullUrl) AddPath ¶ added in v0.1.20
Returns a modified variant where `.Path` is replaced by combining the existing path with the segments via `gt.Join`. See the docs on `gt.Join`. Also see `.WithPath` that replaces the path instead of appending.
func (NullUrl) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullUrl) EscapedFragment ¶ added in v0.1.3
`gt.NullUrl` version of `(*url.URL).EscapedFragment`.
func (NullUrl) EscapedPath ¶ added in v0.1.3
`gt.NullUrl` version of `(*url.URL).EscapedPath`.
func (NullUrl) Get ¶ added in v0.1.3
Implement `gt.Getter`. If zero, returns `nil`, otherwise uses `.String` to return a string representation.
func (NullUrl) GoString ¶ added in v0.1.3
Implement `fmt.GoStringer`, returning valid Go code that constructs this value.
func (NullUrl) IsZero ¶ added in v0.1.3
Implement `gt.Zeroable`. Equivalent to `reflect.ValueOf(self).IsZero()`.
func (NullUrl) MarshalJSON ¶ added in v0.1.3
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise returns bytes representing a JSON string with the same text as in `.String`.
func (NullUrl) MarshalText ¶ added in v0.1.3
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (NullUrl) Maybe ¶ added in v0.1.14
If zero, returns nil. Otherwise returns a non-nil `*url.URL`.
func (*NullUrl) Parse ¶ added in v0.1.3
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise parses the input using `url.Parse`.
func (NullUrl) RequestURI ¶ added in v0.1.3
`gt.NullUrl` version of `(*url.URL).RequestURI`.
func (NullUrl) ResolveReference ¶ added in v0.1.3
`gt.NullUrl` version of `(*url.URL).ResolveReference`.
func (*NullUrl) Scan ¶ added in v0.1.3
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullUrl` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `url.URL` -> convert and assign
- `*url.URL` -> use `.Zero` or convert and assign
- `NullUrl` -> assign
- `gt.Getter` -> scan underlying value
func (NullUrl) String ¶ added in v0.1.3
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise formats using `(*url.URL).String`.
func (*NullUrl) UnmarshalJSON ¶ added in v0.1.3
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise parses a JSON string, using the same algorithm as `.Parse`.
func (*NullUrl) UnmarshalText ¶ added in v0.1.3
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
func (NullUrl) Url ¶ added in v0.1.14
Converts to `*url.URL`. The returned pointer refers to new memory.
func (NullUrl) WithFragment ¶ added in v0.1.3
Returns a modified variant with replaced `.Fragment`.
func (NullUrl) WithPath ¶ added in v0.1.3
Returns a modified variant where `.Path` is replaced by combining the segments via `gt.Join`. See the docs on `gt.Join`. Also see `.AddPath` that appends to the path instead of replacing it.
func (NullUrl) WithQuery ¶ added in v0.1.3
Returns a modified variant with replaced `.RawQuery` encoded from input.
func (NullUrl) WithRawQuery ¶ added in v0.1.3
Returns a modified variant with replaced `.RawQuery`.
type NullUuid ¶
type NullUuid Uuid
Variant of `gt.Uuid` where zero value is considered empty in text, and null in JSON and SQL. Features:
- Reversible encoding/decoding in text. Zero value is "".
- Reversible encoding/decoding in JSON. Zero value is `null`.
- Reversible encoding/decoding in SQL. Zero value is `null`.
- Text encoding uses simplified format without dashes.
- Text decoding supports formats with and without dashes, case-insensitive.
Differences from `"github.com/google/uuid".UUID`:
- Text encoding uses simplified format without dashes.
- Text decoding supports only simplified and canonical format.
- Supports only version 4 (random except for a few bits).
- Zero value is considered empty in text, and null in JSON and SQL.
Differences from `"github.com/google/uuid".NullUUID`:
- Fewer states: there is NO "00000000000000000000000000000000".
- Easier to use: `NullUuid` is a typedef of `Uuid`, not a wrapper.
For database columns, `NullUuid` is recommended over `Uuid`, even when columns are non-nullable. It prevents you from accidentally using zero-initialized "00000000000000000000000000000000" in SQL or JSON, without the hassle of pointers or additional fields.
func ParseNullUuid ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func RandomNullUuid ¶
func RandomNullUuid() NullUuid
Creates a random UUID using `gt.ReadNullUuid` and "crypto/rand". Panics if random bytes can't be read.
func ReadNullUuid ¶
Creates a UUID (version 4 variant 1) from bytes from the provided reader.
func (NullUuid) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (NullUuid) Get ¶
Implement `gt.Getter`. If zero, returns `nil`, otherwise returns `[16]byte` understood by many DB drivers.
func (NullUuid) GoString ¶ added in v0.1.3
Implement `fmt.GoStringer`, returning valid Go code that constructs this value. The rendered code is biased for readability over performance: it parses a string instead of using a literal constructor.
func (NullUuid) MarshalJSON ¶
Implement `json.Marshaler`. If zero, returns bytes representing `null`. Otherwise returns bytes representing a JSON string with the same text as in `.String`.
func (NullUuid) MarshalText ¶
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (*NullUuid) Parse ¶
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise requires a valid UUID representation. Supports both the short format without dashes, and the canonical format with dashes. Parsing is case-insensitive.
func (*NullUuid) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.NullUuid` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[16]byte` -> assign
- `*[16]byte` -> use `.Zero` or assign
- `gt.Uuid` -> assign
- `gt.NullUuid` -> assign
- `gt.Getter` -> scan underlying value
func (NullUuid) String ¶
Implement `fmt.Stringer`. If zero, returns an empty string. Otherwise returns a simplified text representation: lowercase without dashes.
func (*NullUuid) UnmarshalJSON ¶
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, zeroes the receiver. Otherwise parses a JSON string, using the same algorithm as `.Parse`.
func (*NullUuid) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type Nullable ¶
type Nullable interface{ IsNull() bool }
Implemented by all types in this package. For all "null" types, this is equivalent to `gt.Zeroable`. For all non-"null" types, this always returns `false`.
TODO consider removing from `Encodable` and from non-nullable types.
type Parser ¶
Missing counterpart to `encoding.TextUnmarshaler`. Parses a string, rather than a byte slice.
type PtrGetter ¶
type PtrGetter interface{ GetPtr() any }
Mutable counterpart to `gt.Getter`. Where `.Get` returns an underlying primitive value as a copy, `.GetPtr` returns an underlying primitive value as a pointer. Decoding into the underlying value by using `json.Unmarshal`, SQL decoding, or any other decoding mechanism must mutate the target, and the resulting state must be valid for that type.
Unlike other interfaces, not every type in this package implements this. This is implemented only by types whose underlying value is built-in (strings and numbers) or also supports decoding (`time.Time`).
type Raw ¶ added in v0.1.13
type Raw []byte
Similar to `json.RawMessage` but supports text, JSON, SQL. In all contexts, stores and returns self as-is, with no encoding or decoding.
func (Raw) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, appending self to the buffer as-is.
func (Raw) Get ¶ added in v0.1.13
Implement `gt.Getter`. If empty, returns `nil`, otherwise returns self as `[]byte`.
func (Raw) GoString ¶ added in v0.1.13
Implement `fmt.GoStringer`, returning valid Go code that constructs this value. Assumes that the contents are UTF-8 text that can be represented with a Go string.
func (Raw) Grow ¶ added in v0.1.14
Missing feature of the language / standard library. Grows the slice to ensure at least this much additional capacity (not total capacity), returning a modified version of the slice. The returned slice always has the same length as the original, but its capacity and backing array may have changed. This doesn't ensure EXACTLY the given additional capacity. It follows the usual hidden Go rules for slice growth, and may allocate significantly more than asked. Similar to `(*bytes.Buffer).Grow` but without wrapping, unwrapping, or spurious escapes to the heap.
func (Raw) IsZero ¶ added in v0.1.13
Implement `gt.Zeroable`. Equivalent to `len(self)` == 0. NOT equivalent to `self == nil` or `reflect.ValueOf(self).IsZero()`.
func (Raw) Len ¶ added in v0.1.13
Same as `len(self)`. Handy in edge case scenarios involving embedding.
func (Raw) MarshalJSON ¶ added in v0.1.13
Implement `json.Marshaler`. If empty, returns bytes representing `null`. Otherwise returns self as-is, assuming that the source representation was originally valid JSON.
func (Raw) MarshalText ¶ added in v0.1.13
Implement `encoding.TextMarhaler`, returning self as-is.
func (*Raw) Parse ¶ added in v0.1.13
Implement `gt.Parser`. If the input is empty, empties the receiver while keeping any capacity. Otherwise stores the input as-is, copying it for safety. If the receiver had enough capacity, its backing array may be mutated by this.
func (*Raw) Scan ¶ added in v0.1.13
Implement `sql.Scanner`, converting an arbitrary input to `gt.Raw` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- convertible to `string` -> use `.Parse`
- convertible to `[]byte` -> use `.UnmarshalText`
- `gt.Raw` -> assign, replacing the receiver
- `gt.Getter` -> scan underlying value
func (Raw) String ¶ added in v0.1.13
Implement `fmt.Stringer`. Returns self as-is, performing an unsafe cast.
func (*Raw) UnmarshalJSON ¶ added in v0.1.13
Implement `json.Unmarshaler`. If the input is empty or represents JSON `null`, empties the receiver while keeping any capacity. Otherwise stores the input as-is, copying it for safety. If the receiver had enough capacity, its backing array may be mutated by this.
func (*Raw) UnmarshalText ¶ added in v0.1.13
Implement `encoding.TextUnmarshaler`. If the input is empty, empties the receiver while keeping any capacity. Otherwise stores the input as-is, copying it for safety. If the receiver had enough capacity, its backing array may be mutated by this.
type Setter ¶
type Setter interface{ Set(any) }
Implemented by all types in this package. Same as `.Scan`, but panics on error.
type Ter ¶ added in v0.1.8
type Ter byte
Ternary type / nullable boolean type. Similar to `*bool`, with various advantages. Has three states with the following representations:
TerNull | 0 | "" in text | null in JSON | null in SQL TerFalse | 1 | "false" in text | false in JSON | false in SQL TerTrue | 2 | "true" in text | true in JSON | true in SQL
Differences from `bool`:
- 3 states rather than 2.
- Nullable in JSON and SQL.
- Zero value is empty/null rather than false.
Differences from `*bool`:
- More efficient: 1 byte, no heap indirection, no added GC pressure.
- Safer: no nil pointer panics.
- Zero value is considered empty in text.
- Text encoding/decoding is reversible.
Differences from `sql.NullBool`:
- More efficient: 1 byte rather than 2.
- Much easier to use.
- Supports text.
- Supports JSON.
Valid representations of `gt.Ter`. Other values are considered invalid and will cause panics.
func BoolPtrTer ¶ added in v0.1.8
Converts boolean pointer to ternary:
- nil = gt.TerNull
- &false = gt.TerFalse
- &true = gt.TerTrue
For inverse conversion, use `gt.Ter.BoolPtr`.
func BoolTer ¶ added in v0.1.8
Converts boolean to ternary:
- false = gt.TerFalse
- true = gt.TerTrue
For inverse conversion, use `gt.Ter.LaxBool` or `gt.Ter.TryBool`.
func ParseTer ¶ added in v0.1.8
Shortcut: parses successfully or panics. Provided only for consistency with other types. Prefer constants such as `gt.TerNull`.
func (Ter) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (Ter) BoolPtr ¶ added in v0.1.8
Inverse of `gt.BoolPtrTer`. Converts to a boolean pointer:
- gt.TerNull = nil
- gt.TerFalse = &false
- gt.TerTrue = &true
func (Ter) EqBool ¶ added in v0.1.8
Exact boolean equality. If the receiver is not true or false, this returns false regardless of the input.
func (Ter) Get ¶ added in v0.1.8
Implement `gt.Getter`. If zero, returns `nil`, otherwise returns `bool`.
func (Ter) GoString ¶ added in v0.1.9
Implement `fmt.GoStringer`, returning valid Go code representing this value.
func (Ter) IsZero ¶ added in v0.1.8
Implement `gt.Zeroable`. Equivalent to `reflect.ValueOf(self).IsZero()`.
func (Ter) LaxBool ¶ added in v0.1.8
Semi-inverse of `gt.BoolTer`. Permissive conversion, where anything untrue is considered false. Equivalent to `.IsTrue()`.
func (Ter) MarshalJSON ¶ added in v0.1.8
Implement `json.Marshaler`, using the following representations:
- gt.TerNull = []byte("null")
- gt.TerFalse = []byte("false")
- gt.TerTrue = []byte("true")
The returned slices must not be mutated.
func (Ter) MarshalText ¶ added in v0.1.8
Implement `encoding.TextMarhaler`. If zero, returns nil. Otherwise returns the same representation as `.String`.
func (*Ter) Parse ¶ added in v0.1.8
Implement `gt.Parser`. If the input is empty, zeroes the receiver. Otherwise expects the input to be "false" or "true".
func (*Ter) Scan ¶ added in v0.1.8
Implement `sql.Scanner`, converting an arbitrary input to `gt.Ter` and modifying the receiver. Acceptable inputs:
- `nil` -> use `.Zero`
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `bool` -> use `.SetBool`
- `*bool` -> use `.SetBoolPtr`
- `Ter` -> assign
- `gt.Getter` -> scan underlying value
func (*Ter) SetBoolPtr ¶ added in v0.1.8
Sets the receiver to the result of `gt.BoolPtrTer`.
func (Ter) String ¶ added in v0.1.8
Implement `fmt.Stringer`, using the following representations:
- gt.TerNull = ""
- gt.TerFalse = "false"
- gt.TerTrue = "true"
func (Ter) TryBool ¶ added in v0.1.8
Exact inverse of `gt.BoolTer`. If true or false, converts to a boolean, otherwise panics.
func (*Ter) UnmarshalJSON ¶ added in v0.1.8
Implement `json.Unmarshaler`, using the following representations:
- []byte(nil) = gt.TerNull
- []byte("") = gt.TerNull
- []byte("null") = gt.TerNull
- []byte("false") = gt.TerFalse
- []byte("true") = gt.TerTrue
func (*Ter) UnmarshalText ¶ added in v0.1.8
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.
type Uuid ¶
Simple UUID implementation. Features:
- Reversible encoding/decoding in text.
- Reversible encoding/decoding in JSON.
- Reversible encoding/decoding in SQL.
- Text encoding uses simplified format without dashes.
- Text decoding supports formats with and without dashes, case-insensitive.
Differences from "github.com/google/uuid".UUID:
- Text encoding uses simplified format without dashes.
- Text decoding supports only simplified and canonical format.
- Supports only version 4 (random except for a few bits).
When dealing with databases, it's highly recommended to use `NullUuid` instead.
func ParseUuid ¶
Shortcut: parses successfully or panics. Should be used only in root scope. When error handling is relevant, use `.Parse`.
func RandomUuid ¶
func RandomUuid() Uuid
Creates a random UUID using `gt.ReadUuid` and "crypto/rand". Panics if random bytes can't be read.
func (Uuid) AppendTo ¶ added in v0.1.21
Implement `gt.AppenderTo`, using the same representation as `.String`.
func (Uuid) GoString ¶ added in v0.1.3
Implement `fmt.GoStringer`, returning valid Go code that constructs this value. The rendered code is biased for readability over performance: it parses a string instead of using a literal constructor.
func (Uuid) MarshalJSON ¶
Implement `json.Marshaler`, using the same representation as `.String`.
func (Uuid) MarshalText ¶
Implement `encoding.TextMarhaler`, using the same representation as `.String`.
func (*Uuid) Parse ¶
Implement `gt.Parser`, parsing a valid UUID representation. Supports the short format without dashes and the canonical format with dashes. Parsing is case-insensitive.
func (*Uuid) Scan ¶
Implement `sql.Scanner`, converting an arbitrary input to `gt.Uuid` and modifying the receiver. Acceptable inputs:
- `string` -> use `.Parse`
- `[]byte` -> use `.UnmarshalText`
- `[16]byte` -> assign
- `gt.Uuid` -> assign
- `gt.NullUuid` -> assign
- `gt.Getter` -> scan underlying value
func (Uuid) String ¶
Implement `fmt.Stringer`, returning a simplified text representation: lowercase without dashes.
func (*Uuid) UnmarshalJSON ¶
Implement `json.Unmarshaler`, using the same algorithm as `.Parse`.
func (*Uuid) UnmarshalText ¶
Implement `encoding.TextUnmarshaler`, using the same algorithm as `.Parse`.