TimestampFormatters

Module std.format

import std.format;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

fn

pub const fn TryFormatUtcTo(Value: readonly Timestamp&, Builder: mut StringBuilder&) -> Result<void, TimeError>

Appends bounded Gregorian UTC text with exact available subseconds. Value: Readonly timestamp borrowed only for this call. Builder: Writable destination; growth may allocate and invalidates prior views. Return: Ok on calendar formatting, CalendarRange before mutation outside year1..9999. Allocation failures remain sticky and are reported by checked builder finalization.

Example

module example.timestamp_formatting;
from std.format import TryFormatUtcTo, FormatTo;
from std.text import StringBuilder;
from std.time import Timestamp, Duration;
fn Main() -> i32 {
    let Before = Timestamp.Create(Duration<i128, 1, 1000000000>.Create(-1_i128));
    var Builder = StringBuilder();
    if TryFormatUtcTo(Before, Builder) is .Err { Error = _ } { return 1; }
    switch Builder.TryFinalize() {
        case .Ok { Value = Text } => { if Text.View != "1969-12-31T23:59:59.999999999Z" { return 2; } }
        case .Err => return 3;
    }
    // The structural formatter is a distinct trapping entry. Use an already
    // checked in-range timestamp and finalize its independent output owner.
    var Structural = StringBuilder();
    FormatTo(Before, Structural);
    switch Structural.TryFinalize() {
        case .Ok { Value = Text } => { if Text.View != "1969-12-31T23:59:59.999999999Z" { return 4; } }
        case .Err => return 5;
    }
    return 0;
}

fn

pub const fn FormatTo(Value: readonly Timestamp&, Builder: mut StringBuilder&) -> void

Formats a UTC timestamp through the structural Formattable protocol. Value: Readonly timestamp borrowed for this call. Builder: Writable destination, retaining sticky allocation failures. Return: No value; CalendarRange traps. Use TryFormatUtcTo for recoverable range failure. Warning: Builder growth may allocate and invalidates its prior views.