PgTimestampTz

Namespace: Ankus

Assembly: Ankus.Runtime.dll

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

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

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

Constructors

PgTimestampTz(long)

Creates an instant from microseconds relative to 2000-01-01 UTC. Int64 extremes represent infinities.

public PgTimestampTz(long microsecondsSinceEpoch)

Parameters:

microsecondsSinceEpoch — long

The signed PostgreSQL timestamp offset.

Exceptions:

• ArgumentOutOfRangeException: The finite value is outside PostgreSQL’s timestamp range.

Methods

Add(PgInterval)

Adds a calendar interval in the session timezone, retaining daylight-saving distinctions.

public PgTimestampTz Add(PgInterval interval)

Parameters:

interval — PgInterval

The interval.

Returns: PgTimestampTz

The resulting UTC instant.

Age(PgTimestampTz)

Computes a symbolic calendar difference in the session timezone.

public PgInterval Age(PgTimestampTz other)

Parameters:

other — PgTimestampTz

The instant to subtract.

Returns: PgInterval

The calendar interval returned by PostgreSQL age.

AtTimeZone(PgInterval)

Converts this instant to a local timestamp at a fixed interval offset from UTC.

public PgTimestamp AtTimeZone(PgInterval offset)

Parameters:

offset — PgInterval

A finite interval without months or days; positive values mean east of UTC.

Returns: PgTimestamp

The local timestamp, preserving infinities according to PostgreSQL’s rules.

Requires the active backend thread. Offset precision and invalid-interval handling follow PostgreSQL’s interval form of AT TIME ZONE.

AtTimeZone(string)

Converts the instant to a wall-clock timestamp in a named timezone.

public PgTimestamp AtTimeZone(string zone)

Parameters:

zone — string

The PostgreSQL timezone name or abbreviation.

Returns: PgTimestamp

The local wall-clock timestamp.

CompareTo(PgTimestampTz)

Compares UTC instants and infinities without requiring an active backend.

public int CompareTo(PgTimestampTz other)

Parameters:

other — PgTimestampTz

The instant to compare.

Returns: int

A negative value, zero, or a positive value for earlier, equal, or later instants.

Create(int, int, int, int, int, double)

Constructs an instant from local fields in the session timezone using PostgreSQL’s DST rules.

public static PgTimestampTz Create(int year, int month, int day, int hour, int minute, double second)

Parameters:

year — int

The signed year; negative means BC and zero is invalid.

month — int

The month.

day — int

The day.

hour — int

The hour.

minute — int

The minute.

second — double

The fractional seconds, rounded by PostgreSQL.

Returns: PgTimestampTz

The UTC instant.

Create(int, int, int, int, int, double, string)

Constructs an instant from local fields in a named timezone using PostgreSQL’s DST rules.

public static PgTimestampTz Create(int year, int month, int day, int hour, int minute, double second, string zone)

Parameters:

year — int

The signed year; negative means BC and zero is invalid.

month — int

The month.

day — int

The day.

hour — int

The hour.

minute — int

The minute.

second — double

The fractional seconds, rounded by PostgreSQL.

zone — string

The PostgreSQL timezone name or abbreviation.

Returns: PgTimestampTz

The UTC instant.

Equals(PgTimestampTz)

public bool Equals(PgTimestampTz other)

Parameters:

other — PgTimestampTz

Returns: bool

Equals(object)

public override bool Equals(object obj)

Parameters:

obj — object

Returns: bool

Extract(PgDateTimePart)

Extracts a field in the session timezone, 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, or null for an undefined field of infinity.

FromDateTimeOffset(DateTimeOffset)

Converts an offset timestamp to its UTC instant, rejecting sub-microsecond ticks.

public static PgTimestampTz FromDateTimeOffset(DateTimeOffset value)

Parameters:

value — DateTimeOffset

The .NET instant with an offset.

Returns: PgTimestampTz

The PostgreSQL instant.

Exceptions:

• ArgumentException: The value contains sub-microsecond ticks.

FromRawSaturating(long)

Creates an instant from raw PostgreSQL microseconds, clamping values outside the finite range to infinity.

public static PgTimestampTz FromRawSaturating(long microsecondsSinceEpoch)

Parameters:

microsecondsSinceEpoch — long

The signed offset from 2000-01-01 UTC, including infinity sentinels.

Returns: PgTimestampTz

The finite instant, negative infinity below the finite minimum, or positive infinity above the finite maximum.

FromUnixTimeSeconds(double)

Converts fractional Unix epoch seconds with PostgreSQL’s to_timestamp rules.

public static PgTimestampTz FromUnixTimeSeconds(double seconds)

Parameters:

seconds — double

Seconds relative to 1970-01-01 UTC.

Returns: PgTimestampTz

The UTC instant.

GetCurrentTimestamp(int)

Gets SQL CURRENT_TIMESTAMP rounded to the requested precision.

public static PgTimestampTz GetCurrentTimestamp(int precision = 6)

Parameters:

precision — int

Fractional-second digits, zero through six.

Returns: PgTimestampTz

The current transaction’s UTC instant.

GetDateParts()

Reads calendar fields in the backend’s session timezone without narrowing through a wall-clock timestamp conversion.

public (int Year, int Month, int Day) GetDateParts()

Returns: (int Year, int Month, int Day)

The local year, month, and day. Negative years denote BC; there is no year zero.

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

GetHashCode()

public override int GetHashCode()

Returns: int

GetPart(PgDateTimePart)

Reads a floating-point field in the session timezone with PostgreSQL date_part semantics.

public double? GetPart(PgDateTimePart part)

Parameters:

part — PgDateTimePart

The field.

Returns: double?

The field, or null for an undefined field of an infinite value.

GetTimeParts()

Reads exact wall-clock fields in the backend’s session timezone.

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.

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

Parse(string)

Parses PostgreSQL timestamp syntax, resolving omitted zones with the session timezone.

public static PgTimestampTz Parse(string text)

Parameters:

text — string

The timestamp text.

Returns: PgTimestampTz

The UTC instant.

Round(int)

Rounds fractional seconds using PostgreSQL’s timestamptz type modifier.

public PgTimestampTz Round(int precision)

Parameters:

precision — int

Fractional-second digits, zero through six.

Returns: PgTimestampTz

The rounded instant.

Subtract(PgInterval)

Subtracts a calendar interval in the session timezone.

public PgTimestampTz Subtract(PgInterval interval)

Parameters:

interval — PgInterval

The interval.

Returns: PgTimestampTz

The resulting UTC instant.

Subtract(PgTimestampTz)

Computes the elapsed difference using PostgreSQL interval normalization.

public PgInterval Subtract(PgTimestampTz other)

Parameters:

other — PgTimestampTz

The instant to subtract.

Returns: PgInterval

The signed interval.

ToDate()

Extracts the calendar date in the session timezone.

public PgDate ToDate()

Returns: PgDate

The date.

ToDateTimeOffset()

Converts a representable finite instant to a zero-offset DateTimeOffset; other values throw InvalidOperationException.

public DateTimeOffset ToDateTimeOffset()

Returns: DateTimeOffset

The UTC .NET instant.

Exceptions:

• InvalidOperationException: The instant is infinite or outside the DateTimeOffset range.

ToIsoString()

Formats the instant in the session timezone using PostgreSQL’s ISO JSON representation.

public string ToIsoString()

Returns: string

The ISO timestamp with offset, or PostgreSQL’s infinity spelling.

ToIsoString(string)

Formats this instant in an explicit zone using the offset applicable at this instant, independently of session settings.

public string ToIsoString(string zone)

Parameters:

zone — string

The PostgreSQL timezone name or abbreviation.

Returns: string

The ISO timestamp and offset, or an infinity spelling.

ToPostgresString()

Formats the instant using the session timezone and DateStyle.

public string ToPostgresString()

Returns: string

The PostgreSQL text.

ToString()

Formats stored diagnostic values without requiring a backend or reading local calendar fields.

public override string ToString()

Returns: string

The managed record diagnostic representation.

ToTime()

Extracts the wall-clock time in the session timezone, or null for infinity.

public PgTime? ToTime()

Returns: PgTime?

The local time, or null when no finite time exists.

ToTimeTz()

Extracts local time and offset in the session timezone, or null for infinity.

public PgTimeTz? ToTimeTz()

Returns: PgTimeTz?

The local time and offset.

ToTimestamp()

Converts the instant to a wall-clock timestamp in the session timezone.

public PgTimestamp ToTimestamp()

Returns: PgTimestamp

The local timestamp.

ToUtc()

Reads the UTC wall-clock timestamp directly from this instant’s stored value, preserving infinities.

public PgTimestamp ToUtc()

Returns: PgTimestamp

The UTC timestamp without requiring a backend or consulting session settings.

Truncate(PgDateTimePart)

Truncates to a calendar field in the session timezone.

public PgTimestampTz Truncate(PgDateTimePart part)

Parameters:

part — PgDateTimePart

The truncation field.

Returns: PgTimestampTz

The truncated instant.

Truncate(PgDateTimePart, string)

Truncates to a calendar field in an explicit timezone without changing session configuration.

public PgTimestampTz Truncate(PgDateTimePart part, string zone)

Parameters:

part — PgDateTimePart

The truncation field.

zone — string

The PostgreSQL timezone name.

Returns: PgTimestampTz

The truncated instant.

TryParse(string?, out PgTimestampTz)

Tries to parse PostgreSQL timestamp syntax on the active backend thread.

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

Parameters:

text — string

The timestamp text.

value — PgTimestampTz

The parsed instant, 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

ClockTimestamp

Gets PostgreSQL’s current wall-clock timestamp, which can change during a statement.

public static PgTimestampTz ClockTimestamp { get; }

Value: PgTimestampTz

Day

Gets the day of the month in the backend’s session timezone.

public int Day { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

FractionalSecond

Gets the local seconds within the minute, including the microsecond fraction, using the active backend.

public double FractionalSecond { get; }

Value: double

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

Hour

Gets the hour from zero through twenty-three in the backend’s session timezone.

public int Hour { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

IsFinite

Gets whether this instant is finite.

public bool IsFinite { get; }

Value: bool

IsNegativeInfinity

Gets whether this instant is negative infinity.

public bool IsNegativeInfinity { get; }

Value: bool

IsPositiveInfinity

Gets whether this instant is positive infinity.

public bool IsPositiveInfinity { get; }

Value: bool

MicrosecondsSinceEpoch

Gets the UTC microsecond offset, including PostgreSQL’s infinity sentinels.

public long MicrosecondsSinceEpoch { get; }

Value: long

MicrosecondsWithinSecond

Gets the microseconds within the local second, from zero through 999999, using the active backend.

public int MicrosecondsWithinSecond { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

Minute

Gets the minute within the hour in the backend’s session timezone.

public int Minute { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

Month

Gets the month from one through twelve in the backend’s session timezone.

public int Month { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

NegativeInfinity

Gets negative infinity.

public static PgTimestampTz NegativeInfinity { get; }

Value: PgTimestampTz

PositiveInfinity

Gets positive infinity.

public static PgTimestampTz PositiveInfinity { get; }

Value: PgTimestampTz

Second

Gets the whole second within the minute in the backend’s session timezone.

public int Second { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

StatementTimestamp

Gets the start of the current PostgreSQL statement.

public static PgTimestampTz StatementTimestamp { get; }

Value: PgTimestampTz

TimeOfDay

Gets PostgreSQL’s current wall-clock text in the session timezone, like SQL timeofday().

public static string TimeOfDay { get; }

Value: string

Requires the active backend thread. The owned text includes fractional seconds and the timezone abbreviation. It reads the live clock, which can change within a statement.

TransactionTimestamp

Gets the start of the current PostgreSQL transaction.

public static PgTimestampTz TransactionTimestamp { get; }

Value: PgTimestampTz

Year

Gets the year in the backend’s session timezone. Negative years denote BC; there is no year zero.

public int Year { get; }

Value: int

Exceptions:

• InvalidOperationException: The timestamp is infinite or no backend is active.

Operators

operator +(PgInterval, PgTimestampTz)

Adds a calendar interval in the session timezone.

public static PgTimestampTz operator +(PgInterval interval, PgTimestampTz timestamp)

Parameters:

interval — PgInterval

timestamp — PgTimestampTz

Returns: PgTimestampTz

operator +(PgTimestampTz, PgInterval)

Adds a calendar interval in the session timezone.

public static PgTimestampTz operator +(PgTimestampTz timestamp, PgInterval interval)

Parameters:

timestamp — PgTimestampTz

interval — PgInterval

Returns: PgTimestampTz

operator ==(PgTimestampTz, PgTimestampTz)

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator >(PgTimestampTz, PgTimestampTz)

Tests whether the left instant follows the right instant.

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator >=(PgTimestampTz, PgTimestampTz)

Tests whether the left instant follows or equals the right instant.

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator !=(PgTimestampTz, PgTimestampTz)

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator <(PgTimestampTz, PgTimestampTz)

Tests whether the left instant precedes the right instant.

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator <=(PgTimestampTz, PgTimestampTz)

Tests whether the left instant precedes or equals the right instant.

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

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: bool

operator -(PgTimestampTz, PgInterval)

Subtracts a calendar interval in the session timezone.

public static PgTimestampTz operator -(PgTimestampTz timestamp, PgInterval interval)

Parameters:

timestamp — PgTimestampTz

interval — PgInterval

Returns: PgTimestampTz

operator -(PgTimestampTz, PgTimestampTz)

Computes the elapsed difference.

public static PgInterval operator -(PgTimestampTz left, PgTimestampTz right)

Parameters:

left — PgTimestampTz

right — PgTimestampTz

Returns: PgInterval