PgTimeTz

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Implements .NET’s parsing contract over PostgreSQL’s input function.

[JsonConverter(typeof(PgTimeTzConverter))]
public readonly struct PgTimeTz : IParsable<PgTimeTz>, IComparable<PgTimeTz>, IEquatable<PgTimeTz>

Implements: IParsable<PgTimeTz>, IComparable<PgTimeTz>, IEquatable<PgTimeTz>

Constructors

PgTimeTz(PgTime, int)

Creates a time with a signed offset east of UTC, retaining second-resolution historical offsets.

public PgTimeTz(PgTime time, int offsetSeconds)

Parameters:

time — PgTime

The local time, including 24:00:00.

offsetSeconds — int

The offset east of UTC, strictly between -57,600 and 57,600 seconds.

Exceptions:

• ArgumentOutOfRangeException: The offset is outside PostgreSQL’s supported range.

Methods

Add(PgInterval)

Adds the interval’s time component while retaining the fixed offset.

public PgTimeTz Add(PgInterval interval)

Parameters:

interval — PgInterval

The interval.

Returns: PgTimeTz

The resulting time and offset.

AtTimeZone(PgInterval)

Shifts this time to a fixed interval offset using PostgreSQL’s timezone interval rules.

public PgTimeTz AtTimeZone(PgInterval offset)

Parameters:

offset — PgInterval

A finite interval without months or days; sub-second precision follows PostgreSQL.

Returns: PgTimeTz

The shifted wall-clock time and fixed offset.

Positive intervals mean east of UTC. Conversion requires the active backend thread. An offset outside this type’s supported range is rejected when the result is read.

AtTimeZone(string)

Converts the time to a named zone using PostgreSQL’s timetz rules, including its current-date DST resolution.

public PgTimeTz AtTimeZone(string zone)

Parameters:

zone — string

The PostgreSQL timezone name or abbreviation.

Returns: PgTimeTz

The shifted local time and offset.

CompareTo(PgTimeTz)

Compares UTC-adjusted times without wrapping at midnight, breaking ties by PostgreSQL’s offset order.

public int CompareTo(PgTimeTz other)

Parameters:

other — PgTimeTz

The time and offset to compare.

Returns: int

A negative value, zero, or a positive value for lesser, equal, or greater values. No backend is required.

Create(int, int, double)

Constructs a local time with the session timezone’s current-date offset.

public static PgTimeTz Create(int hour, int minute, double second)

Parameters:

hour — int

The hour.

minute — int

The minute.

second — double

The fractional seconds, rounded by PostgreSQL.

Returns: PgTimeTz

The local time and offset.

Create(int, int, double, int)

Constructs a local time with an explicit second-resolution offset east of UTC.

public static PgTimeTz Create(int hour, int minute, double second, int offsetSeconds)

Parameters:

hour — int

The hour.

minute — int

The minute.

second — double

The fractional seconds, rounded by PostgreSQL.

offsetSeconds — int

The offset east of UTC, strictly between -57600 and 57600.

Returns: PgTimeTz

The local time and offset.

Create(int, int, double, string)

Constructs a local time with a named zone’s offset at the current transaction’s start instant.

public static PgTimeTz Create(int hour, int minute, double second, string zone)

Parameters:

hour — int

The local hour, including 24 only for the end-of-day value.

minute — int

The local minute.

second — double

The fractional seconds, rounded by PostgreSQL.

zone — string

A PostgreSQL timezone name, abbreviation, or POSIX specification.

Returns: PgTimeTz

The requested local clock with the resolved fixed offset.

Exceptions:

• ArgumentOutOfRangeException: The resolved offset is not strictly between -57600 and 57600 seconds.

The supplied clock fields are retained. The zone supplies only the offset, which follows transaction-start daylight-saving rules because this type stores no date.

Equals(PgTimeTz)

public bool Equals(PgTimeTz other)

Parameters:

other — PgTimeTz

Returns: bool

Equals(object)

public override bool Equals(object obj)

Parameters:

obj — object

Returns: bool

Extract(PgDateTimePart)

Extracts a numeric field exactly on PostgreSQL 14+; PostgreSQL 13 converts its floating-point result.

public PgNumeric? Extract(PgDateTimePart part)

Parameters:

part — PgDateTimePart

The field to extract.

Returns: PgNumeric?

The numeric field.

FromRawWrapping(long, int)

Creates a time from PostgreSQL’s raw storage convention, wrapping the clock and offset into their valid ranges.

public static PgTimeTz FromRawWrapping(long microseconds, int secondsWestOfUtc)

Parameters:

microseconds — long

The signed raw time; its nonnegative remainder modulo one day becomes the local clock.

secondsWestOfUtc — int

The raw PostgreSQL offset west of UTC. Its nonnegative remainder modulo 57600 is negated to obtain the public OffsetSeconds value east of UTC.

Returns: PgTimeTz

The wrapped clock and fixed offset without requiring a backend.

GetCurrentTime(int)

Gets SQL CURRENT_TIME at the requested precision in the session timezone.

public static PgTimeTz GetCurrentTime(int precision = 6)

Parameters:

precision — int

Fractional-second digits, zero through six.

Returns: PgTimeTz

The current transaction’s local time and offset.

GetHashCode()

public override int GetHashCode()

Returns: int

GetPart(PgDateTimePart)

Reads a floating-point field using PostgreSQL date_part semantics.

public double? GetPart(PgDateTimePart part)

Parameters:

part — PgDateTimePart

The field.

Returns: double?

The field value.

GetTimeParts()

Reads exact local wall-clock fields without requiring a backend or adjusting for the offset.

public (int Hour, int Minute, int Second, int Microseconds) GetTimeParts()

Returns: (int Hour, int Minute, int Second, int Microseconds)

The local hour, minute, whole second, and microseconds within that second.

Parse(string)

Parses PostgreSQL fixed-offset time syntax on the active backend thread.

public static PgTimeTz Parse(string text)

Parameters:

text — string

The time and timezone text.

Returns: PgTimeTz

The parsed time and offset.

Round(int)

Rounds fractional seconds, retaining the offset, with PostgreSQL’s type modifier.

public PgTimeTz Round(int precision)

Parameters:

precision — int

Fractional-second digits, zero through six.

Returns: PgTimeTz

The rounded time and offset.

Subtract(PgInterval)

Subtracts the interval’s time component while retaining the fixed offset.

public PgTimeTz Subtract(PgInterval interval)

Parameters:

interval — PgInterval

The interval.

Returns: PgTimeTz

The resulting time and offset.

ToIsoString()

Formats the time and offset using PostgreSQL’s ISO JSON representation.

public string ToIsoString()

Returns: string

The ISO time and offset.

ToIsoString(string)

Formats the shifted time and offset in a named zone using PostgreSQL’s current-date DST rules.

public string ToIsoString(string zone)

Parameters:

zone — string

The PostgreSQL timezone name or abbreviation.

Returns: string

The ISO time and offset.

ToPostgresString()

Formats the time and offset using PostgreSQL’s output routine.

public string ToPostgresString()

Returns: string

The PostgreSQL text.

ToString()

Formats stored diagnostic values without requiring a backend.

public override string ToString()

Returns: string

The managed record diagnostic representation.

ToTime()

Removes the offset without shifting the local time.

public PgTime ToTime()

Returns: PgTime

The wall-clock time.

ToUtc()

Converts the fixed-offset local time to UTC, wrapping across midnight and normalizing 24:00 to midnight.

public PgTime ToUtc()

Returns: PgTime

The UTC time of day without requiring a backend.

TryParse(string?, out PgTimeTz)

Tries to parse PostgreSQL fixed-offset time syntax on the active backend thread.

public static bool TryParse(string? text, out PgTimeTz value)

Parameters:

text — string

The time and offset text.

value — PgTimeTz

The parsed value, or the default value on invalid input.

Returns: bool

Whether the input is valid. Backend-access and operational errors still throw.

Invalid input leaves no error pending: PostgreSQL 16 and later report it as a soft input error, and earlier majors roll back an internal subtransaction. Before PostgreSQL 16, transaction callbacks and parallel operations forbid that rollback; native errors there remain pending and throw PgException.

Properties

FractionalSecond

Gets the local seconds within the minute, including the microsecond fraction.

public double FractionalSecond { get; }

Value: double

Hour

Gets the local hour from zero through twenty-four, without adjusting for the offset.

public int Hour { get; }

Value: int

MicrosecondsWithinSecond

Gets the microseconds within the current local second, from zero through 999999.

public int MicrosecondsWithinSecond { get; }

Value: int

Minute

Gets the local minute within the hour.

public int Minute { get; }

Value: int

Offset

Gets the fixed UTC offset as a TimeSpan.

public TimeSpan Offset { get; }

Value: TimeSpan

OffsetHours

Gets the signed whole-hour offset east of UTC, truncated toward zero like PostgreSQL’s timezone_hour field.

public int OffsetHours { get; }

Value: int

OffsetMinutes

Gets the signed remaining whole-minute offset east of UTC, like PostgreSQL’s timezone_minute field.

public int OffsetMinutes { get; }

Value: int

OffsetSeconds

Gets the offset east of UTC in seconds; positive values correspond to SQL offsets such as +05:30.

public int OffsetSeconds { get; }

Value: int

Second

Gets the local whole second within the minute.

public int Second { get; }

Value: int

Time

Gets the local wall-clock time.

public PgTime Time { get; }

Value: PgTime

Operators

operator +(PgInterval, PgTimeTz)

Adds an interval while retaining the fixed offset.

public static PgTimeTz operator +(PgInterval interval, PgTimeTz time)

Parameters:

interval — PgInterval

time — PgTimeTz

Returns: PgTimeTz

operator +(PgTimeTz, PgInterval)

Adds an interval while retaining the fixed offset.

public static PgTimeTz operator +(PgTimeTz time, PgInterval interval)

Parameters:

time — PgTimeTz

interval — PgInterval

Returns: PgTimeTz

operator ==(PgTimeTz, PgTimeTz)

public static bool operator ==(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator >(PgTimeTz, PgTimeTz)

Tests whether the left value sorts after the right value.

public static bool operator >(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator >=(PgTimeTz, PgTimeTz)

Tests whether the left value sorts after or equals the right value.

public static bool operator >=(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator !=(PgTimeTz, PgTimeTz)

public static bool operator !=(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator <(PgTimeTz, PgTimeTz)

Tests whether the left value sorts before the right value.

public static bool operator <(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator <=(PgTimeTz, PgTimeTz)

Tests whether the left value sorts before or equals the right value.

public static bool operator <=(PgTimeTz left, PgTimeTz right)

Parameters:

left — PgTimeTz

right — PgTimeTz

Returns: bool

operator -(PgTimeTz, PgInterval)

Subtracts an interval while retaining the fixed offset.

public static PgTimeTz operator -(PgTimeTz time, PgInterval interval)

Parameters:

time — PgTimeTz

interval — PgInterval

Returns: PgTimeTz