PosixBoundary

PosixBoundary :: # (opaque)

Exact POSIX coordinates: microseconds since 1970-01-01T00:00:00Z. Leap seconds are not representable on this axis.

Example

Use integer microseconds for exact coordinates, or explicitly select the rounding policy when accepting decimal seconds. Zero is the Unix epoch; this coordinate does not attach a display timezone.

import time.PosixBoundary

expect {
    point = PosixBoundary.from_seconds(1.25, RejectSubmicrosecond)?
    PosixBoundary.to_microseconds(point) == 1250000
}

Examples assume a package dependency named time.

from_microseconds : I64 -> PosixBoundary

Construct an exact position from signed microseconds since the POSIX epoch, 1970-01-01T00:00:00Z. Every I64 value is accepted; leap seconds are not distinct.

to_microseconds : PosixBoundary -> I64

Read the signed microsecond count since the POSIX epoch.

from_nanoseconds : I128 -> Try(PosixBoundary, [Submicrosecond, OutOfRange])

Convert nanoseconds since the POSIX epoch without losing precision. Return Submicrosecond unless divisible by 1000, or OutOfRange if the result cannot fit the supported I64 microsecond range.

from_nanoseconds_with_rounding : I128, Rounding -> Try(PosixBoundary, [Submicrosecond, OutOfRange])

Convert nanoseconds since the POSIX epoch using the supplied rounding policy. Range is checked after rounding; RejectSubmicrosecond rejects an inexact input.

from_seconds : Dec, Rounding -> Try(PosixBoundary, [Submicrosecond, OutOfRange])

Convert exact decimal seconds since the POSIX epoch with explicit rounding. RejectSubmicrosecond preserves exactness; a rounded result outside I64 microseconds returns OutOfRange.

compare : PosixBoundary, PosixBoundary -> [LT, EQ, GT]

Compare exact POSIX positions, returning LT, EQ or GT.

is_lt : PosixBoundary, PosixBoundary -> Bool

Whether the first of two POSIX positions precedes the second in their numeric order.

is_lte : PosixBoundary, PosixBoundary -> Bool

Whether the first of two POSIX positions precedes or equals the second.

is_gt : PosixBoundary, PosixBoundary -> Bool

Whether the first of two POSIX positions follows the second in their numeric order.

is_gte : PosixBoundary, PosixBoundary -> Bool

Whether the first of two POSIX positions follows or equals the second.

to_hash : PosixBoundary, Hasher -> Hasher

Hash POSIX positions consistently with equality for dictionary and set keys. Hash values are not a stable serialization format.

to_inspect : PosixBoundary -> Str

Return a concise diagnostic description of these POSIX positions. Use explicit conversions or text serialization when storing or exchanging data.

is_eq : PosixBoundary, PosixBoundary -> Bool

Equality of POSIX positions; values of other temporal domains must be converted explicitly.

shift : PosixBoundary, PosixDelta -> Try(PosixBoundary, [OutOfRange])

Add a signed POSIX displacement to a position. Return OutOfRange on overflow. For calendar-day or month changes, use calendar arithmetic with an explicit context.

difference : PosixBoundary, PosixBoundary -> Try(PosixDelta, [OutOfRange])

Return the first position minus the second, as a signed POSIX displacement. OutOfRange is possible even when both positions individually fit. This is coordinate width, not leap-aware physical elapsed time.

Rounding : [RejectSubmicrosecond, Floor, Ceiling, TowardZero, NearestTiesEven]

Precision reduction policy. RejectSubmicrosecond rejects inexact input; Floor rounds toward negative infinity, Ceiling toward positive infinity, and TowardZero discards the fractional part. NearestTiesEven chooses the closest microsecond, resolving exact ties to the even microsecond.