Esc

add

procedureextension6 overloadssince 0.36.1Source
  • macOS: add works on macOS
  • Linux: add works on Linux
  • Windows: add works on Windows
  • Wasm: add works on Wasm

overload 1

add :: (
    value: Date,
    amount: Span,
    overflow := Overflow.CONSTRAIN
) -> (Date, Time_Error)

Applies years/months with month-end policy, then weeks/days; clock units fail.

Example↗
d, error := add(Date.{ 2024, 1, 31 }, Span.{ months = 1 });
assert(error.kind == .NONE && d.month == 2 && d.day == 29);
_, rejected := add(Date.{ 2024, 1, 31 }, Span.{ months = 1 }, .REJECT);
assert(rejected.kind == .INVALID_VALUE);

overload 2

add :: (
    value: Date_Time,
    amount: Span,
    overflow := Overflow.CONSTRAIN
) -> (Date_Time, Time_Error)

Applies calendar units before exact clock units, carrying across midnight.

Example↗
wall, error := add(Date_Time.{ .{ 2024, 2, 28 }, .{ 23, 0, 0, 0 } }, Span.{ days = 1, hours = 2 });
assert(error.kind == .NONE && wall.date.month == 3 && wall.date.day == 1 && wall.time.hour == 1);

overload 3

add :: (value: Time_Of_Day, amount: Span) -> (Time_Of_Day, Time_Error)

Adds clock units modulo one day; all calendar units fail.

Example
t, error := add(Time_Of_Day.{ 23, 30, 0, 0 }, Span.{ hours = 25 });
assert(error.kind == .NONE && t.hour == 0 && t.minute == 30);

overload 4

add :: (
    value: Timestamp,
    amount: Signed_Duration
) -> (Timestamp, Time_Error)

Adds exact elapsed time with checked range and normalization.

Example↗
start, _ := timestamp_from_seconds(0);
step, _ := signed_duration(90);
later, error := add(start, step);
assert(error.kind == .NONE && later.seconds == 90);

overload 5

add :: (value: Timestamp, amount: Span) -> (Timestamp, Time_Error)

Adds clock units only; calendar units, including days, fail.

Example↗
start, _ := timestamp_from_seconds(0);
later, error := add(start, Span.{ hours = 1 });
assert(error.kind == .NONE && later.seconds == 3600);
_, calendar := add(start, Span.{ days = 1 });
assert(calendar.kind != .NONE);

overload 6

add :: (
    value: Zoned,
    amount: Span,
    overflow := Overflow.CONSTRAIN,
    disambiguation := Disambiguation.COMPATIBLE
) -> (Zoned, Time_Error)

Adds calendar units in civil time, resolves, then adds clock units on the timeline.

Example↗
zone, zone_error := time_zone_from_posix("EST5EDT,M3.2.0,M11.1.0");
assert(zone_error.kind == .NONE);
defer time_zone_free(*zone);
start, _ := to_zoned(.{ .{ 2024, 3, 9 }, .{ 12, 0, 0, 0 } }, zone);
by_day, _ := add(start, Span.{ days = 1 });
by_hours, _ := add(start, Span.{ hours = 24 });
assert(by_hours.timestamp.seconds - by_day.timestamp.seconds == 3600);

See also