PgTimestamp
Namespace: Ankus
Assembly: Ankus.Runtime.dll
Implements .NET’s parsing contract over PostgreSQL’s input function.
[JsonConverter(typeof(PgTimestampConverter))]public readonly struct PgTimestamp : IParsable<PgTimestamp>, IComparable<PgTimestamp>, IEquatable<PgTimestamp>Implements: IParsable<PgTimestamp>, IComparable<PgTimestamp>, IEquatable<PgTimestamp>
Constructors
Section titled “Constructors”PgTimestamp(long)
Section titled “PgTimestamp(long)”Creates a timestamp from microseconds relative to 2000-01-01. Int64 extremes represent infinities.
public PgTimestamp(long microsecondsSinceEpoch)Parameters:
microsecondsSinceEpoch — long
The signed PostgreSQL timestamp offset.
Exceptions:
- ArgumentOutOfRangeException: The finite value is outside PostgreSQL’s timestamp range.
Methods
Section titled “Methods”Add(PgInterval)
Section titled “Add(PgInterval)”Adds an interval using PostgreSQL’s calendar and month-end rules.
public PgTimestamp Add(PgInterval interval)Parameters:
interval — PgInterval
The interval.
Returns: PgTimestamp
The resulting timestamp.
Age(PgTimestamp)
Section titled “Age(PgTimestamp)”Computes a symbolic difference retaining calendar years and months.
public PgInterval Age(PgTimestamp other)Parameters:
other — PgTimestamp
The timestamp to subtract.
Returns: PgInterval
The calendar interval returned by PostgreSQL age.
AtTimeZone(PgInterval)
Section titled “AtTimeZone(PgInterval)”Interprets this local timestamp at a fixed interval offset from UTC.
public PgTimestampTz AtTimeZone(PgInterval offset)Parameters:
offset — PgInterval
A finite interval without months or days; positive values mean east of UTC.
Returns: PgTimestampTz
The resulting UTC instant, 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)
Section titled “AtTimeZone(string)”Interprets this wall-clock time in a named timezone using PostgreSQL’s DST gap and overlap rules.
public PgTimestampTz AtTimeZone(string zone)Parameters:
zone — string
The PostgreSQL timezone name or abbreviation.
Returns: PgTimestampTz
The corresponding UTC instant.
CompareTo(PgTimestamp)
Section titled “CompareTo(PgTimestamp)”Compares wall-clock timestamps and infinities without requiring an active backend.
public int CompareTo(PgTimestamp other)Parameters:
other — PgTimestamp
The timestamp to compare.
Returns: int
A negative value, zero, or a positive value for earlier, equal, or later timestamps.
Create(int, int, int, int, int, double)
Section titled “Create(int, int, int, int, int, double)”Constructs a timestamp using PostgreSQL’s calendar, field validation, and fractional-second rounding.
public static PgTimestamp 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 of month.
hour — int
The hour.
minute — int
The minute.
second — double
The fractional seconds.
Returns: PgTimestamp
The timestamp.
Equals(PgTimestamp)
Section titled “Equals(PgTimestamp)”public bool Equals(PgTimestamp other)Parameters:
other — PgTimestamp
Returns: bool
Equals(object)
Section titled “Equals(object)”public override bool Equals(object obj)Parameters:
obj — object
Returns: bool
Extract(PgDateTimePart)
Section titled “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, or null for an undefined field of infinity.
FromDateTime(DateTime)
Section titled “FromDateTime(DateTime)”Converts an unspecified DateTime, rejecting UTC/local kinds and sub-microsecond ticks.
public static PgTimestamp FromDateTime(DateTime value)Parameters:
value — DateTime
A timezone-free .NET timestamp.
Returns: PgTimestamp
The PostgreSQL timestamp.
Exceptions:
- ArgumentException: The kind is not Unspecified or the value contains sub-microsecond ticks.
FromRawSaturating(long)
Section titled “FromRawSaturating(long)”Creates a timestamp from raw PostgreSQL microseconds, clamping values outside the finite range to infinity.
public static PgTimestamp FromRawSaturating(long microsecondsSinceEpoch)Parameters:
microsecondsSinceEpoch — long
The signed offset from 2000-01-01, including infinity sentinels.
Returns: PgTimestamp
The finite timestamp, negative infinity below the finite minimum, or positive infinity above the finite maximum.
GetDateParts()
Section titled “GetDateParts()”Reads the full-range Gregorian date without a backend, using the containing day for negative epoch offsets.
public (int Year, int Month, int Day) GetDateParts()Returns: (int Year, int Month, int Day)
The year, month, and day. Negative years denote BC; there is no year zero.
Exceptions:
- InvalidOperationException: The timestamp is infinite.
GetHashCode()
Section titled “GetHashCode()”public override int GetHashCode()Returns: int
GetLocalTimestamp(int)
Section titled “GetLocalTimestamp(int)”Gets SQL LOCALTIMESTAMP at the requested precision in the session timezone.
public static PgTimestamp GetLocalTimestamp(int precision = 6)Parameters:
precision — int
Fractional-second digits, zero through six.
Returns: PgTimestamp
The current transaction’s local timestamp.
GetPart(PgDateTimePart)
Section titled “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, or null for an undefined field of an infinite value.
GetTimeParts()
Section titled “GetTimeParts()”Reads exact wall-clock fields without a backend, using a nonnegative time of day before the epoch.
public (int Hour, int Minute, int Second, int Microseconds) GetTimeParts()Returns: (int Hour, int Minute, int Second, int Microseconds)
The hour, minute, whole second, and microseconds within that second.
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Parse(string)
Section titled “Parse(string)”Parses PostgreSQL wall-clock timestamp syntax using the backend’s DateStyle.
public static PgTimestamp Parse(string text)Parameters:
text — string
The timestamp text.
Returns: PgTimestamp
The timestamp.
Round(int)
Section titled “Round(int)”Rounds fractional seconds using PostgreSQL’s timestamp type modifier.
public PgTimestamp Round(int precision)Parameters:
precision — int
Fractional-second digits, zero through six.
Returns: PgTimestamp
The rounded timestamp.
Subtract(PgInterval)
Section titled “Subtract(PgInterval)”Subtracts an interval using PostgreSQL’s calendar and month-end rules.
public PgTimestamp Subtract(PgInterval interval)Parameters:
interval — PgInterval
The interval.
Returns: PgTimestamp
The resulting timestamp.
Subtract(PgTimestamp)
Section titled “Subtract(PgTimestamp)”Computes the elapsed difference with PostgreSQL’s interval normalization.
public PgInterval Subtract(PgTimestamp other)Parameters:
other — PgTimestamp
The timestamp to subtract.
Returns: PgInterval
The signed interval.
ToDate()
Section titled “ToDate()”Extracts the calendar date using PostgreSQL’s infinity rules.
public PgDate ToDate()Returns: PgDate
The date.
ToDateTime()
Section titled “ToDateTime()”Converts a representable finite value to DateTime with Kind Unspecified; other values throw InvalidOperationException.
public DateTime ToDateTime()Returns: DateTime
The timezone-free .NET timestamp.
Exceptions:
- InvalidOperationException: The timestamp is infinite or outside the DateTime range.
ToIsoString()
Section titled “ToIsoString()”Formats the timestamp using PostgreSQL’s ISO JSON representation independently of DateStyle.
public string ToIsoString()Returns: string
The ISO timestamp, or PostgreSQL’s infinity spelling.
ToPostgresString()
Section titled “ToPostgresString()”Formats the timestamp using the backend’s DateStyle.
public string ToPostgresString()Returns: string
The PostgreSQL text.
ToString()
Section titled “ToString()”Formats stored diagnostic values without requiring a backend or reading finite calendar fields.
public override string ToString()Returns: string
The managed record diagnostic representation.
ToTime()
Section titled “ToTime()”Extracts the wall-clock time, or null for infinity.
public PgTime? ToTime()Returns: PgTime?
The time, or null when no finite time exists.
ToTimestampTz()
Section titled “ToTimestampTz()”Interprets this wall-clock time in the current session’s timezone.
public PgTimestampTz ToTimestampTz()Returns: PgTimestampTz
The corresponding UTC instant.
Truncate(PgDateTimePart)
Section titled “Truncate(PgDateTimePart)”Truncates to a PostgreSQL calendar field.
public PgTimestamp Truncate(PgDateTimePart part)Parameters:
part — PgDateTimePart
The truncation field.
Returns: PgTimestamp
The truncated timestamp.
TryParse(string?, out PgTimestamp)
Section titled “TryParse(string?, out PgTimestamp)”Tries to parse PostgreSQL wall-clock timestamp syntax on the active backend thread.
public static bool TryParse(string? text, out PgTimestamp value)Parameters:
text — string
The timestamp text.
value — PgTimestamp
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
Section titled “Properties”Gets the calendar day of the month without a backend.
public int Day { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
FractionalSecond
Section titled “FractionalSecond”Gets the seconds within the minute, including the microsecond fraction, without a backend.
public double FractionalSecond { get; }Value: double
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Gets the hour from zero through twenty-three without a backend.
public int Hour { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
IsFinite
Section titled “IsFinite”Gets whether this timestamp is finite.
public bool IsFinite { get; }Value: bool
IsNegativeInfinity
Section titled “IsNegativeInfinity”Gets whether this timestamp is negative infinity.
public bool IsNegativeInfinity { get; }Value: bool
IsPositiveInfinity
Section titled “IsPositiveInfinity”Gets whether this timestamp is positive infinity.
public bool IsPositiveInfinity { get; }Value: bool
MicrosecondsSinceEpoch
Section titled “MicrosecondsSinceEpoch”Gets the PostgreSQL microsecond offset, including its infinity sentinels.
public long MicrosecondsSinceEpoch { get; }Value: long
MicrosecondsWithinSecond
Section titled “MicrosecondsWithinSecond”Gets the microseconds within the current second, from zero through 999999, without a backend.
public int MicrosecondsWithinSecond { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Minute
Section titled “Minute”Gets the minute within the hour without a backend.
public int Minute { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Gets the calendar month from one through twelve without a backend.
public int Month { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
NegativeInfinity
Section titled “NegativeInfinity”Gets negative infinity.
public static PgTimestamp NegativeInfinity { get; }Value: PgTimestamp
PositiveInfinity
Section titled “PositiveInfinity”Gets positive infinity.
public static PgTimestamp PositiveInfinity { get; }Value: PgTimestamp
Second
Section titled “Second”Gets the whole second within the minute without a backend.
public int Second { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Gets the calendar year without a backend. Negative years denote BC; there is no year zero.
public int Year { get; }Value: int
Exceptions:
- InvalidOperationException: The timestamp is infinite.
Operators
Section titled “Operators”operator +(PgInterval, PgTimestamp)
Section titled “operator +(PgInterval, PgTimestamp)”Adds a calendar interval using PostgreSQL’s rules.
public static PgTimestamp operator +(PgInterval interval, PgTimestamp timestamp)Parameters:
interval — PgInterval
timestamp — PgTimestamp
Returns: PgTimestamp
operator +(PgTimestamp, PgInterval)
Section titled “operator +(PgTimestamp, PgInterval)”Adds a calendar interval using PostgreSQL’s rules.
public static PgTimestamp operator +(PgTimestamp timestamp, PgInterval interval)Parameters:
timestamp — PgTimestamp
interval — PgInterval
Returns: PgTimestamp
operator ==(PgTimestamp, PgTimestamp)
Section titled “operator ==(PgTimestamp, PgTimestamp)”public static bool operator ==(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator >(PgTimestamp, PgTimestamp)
Section titled “operator >(PgTimestamp, PgTimestamp)”Tests whether the left timestamp follows the right timestamp.
public static bool operator >(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator >=(PgTimestamp, PgTimestamp)
Section titled “operator >=(PgTimestamp, PgTimestamp)”Tests whether the left timestamp follows or equals the right timestamp.
public static bool operator >=(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator !=(PgTimestamp, PgTimestamp)
Section titled “operator !=(PgTimestamp, PgTimestamp)”public static bool operator !=(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator <(PgTimestamp, PgTimestamp)
Section titled “operator <(PgTimestamp, PgTimestamp)”Tests whether the left timestamp precedes the right timestamp.
public static bool operator <(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator <=(PgTimestamp, PgTimestamp)
Section titled “operator <=(PgTimestamp, PgTimestamp)”Tests whether the left timestamp precedes or equals the right timestamp.
public static bool operator <=(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: bool
operator -(PgTimestamp, PgInterval)
Section titled “operator -(PgTimestamp, PgInterval)”Subtracts a calendar interval using PostgreSQL’s rules.
public static PgTimestamp operator -(PgTimestamp timestamp, PgInterval interval)Parameters:
timestamp — PgTimestamp
interval — PgInterval
Returns: PgTimestamp
operator -(PgTimestamp, PgTimestamp)
Section titled “operator -(PgTimestamp, PgTimestamp)”Computes the elapsed difference.
public static PgInterval operator -(PgTimestamp left, PgTimestamp right)Parameters:
left — PgTimestamp
right — PgTimestamp
Returns: PgInterval