อินสแตนซ์

Absolute point-in-time primitive with precision contract.

Syntax: อินสแตนซ์ | อินสแตนซ์<ms> | อินสแตนซ์<us> | อินสแตนซ์<ns>

Category#

conversion

Related#

• ↦
• ⊥
• ข้อความ

Examples#

radix/corpus/conversio/instans.fab (canonical · conversio)#

Conversio arms for อินสแตนซ์ precision family and ข้อความ datetime provenance.

# =============================================================================
# อินสแตนซ์ — Conversio arms for อินสแตนซ์ precision family and ข้อความ datetime provenance.
# =============================================================================
#
# What this teaches:
#   • Precision family — `อินสแตนซ์<ms>`, `อินสแตนซ์<us>`, `อินสแตนซ์<ns>` let you choose sub-second precision on datetime แปลง.
#   • Widening vs narrowing — coarse→fine widening is lossless; fine→coarse narrowing truncates sub-second bits.
#   • RFC3339 roundtrip — text→อินสแตนซ์ parses, อินสแตนซ์→ข้อความ emits at the declared precision without fabricated digits.
#
# Common mistakes:
#   • Converting `อินสแตนซ์<ns>` to `อินสแตนซ์` and expecting sub-second precision in the text output — fine→coarse narrowing truncates sub-second bits.
#
# See also: ↦, ⊥, ข้อความ
# =============================================================================

# การแปลง — อินสแตนซ์ precision family and ค่า provenance
#
# WHY: `ข้อความ ↦ อินสแตนซ์<N>` restores datetime provenance from wire carriers;
# `อินสแตนซ์ ↔ อินสแตนซ์` re-tags precision; `อินสแตนซ์ ↦ ข้อความ` emits RFC3339 UTC
# at the declared precision contract (no fabricated sub-precision digits).
#
# ข้อความ ↦ อินสแตนซ์<N>    — RFC3339 wire per target precision
# อินสแตนซ์ ↦ อินสแตนซ์<ms>  — coarse→fine widening (lossless at storage)
# อินสแตนซ์<ns> ↦ อินสแตนซ์    — fine→coarse narrowing (truncates sub-second bits)
# อินสแตนซ์ ↦ ข้อความ        — precision-honoring RFC3339 `Z` emit
# ข้อความ ↦ อินสแตนซ์ ⊥ …     — explicit recovery when wire is not a datetime

main {
    const string utc ← "1979-05-27T07:32:00.123456Z"
    const string offset ← "1979-05-27T16:32:00+0900"
    const instant seconds ← utc ↦ instant
    const instant<ms> millis ← seconds ↦ instant<ms>
    const instant<us> micros ← utc ↦ instant<us>
    const instant<ns> nanos ← utc ↦ instant<ns>
    const instant normalized ← offset ↦ instant
    assert (millis ↦ string) ≡ "1979-05-27T07:32:00.000Z"
    assert (micros ↦ string) ≡ "1979-05-27T07:32:00.123456Z"
    assert normalized ≡ seconds panic "offset ingest lands on same UTC instant"
    const instant<ns> fine ← nanos
    const instant narrowed ← fine ↦ instant
    assert (narrowed ↦ string) ≡ "1979-05-27T07:32:00Z"
    const string bad ← "not-a-datetime"
    const instant recovered ← bad ↦ instant ⊥ seconds
    assert recovered ≡ seconds
    print seconds ↦ string
    print millis ↦ string
    print micros ↦ string
    print nanos ↦ string
    print narrowed ↦ string
}

Expected output:

1979-05-27T07:32:00Z
1979-05-27T07:32:00.000Z
1979-05-27T07:32:00.123456Z
1979-05-27T07:32:00.123456000Z
1979-05-27T07:32:00Z

radix/corpus/instans/instans.fab (canonical · keyword)#

Absolute point-in-time primitive with precision contract.

# =============================================================================
# อินสแตนซ์ — Absolute point-in-time primitive with precision contract
# =============================================================================
#
# What this teaches:
#   • Absolute point-in-time primitive with precision contract.
#   • Related keywords: ↦, ⊥, ข้อความ
#
# Common mistakes:
#   • Using `อินสแตนซ์ ∷ T` (static ascription) instead of `อินสแตนซ์ ↦ T` (runtime แปลง) — use `↦` for runtime datetime parsing and extraction (SEM016).
#
# See also: ↦, ⊥, ข้อความ
# =============================================================================

# อินสแตนซ์ — wall clock, precision contract, offset ingest, TOML provenance
#
# GRAMMAR:
#   อินสแตนซ์ | อินสแตนซ์<ms> | อินสแตนซ์<us> | อินสแตนซ์<ns>
#   tempus.now() → อินสแตนซ์<ns>; downconvert at use site
#   ค่า ↦ อินสแตนซ์<N> | อินสแตนซ์ ↦ ข้อความ
#
# EXPECTED OUTPUT:
#   Smoke asserts exit 0 only.

import from "norma:time" tempus

import from "norma:toml" toml

import from "norma:value" ค่า

fn epoch_wire(instant t) → string {
    return t ↦ string
}

main {
    # --- precision declarations from canonical nanosecond wall clock ---
    const instant<ns> nanos ← tempus.now()
    const instant secunda ← nanos ↦ instant
    const instant<ms> millis ← nanos ↦ instant<ms>
    const instant<us> micros ← nanos ↦ instant<us>

    # --- ค่า ↦ อินสแตนซ์: UTC wire and numeric offset normalize to same instant ---
    const value utc ← "1979-05-27T07:32:00Z"
    const value offset ← "1979-05-27T03:32:00-04:00"
    const instant parsed ← utc ↦ instant
    const instant normalized ← offset ↦ instant
    assert parsed ≡ normalized panic "offset ingest normalizes to UTC instant"

    # --- TOML datetime provenance (Valor::Instans carrier, not ข้อความ) ---
    const value doc ← toml.parse("creatus = 1979-05-27T07:32:00.123456Z")
    const value carrier ← valor.get(doc, "creatus")
    const instant<us> fromToml ← carrier ↦ instant<us>
    assert (fromToml ↦ string) ≡ "1979-05-27T07:32:00.123456Z" panic "emit honors micros contract"

    # --- precision-tagged equality: distinct at ns, equal at ms ---
    const value leftWire ← "1979-05-27T07:32:00.123456Z"
    const value rightWire ← "1979-05-27T07:32:00.123999Z"
    const instant<ns> left ← leftWire ↦ instant<ns>
    const instant<ns> right ← rightWire ↦ instant<ns>
    assert left ≠ right panic "sub-millisecond bits differ at nanosecond precision"
    const instant<ms> leftMs ← left ↦ instant<ms>
    const instant<ms> rightMs ← right ↦ instant<ms>
    assert leftMs ≡ rightMs panic "same millisecond at declared ms precision"

    # --- cross-precision การแปลง: widen and narrow with observable truncation ---
    const instant<ns> fine ← parsed ↦ instant<ns>
    const instant<ms> coarse ← fine ↦ instant<ms>
    const instant seconds ← fine ↦ instant
    assert (seconds ↦ string) ≡ "1979-05-27T07:32:00Z" panic "narrow to seconds strips sub-second wire"
    const instant<ms> wider ← secunda ↦ instant<ms>
    assert wider ≤ millis panic "cross-precision comparison at coarser operand"

    # --- wire emit and parse-back via TOML (same instant) ---
    const string wire ← epoch_wire(parsed)
    const value replayDoc ← toml.parse("creatus = 1979-05-27T07:32:00Z")
    const value replayCarrier ← valor.get(replayDoc, "creatus")
    const instant roundtrip ← replayCarrier ↦ instant
    assert roundtrip ≡ parsed panic "TOML ingest roundtrip matches UTC valor extract"
    assert wire ≡ "1979-05-27T07:32:00Z" panic "seconds-precision wire emit"
    print wire, secunda, millis, micros, nanos, fromToml, coarse
}