From 406c7562bb5cf1e631f9b3d0e7884756bba3d9a5 Mon Sep 17 00:00:00 2001 From: "Nurul Huda (Apon)" Date: Sat, 31 Jan 2026 21:06:16 +0600 Subject: [PATCH] docs: add more doccomment from mdn --- src/Duration.zig | 88 ++++++++++++++++----- src/Instant.zig | 62 +++++++++++---- src/Now.zig | 38 +++++++++ src/PlainDate.zig | 64 ++++++++++++++- src/PlainDateTime.zig | 96 +++++++++++++++++++--- src/PlainMonthDay.zig | 32 +++++++- src/PlainTime.zig | 51 +++++++++++- src/PlainYearMonth.zig | 57 +++++++++++++- src/ZonedDateTime.zig | 175 ++++++++++++++++++++++++++++++++++------- src/root.zig | 59 +++++++++++--- src/temporal.zig | 28 +++++-- 11 files changed, 646 insertions(+), 104 deletions(-) diff --git a/src/Duration.zig b/src/Duration.zig index 9fafa90..82a1d7d 100644 --- a/src/Duration.zig +++ b/src/Duration.zig @@ -6,26 +6,41 @@ const PlainDate = @import("PlainDate.zig"); const PlainDateTime = @import("PlainDateTime.zig"); const ZonedDateTime = @import("ZonedDateTime.zig"); +/// The `Temporal.Duration` object represents a difference between two time points, which can be used in date/time arithmetic. +/// It is fundamentally represented as a combination of years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds values. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration const Duration = @This(); _inner: *abi.c.Duration, +/// Options for controlling stringification of a Duration. pub const ToStringOptions = t.ToStringRoundingOptions; +/// Options for controlling stringification of a Duration (alias). pub const ToStringRoundingOptions = t.ToStringRoundingOptions; +/// Units supported by Temporal.Duration (years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds). pub const Unit = t.Unit; +/// Rounding modes for Duration operations. pub const RoundingMode = t.RoundingMode; +/// The sign of a Duration: positive, zero, or negative. pub const Sign = t.Sign; +/// Options for rounding a Duration. pub const RoundingOptions = struct { + /// The largest unit to round to. largest_unit: ?Unit = null, + /// The smallest unit to round to. smallest_unit: ?Unit = null, + /// The rounding mode to use. rounding_mode: ?RoundingMode = null, + /// The increment to round to. rounding_increment: ?u32 = null, + /// The relative-to context (PlainDate, PlainDateTime, or ZonedDateTime). relative_to: ?RelativeTo = null, }; /// Partial duration specification for creating Duration objects. /// This is a wrapper around the C API type to avoid exposing C types directly. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/from pub const PartialDuration = struct { years: ?i64 = null, months: ?i64 = null, @@ -39,7 +54,8 @@ pub const PartialDuration = struct { nanoseconds: ?f64 = null, }; -/// Relative-to context for duration operations. +/// Relative-to context for duration operations, used for balancing and calendar-aware math. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations pub const RelativeTo = union(enum) { plain_date: PlainDate, plain_date_time: PlainDateTime, @@ -48,16 +64,21 @@ pub const RelativeTo = union(enum) { /// Options for Duration.total() providing unit and relative-to context. pub const TotalOptions = struct { + /// The unit to total in. unit: Unit, + /// The relative-to context (PlainDate, PlainDateTime, or ZonedDateTime). relative_to: ?RelativeTo = null, }; +/// Options for Duration.compare() providing relative-to context. pub const CompareOptions = struct { + /// The relative-to context (PlainDate, PlainDateTime, or ZonedDateTime). relative_to: ?RelativeTo = null, }; /// Construct a Duration from years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. -/// Equivalent to `Temporal.Duration.from()` or the constructor. +/// Equivalent to `Temporal.Duration()` constructor. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/Duration pub fn init( years_val: i64, months_val: i64, @@ -142,89 +163,106 @@ fn isTimeWithinRange(self: Duration) bool { return abi.c.temporal_rs_Duration_is_time_within_range(self._inner); } -/// Get the years component of the duration. +/// Returns the number of years in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/years pub fn years(self: Duration) i64 { return abi.c.temporal_rs_Duration_years(self._inner); } -/// Get the months component of the duration. +/// Returns the number of months in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/months pub fn months(self: Duration) i64 { return abi.c.temporal_rs_Duration_months(self._inner); } -/// Get the weeks component of the duration. +/// Returns the number of weeks in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/weeks pub fn weeks(self: Duration) i64 { return abi.c.temporal_rs_Duration_weeks(self._inner); } -/// Get the days component of the duration. +/// Returns the number of days in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/days pub fn days(self: Duration) i64 { return abi.c.temporal_rs_Duration_days(self._inner); } -/// Get the hours component of the duration. +/// Returns the number of hours in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/hours pub fn hours(self: Duration) i64 { return abi.c.temporal_rs_Duration_hours(self._inner); } -/// Get the minutes component of the duration. +/// Returns the number of minutes in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/minutes pub fn minutes(self: Duration) i64 { return abi.c.temporal_rs_Duration_minutes(self._inner); } -/// Get the seconds component of the duration. +/// Returns the number of seconds in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/seconds pub fn seconds(self: Duration) i64 { return abi.c.temporal_rs_Duration_seconds(self._inner); } -/// Get the milliseconds component of the duration. +/// Returns the number of milliseconds in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/milliseconds pub fn milliseconds(self: Duration) i64 { return abi.c.temporal_rs_Duration_milliseconds(self._inner); } -/// Get the microseconds component of the duration. +/// Returns the number of microseconds in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/microseconds pub fn microseconds(self: Duration) f64 { return abi.c.temporal_rs_Duration_microseconds(self._inner); } -/// Get the nanoseconds component of the duration. +/// Returns the number of nanoseconds in the duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/nanoseconds pub fn nanoseconds(self: Duration) f64 { return abi.c.temporal_rs_Duration_nanoseconds(self._inner); } -/// Get the sign of the duration: positive (1), zero (0), or negative (-1). +/// Returns the sign of the duration: positive (1), zero (0), or negative (-1). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/sign pub fn sign(self: Duration) Sign { return abi.from.sign(abi.c.temporal_rs_Duration_sign(self._inner)); } -/// Check if the duration is zero (all fields are zero). +/// Returns true if the duration is zero (all fields are zero), false otherwise. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/blank pub fn blank(self: Duration) bool { return abi.c.temporal_rs_Duration_is_zero(self._inner); } /// Returns a new Duration with the absolute value (all components positive). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/abs pub fn abs(self: Duration) Duration { const ptr: *abi.c.Duration = abi.c.temporal_rs_Duration_abs(self._inner) orelse unreachable; return .{ ._inner = ptr }; } -/// Returns a new Duration with all components negated. +/// Returns a new Duration with all components negated (sign reversed). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/negated pub fn negated(self: Duration) Duration { const ptr: *abi.c.Duration = abi.c.temporal_rs_Duration_negated(self._inner) orelse unreachable; return .{ ._inner = ptr }; } -/// Add two durations together (Temporal.Duration.prototype.add). +/// Returns a new Duration with the sum of this duration and another (balanced as needed). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/add pub fn add(self: Duration, other: Duration) !Duration { return wrapDuration(abi.c.temporal_rs_Duration_add(self._inner, other._inner)); } -/// Subtract another duration from this one (Temporal.Duration.prototype.subtract). +/// Returns a new Duration with the difference between this duration and another (balanced as needed). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/subtract pub fn subtract(self: Duration, other: Duration) !Duration { return wrapDuration(abi.c.temporal_rs_Duration_subtract(self._inner, other._inner)); } -/// Round the duration according to the specified options (Temporal.Duration.prototype.round). +/// Returns a new Duration rounded to the given smallest/largest unit and/or balanced. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round pub fn round(self: Duration, options: RoundingOptions) !Duration { const rel = if (options.relative_to) |r| abi.to.durRelativeTo(r) else abi.c.RelativeTo{ .date = null, .zoned = null }; return wrapDuration(abi.c.temporal_rs_Duration_round(self._inner, abi.to.durRoundingOpts(options), rel)); @@ -235,7 +273,8 @@ fn roundWithProvider(self: Duration, options: RoundingOptions, relative_to: Rela return wrapDuration(abi.c.temporal_rs_Duration_round_with_provider(self._inner, options.toCApi(), relative_to, provider)); } -/// Compare two durations (Temporal.Duration.compare). +/// Compares two durations, returning -1, 0, or 1 if this duration is shorter, equal, or longer than the other. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/compare pub fn compare(self: Duration, other: Duration, options: CompareOptions) !i8 { const rel = if (options.relative_to) |r| abi.to.durRelativeTo(r) else abi.c.RelativeTo{ .date = null, .zoned = null }; const res = abi.c.temporal_rs_Duration_compare(self._inner, other._inner, rel); @@ -248,7 +287,8 @@ fn compareWithProvider(self: Duration, other: Duration, relative_to: RelativeTo, return try abi.extractResult(res); } -/// Get the total value of the duration in the specified unit (Temporal.Duration.prototype.total). +/// Returns the total value of the duration in the specified unit. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/total pub fn total(self: Duration, options: TotalOptions) !f64 { const rel = if (options.relative_to) |r| abi.to.durRelativeTo(r) else abi.c.RelativeTo{ .date = null, .zoned = null }; const res = abi.c.temporal_rs_Duration_total(self._inner, abi.to.unit(options.unit).?, rel); @@ -262,7 +302,8 @@ fn totalWithProvider(self: Duration, options: TotalOptions, provider: *const abi return try abi.extractResult(res); } -/// Convert to string (Temporal.Duration.prototype.toString); caller owns returned slice. +/// Returns a string representing this duration in the ISO 8601 format. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/toString pub fn toString(self: Duration, allocator: std.mem.Allocator, options: ToStringRoundingOptions) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -273,10 +314,14 @@ pub fn toString(self: Duration, allocator: std.mem.Allocator, options: ToStringR return try write.toOwnedSlice(); } +/// Returns a string representing this duration in the ISO 8601 format (same as toString). Intended for JSON serialization. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/toJSON pub fn toJSON(self: Duration, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } +/// Returns a string with a language-sensitive representation of this duration. Not implemented. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/toLocaleString pub fn toLocaleString(self: Duration, allocator: std.mem.Allocator) ![]u8 { _ = self; _ = allocator; @@ -289,6 +334,7 @@ fn clone(self: Duration) Duration { return .{ ._inner = ptr }; } +/// Deinitialize the Duration, freeing underlying resources. pub fn deinit(self: Duration) void { abi.c.temporal_rs_Duration_destroy(self._inner); } diff --git a/src/Instant.zig b/src/Instant.zig index e9f7de5..dd70732 100644 --- a/src/Instant.zig +++ b/src/Instant.zig @@ -4,18 +4,27 @@ const t = @import("temporal.zig"); const Duration = @import("Duration.zig"); +/// The `Temporal.Instant` object represents a unique point in time, with nanosecond precision. +/// It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant const Instant = @This(); _inner: *abi.c.Instant, +/// Units supported by Temporal.Instant (e.g., nanosecond, microsecond, millisecond, second, minute, hour). pub const Unit = t.Unit; +/// Rounding modes for Instant operations. pub const RoundingMode = t.RoundingMode; +/// The sign of a Duration: positive, zero, or negative. pub const Sign = t.Sign; +/// Options for rounding an Instant. pub const RoundingOptions = t.RoundingOptions; +/// Options for difference calculations between Instants. pub const DifferenceSettings = t.DifferenceSettings; +/// Time zone identifier or object for use with toString and toZonedDateTimeISO. pub const TimeZone = t.TimeZone; -/// Options for Instant.toString() +/// Options for Instant.toString(). /// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/toString pub const ToStringOptions = struct { /// Either an integer from 0 to 9, or null for "auto". @@ -36,23 +45,27 @@ pub const ToStringOptions = struct { time_zone: ?TimeZone = null, }; -/// Construct from epoch nanoseconds (Temporal.Instant.fromEpochNanoseconds). +/// Construct an Instant from epoch nanoseconds (Temporal.Instant.fromEpochNanoseconds). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/fromEpochNanoseconds pub fn init(epoch_ns: i128) !Instant { return fromEpochNanoseconds(epoch_ns); } -/// Construct from epoch milliseconds. +/// Construct an Instant from epoch milliseconds (Temporal.Instant.fromEpochMilliseconds). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/fromEpochMilliseconds pub fn fromEpochMilliseconds(epoch_ms: i64) !Instant { return wrapInstant(abi.c.temporal_rs_Instant_from_epoch_milliseconds(epoch_ms)); } -/// Construct from epoch nanoseconds (Temporal.Instant.fromEpochNanoseconds). +/// Construct an Instant from epoch nanoseconds (Temporal.Instant.fromEpochNanoseconds). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/fromEpochNanoseconds pub fn fromEpochNanoseconds(epoch_ns: i128) !Instant { const parts = abi.toI128Nanoseconds(epoch_ns); return wrapInstant(abi.c.temporal_rs_Instant_try_new(parts)); } -/// Parse an ISO 8601 string (Temporal.Instant.from) or from another Temporal.Instant. +/// Parse an RFC 9557 string (Temporal.Instant.from) or from another Temporal.Instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/from pub fn from(info: anytype) !Instant { const T = @TypeOf(info); @@ -87,44 +100,52 @@ inline fn fromUtf8(text: []const u8) !Instant { return wrapInstant(abi.c.temporal_rs_Instant_from_utf8(view)); } -/// Add a Duration to this instant (Temporal.Instant.prototype.add). +/// Returns a new Instant representing this instant moved forward by a given Duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/add pub fn add(self: Instant, duration: *Duration) !Instant { return wrapInstant(abi.c.temporal_rs_Instant_add(self._inner, duration._inner)); } -/// Subtract a Duration from this instant (Temporal.Instant.prototype.subtract). +/// Returns a new Instant representing this instant moved backward by a given Duration. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/subtract pub fn subtract(self: Instant, duration: *Duration) !Instant { return wrapInstant(abi.c.temporal_rs_Instant_subtract(self._inner, duration._inner)); } -/// Difference until another instant (Temporal.Instant.prototype.until). +/// Returns a Duration representing the difference from this instant until another instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/until pub fn until(self: Instant, other: Instant, settings: DifferenceSettings) !Duration { const ptr = (try abi.extractResult(abi.c.temporal_rs_Instant_until(self._inner, other._inner, abi.to.diffsettings(settings)))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } -/// Difference since another instant (Temporal.Instant.prototype.since). +/// Returns a Duration representing the difference from another instant until this instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/since pub fn since(self: Instant, other: Instant, settings: DifferenceSettings) !Duration { const ptr = (try abi.extractResult(abi.c.temporal_rs_Instant_since(self._inner, other._inner, abi.to.diffsettings(settings)))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } -/// Round this instant (Temporal.Instant.prototype.round). +/// Returns a new Instant rounded to the given unit. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/round pub fn round(self: Instant, options: RoundingOptions) !Instant { return wrapInstant(abi.c.temporal_rs_Instant_round(self._inner, abi.to.roundingOpts(options))); } -/// Compare two instants (Temporal.Instant.compare). +/// Compares two Instants, returning -1, 0, or 1 if the first is before, equal, or after the second. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/compare pub fn compare(a: Instant, b: Instant) i8 { return abi.c.temporal_rs_Instant_compare(a._inner, b._inner); } -/// Equality check (Temporal.Instant.prototype.equals). +/// Returns true if two Instants are equal (same epoch nanoseconds). +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/equals pub fn equals(a: Instant, b: Instant) bool { return abi.c.temporal_rs_Instant_equals(a._inner, b._inner); } -/// Convert to string using compiled TZ data; caller owns returned slice. +/// Returns a string representing this instant in the RFC 9557 format, optionally using a time zone. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/toString pub fn toString(self: Instant, allocator: std.mem.Allocator, opts: ToStringOptions) ![]u8 { const zone_opt = if (opts.time_zone) |tz| abi.toTimeZoneOption(tz._inner) else abi.toTimeZoneOption(null); const rounding = optsToRounding(opts); @@ -152,18 +173,20 @@ fn toStringWithProvider(self: Instant, allocator: std.mem.Allocator, provider: * return try write.toOwnedSlice(); } +/// Returns a string representing this instant in the RFC 9557 format (same as toString). Intended for JSON serialization. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/toJSON pub fn toJSON(self: Instant, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } -/// Convert to a locale string representation. -/// Per Temporal spec, toLocaleString returns a formatted string without taking locale/options parameters. -/// This uses auto precision for fractional seconds. +/// Returns a string with a language-sensitive representation of this instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/toLocaleString pub fn toLocaleString(self: Instant, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } -/// Convert to ZonedDateTime using built-in provider (Temporal.Instant.prototype.toZonedDateTimeISO). +/// Returns a ZonedDateTime representing this instant in the specified time zone using the ISO 8601 calendar system. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/toZonedDateTimeISO pub fn toZonedDateTimeISO(self: Instant, zone: TimeZone) !ZonedDateTime { const ptr = (try abi.extractResult(abi.c.temporal_rs_Instant_to_zoned_date_time_iso(self._inner, zone._inner))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; @@ -181,14 +204,19 @@ fn clone(self: Instant) Instant { return .{ ._inner = ptr }; } +/// Returns the number of milliseconds since the Unix epoch for this instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/epochMilliseconds pub fn epochMilliseconds(self: Instant) i64 { return abi.c.temporal_rs_Instant_epoch_milliseconds(self._inner); } +/// Returns the number of nanoseconds since the Unix epoch for this instant. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/epochNanoseconds pub fn epochNanoseconds(self: Instant) i128 { return abi.fromI128Nanoseconds(abi.c.temporal_rs_Instant_epoch_nanoseconds(self._inner)); } +/// Deinitialize the Instant, freeing underlying resources. pub fn deinit(self: Instant) void { abi.c.temporal_rs_Instant_destroy(self._inner); } diff --git a/src/Now.zig b/src/Now.zig index 7862e4f..38196ee 100644 --- a/src/Now.zig +++ b/src/Now.zig @@ -5,18 +5,47 @@ const PlainDateTime = @import("PlainDateTime.zig"); const PlainTime = @import("PlainTime.zig"); const ZonedDateTime = @import("ZonedDateTime.zig"); +/// # Temporal.Now +/// +/// The `Temporal.Now` namespace object contains static methods for getting the current time in various formats. +/// +/// - [MDN Temporal.Now](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now) +/// +/// ## Description +/// +/// Unlike most global objects, `Temporal.Now` is not a constructor. All properties and methods are static. +/// +/// ## Example +/// +/// ```js +/// Temporal.Now.instant(); +/// Temporal.Now.plainDateISO(); +/// Temporal.Now.plainDateTimeISO(); +/// Temporal.Now.plainTimeISO(); +/// Temporal.Now.timeZoneId(); +/// Temporal.Now.zonedDateTimeISO(); +/// ``` const Now = @This(); +/// Returns the current time as a [`Temporal.Instant`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant) object. +/// +/// See: [MDN Temporal.Now.instant](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/instant) pub fn instant() !Instant { const ns: i128 = std.time.nanoTimestamp(); return Instant.fromEpochNanoseconds(ns); } +/// Returns the current date as a [`Temporal.PlainDate`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate) object, in the ISO 8601 calendar and the specified time zone. +/// +/// See: [MDN Temporal.Now.plainDateISO](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/plainDateISO) pub fn plainDateISO() !PlainDate { const now = currentParts(); return PlainDate.init(now.year, now.month, now.day); } +/// Returns the current date and time as a [`Temporal.PlainDateTime`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime) object, in the ISO 8601 calendar and the specified time zone. +/// +/// See: [MDN Temporal.Now.plainDateTimeISO](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/plainDateTimeISO) pub fn plainDateTimeISO() !PlainDateTime { const now = currentParts(); return PlainDateTime.init( @@ -32,6 +61,9 @@ pub fn plainDateTimeISO() !PlainDateTime { ); } +/// Returns the current time as a [`Temporal.PlainTime`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime) object, in the specified time zone. +/// +/// See: [MDN Temporal.Now.plainTimeISO](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/plainTimeISO) pub fn plainTimeISO() !PlainTime { const now = currentParts(); return PlainTime.init( @@ -44,10 +76,16 @@ pub fn plainTimeISO() !PlainTime { ); } +/// Returns a time zone identifier representing the system's current time zone. +/// +/// See: [MDN Temporal.Now.timeZoneId](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/timeZoneId) pub fn timeZoneId() []const u8 { return "UTC"; } +/// Returns the current date and time as a [`Temporal.ZonedDateTime`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) object, in the ISO 8601 calendar and the specified time zone. +/// +/// See: [MDN Temporal.Now.zonedDateTimeISO](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now/zonedDateTimeISO) pub fn zonedDateTimeISO() !ZonedDateTime { return error.TemporalNotImplemented; } diff --git a/src/PlainDate.zig b/src/PlainDate.zig index ed90107..2f8722c 100644 --- a/src/PlainDate.zig +++ b/src/PlainDate.zig @@ -9,35 +9,59 @@ const ZonedDateTime = @import("ZonedDateTime.zig"); const PlainTime = @import("PlainTime.zig"); const Duration = @import("Duration.zig"); +/// # Temporal.PlainDate +/// +/// The `Temporal.PlainDate` object represents a calendar date (year, month, day) with no time or time zone. +/// +/// The `Temporal.PlainDate` object represents a calendar date (year, month, day) with no time or time zone. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate const PlainDate = @This(); +/// Internal pointer to the underlying C PlainDate object. _inner: *abi.c.PlainDate, +/// Units used for date and time calculations. pub const Unit = t.Unit; +/// Rounding modes for date/time operations. pub const RoundingMode = t.RoundingMode; +/// Sign type for durations. pub const Sign = t.Sign; +/// Settings for difference calculations between dates. pub const DifferenceSettings = t.DifferenceSettings; +/// Options for `toString()` method. pub const ToStringOptions = struct { + /// Controls how the calendar is displayed in the string output. calendar_id: ?CalendarDisplay = null, }; +/// Controls how the calendar is displayed in string output. pub const CalendarDisplay = enum { + /// Display calendar only if not ISO. auto, + /// Always display calendar. always, + /// Never display calendar. never, + /// Display calendar as a critical flag. critical, }; +/// Options for `toZonedDateTime()` method. pub const ToZonedDateTimeOptions = struct { + /// The time zone identifier (IANA string). time_zone: []const u8, + /// Optional PlainTime to use for the time part. plain_time: ?PlainTime = null, }; +/// Creates a new PlainDate from the given ISO year, month, and day. pub fn init(year_val: i32, month_val: u8, day_val: u8) !PlainDate { return calInit(year_val, month_val, day_val, "iso8601"); } +/// Creates a new PlainDate with a specific calendar. +/// - `calendar`: Calendar identifier string (e.g., "iso8601"). pub fn calInit(year_val: i32, month_val: u8, day_val: u8, calendar: []const u8) !PlainDate { const cal_view = abi.toDiplomatStringView(calendar); const cal_result = abi.c.temporal_rs_AnyCalendarKind_parse_temporal_calendar_string(cal_view); @@ -45,6 +69,7 @@ pub fn calInit(year_val: i32, month_val: u8, day_val: u8, calendar: []const u8) return wrapPlainDate(abi.c.temporal_rs_PlainDate_try_new(year_val, month_val, day_val, cal_kind)); } +/// Creates a PlainDate from another PlainDate or from a string (ISO 8601) or UTF-16 array. pub fn from(info: anytype) !PlainDate { const T = @TypeOf(info); @@ -66,50 +91,60 @@ pub fn from(info: anytype) !PlainDate { } } +/// Internal: Creates a PlainDate from a UTF-8 string. inline fn fromUtf8(text: []const u8) !PlainDate { const view = abi.toDiplomatStringView(text); return wrapPlainDate(abi.c.temporal_rs_PlainDate_from_utf8(view)); } +/// Internal: Creates a PlainDate from a UTF-16 string. inline fn fromUtf16(text: []const u16) !PlainDate { const view = abi.toDiplomatString16View(text); return wrapPlainDate(abi.c.temporal_rs_PlainDate_from_utf16(view)); } +/// Compares two PlainDate objects. Returns -1, 0, or 1. pub fn compare(a: PlainDate, b: PlainDate) i8 { return abi.c.temporal_rs_PlainDate_compare(a._inner, b._inner); } +/// Returns true if two PlainDate objects represent the same date. pub fn equals(self: PlainDate, other: PlainDate) bool { return abi.c.temporal_rs_PlainDate_equals(self._inner, other._inner); } +/// Returns a new PlainDate by adding a Duration to this date. pub fn add(self: PlainDate, duration: Duration) !PlainDate { const overflow_opt = abi.c.ArithmeticOverflow_option{ .is_ok = true, .unnamed_0 = .{ .ok = abi.c.ArithmeticOverflow_Constrain } }; return wrapPlainDate(abi.c.temporal_rs_PlainDate_add(self._inner, duration._inner, overflow_opt)); } +/// Returns a new PlainDate by subtracting a Duration from this date. pub fn subtract(self: PlainDate, duration: Duration) !PlainDate { const overflow_opt = abi.c.ArithmeticOverflow_option{ .is_ok = true, .unnamed_0 = .{ .ok = abi.c.ArithmeticOverflow_Constrain } }; return wrapPlainDate(abi.c.temporal_rs_PlainDate_subtract(self._inner, duration._inner, overflow_opt)); } +/// Returns the Duration until another PlainDate, according to the given settings. pub fn until(self: PlainDate, other: PlainDate, settings: DifferenceSettings) !Duration { const ptr = (try abi.extractResult(abi.c.temporal_rs_PlainDate_until(self._inner, other._inner, abi.to.diffsettings(settings)))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns the Duration since another PlainDate, according to the given settings. pub fn since(self: PlainDate, other: PlainDate, settings: DifferenceSettings) !Duration { const ptr = (try abi.extractResult(abi.c.temporal_rs_PlainDate_since(self._inner, other._inner, abi.to.diffsettings(settings)))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns a new PlainDate with some fields replaced (not implemented). pub fn with(self: PlainDate, fields: anytype) !PlainDate { _ = self; _ = fields; return error.TemporalNotImplemented; } +/// Returns a new PlainDate with a different calendar. pub fn withCalendar(self: PlainDate, calendar: []const u8) !PlainDate { const cal_view = abi.toDiplomatStringView(calendar); const cal_result = abi.c.temporal_rs_AnyCalendarKind_parse_temporal_calendar_string(cal_view); @@ -119,22 +154,26 @@ pub fn withCalendar(self: PlainDate, calendar: []const u8) !PlainDate { return .{ ._inner = ptr }; } +/// Returns a PlainDateTime by combining this date with a PlainTime (or midnight if null). pub fn toPlainDateTime(self: PlainDate, time: ?PlainTime) !PlainDateTime { const time_ptr = if (time) |tt| tt._inner else null; const ptr = (try abi.extractResult(abi.c.temporal_rs_PlainDate_to_plain_date_time(self._inner, time_ptr))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns a PlainMonthDay representing the month and day in this date. pub fn toPlainMonthDay(self: PlainDate) !PlainMonthDay { const ptr = (try abi.extractResult(abi.c.temporal_rs_PlainDate_to_plain_month_day(self._inner))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns a PlainYearMonth representing the year and month in this date. pub fn toPlainYearMonth(self: PlainDate) !PlainYearMonth { const ptr = (try abi.extractResult(abi.c.temporal_rs_PlainDate_to_plain_year_month(self._inner))) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns a ZonedDateTime by combining this date with a time and time zone. pub fn toZonedDateTime(self: PlainDate, options: ToZonedDateTimeOptions) !ZonedDateTime { const tz_view = abi.toDiplomatStringView(options.time_zone); const tz_result = abi.c.temporal_rs_TimeZone_try_from_str(tz_view); @@ -146,6 +185,7 @@ pub fn toZonedDateTime(self: PlainDate, options: ToZonedDateTimeOptions) !ZonedD return .{ ._inner = ptr }; } +/// Returns a string representation of the date. pub fn toString(self: PlainDate, allocator: std.mem.Allocator, options: ToStringOptions) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -161,45 +201,55 @@ pub fn toString(self: PlainDate, allocator: std.mem.Allocator, options: ToString return try write.toOwnedSlice(); } +/// Returns a string suitable for use as JSON. pub fn toJSON(self: PlainDate, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } +/// Not implemented. Throws TemporalNotImplemented error. pub fn toLocaleString(self: PlainDate, allocator: std.mem.Allocator) ![]u8 { _ = self; _ = allocator; return error.TemporalNotImplemented; } +/// Not supported. Throws TemporalValueOfNotSupported error. pub fn valueOf(self: PlainDate) !void { _ = self; return error.TemporalValueOfNotSupported; } +/// Returns the day of the month (1-31). pub fn day(self: PlainDate) u8 { return abi.c.temporal_rs_PlainDate_day(self._inner); } +/// Returns the day of the week (1 = Monday, 7 = Sunday). pub fn dayOfWeek(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_day_of_week(self._inner); } +/// Returns the day of the year (1-366). pub fn dayOfYear(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_day_of_year(self._inner); } +/// Returns the number of days in the month for this date. pub fn daysInMonth(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_days_in_month(self._inner); } +/// Returns the number of days in the week for this date. pub fn daysInWeek(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_days_in_week(self._inner); } +/// Returns the number of days in the year for this date. pub fn daysInYear(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_days_in_year(self._inner); } +/// Returns the month code (e.g., "M03"). pub fn monthCode(self: PlainDate, allocator: std.mem.Allocator) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -208,28 +258,34 @@ pub fn monthCode(self: PlainDate, allocator: std.mem.Allocator) ![]u8 { return try write.toOwnedSlice(); } +/// Returns the month (1-12). pub fn month(self: PlainDate) u8 { return abi.c.temporal_rs_PlainDate_month(self._inner); } +/// Returns the number of months in the year for this date. pub fn monthsInYear(self: PlainDate) u16 { return abi.c.temporal_rs_PlainDate_months_in_year(self._inner); } +/// Returns the year. pub fn year(self: PlainDate) i32 { return abi.c.temporal_rs_PlainDate_year(self._inner); } +/// Returns true if the year is a leap year. pub fn inLeapYear(self: PlainDate) bool { return abi.c.temporal_rs_PlainDate_in_leap_year(self._inner); } +/// Returns the calendar identifier for this date. pub fn calendarId(self: PlainDate, allocator: std.mem.Allocator) ![]u8 { const calendar_ptr = abi.c.temporal_rs_PlainDate_calendar(self._inner) orelse return error.TemporalError; const cal_id_view = abi.c.temporal_rs_Calendar_identifier(calendar_ptr); return try allocator.dupe(u8, cal_id_view.data[0..cal_id_view.len]); } +/// Returns the era for this date, if any. pub fn era(self: PlainDate, allocator: std.mem.Allocator) !?[]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -239,39 +295,45 @@ pub fn era(self: PlainDate, allocator: std.mem.Allocator) !?[]u8 { return try write.toOwnedSlice(); } +/// Returns the era year for this date, if any. pub fn eraYear(self: PlainDate) ?u32 { const result = abi.c.temporal_rs_PlainDate_era_year(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } +/// Returns the week of the year for this date, if any. pub fn weekOfYear(self: PlainDate) ?u8 { const result = abi.c.temporal_rs_PlainDate_week_of_year(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } +/// Returns the year of the week for this date, if any. pub fn yearOfWeek(self: PlainDate) ?i32 { const result = abi.c.temporal_rs_PlainDate_year_of_week(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } +/// Returns a clone of this PlainDate. fn clone(self: PlainDate) PlainDate { const ptr = abi.c.temporal_rs_PlainDate_clone(self._inner) orelse unreachable; return .{ ._inner = ptr }; } +/// Frees resources associated with this PlainDate. pub fn deinit(self: PlainDate) void { abi.c.temporal_rs_PlainDate_destroy(self._inner); } +/// Internal: Wraps a result as a PlainDate. fn wrapPlainDate(res: anytype) !PlainDate { const ptr = (try abi.extractResult(res)) orelse return abi.TemporalError.Generic; - return .{ ._inner = ptr }; } +/// Internal: Handles a void result from an FFI call. fn handleVoidResult(res: anytype) !void { _ = try abi.extractResult(res); } diff --git a/src/PlainDateTime.zig b/src/PlainDateTime.zig index 44d36e9..910952f 100644 --- a/src/PlainDateTime.zig +++ b/src/PlainDateTime.zig @@ -7,45 +7,80 @@ const PlainTime = @import("PlainTime.zig"); const ZonedDateTime = @import("ZonedDateTime.zig"); const Duration = @import("Duration.zig"); +/// # Temporal.PlainDateTime +/// +/// The `Temporal.PlainDateTime` object represents a calendar date and wall-clock time, but no time zone or offset. +/// +/// - [MDN Temporal.PlainDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime) +/// The `Temporal.PlainDateTime` object represents a calendar date and wall-clock time, but no time zone or offset. +/// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime const PlainDateTime = @This(); +/// Internal pointer to the underlying C PlainDateTime object. _inner: *abi.c.PlainDateTime, -// Import types from temporal.zig +/// Units used for date and time calculations. pub const Unit = t.Unit; +/// Rounding modes for date/time operations. pub const RoundingMode = t.RoundingMode; +/// Sign type for durations. pub const Sign = t.Sign; +/// Settings for difference calculations between date-times. pub const DifferenceSettings = t.DifferenceSettings; +/// Options for rounding operations. pub const RoundOptions = t.RoundingOptions; -// Type definitions for API compatibility + +/// Controls how the calendar is displayed in string output. pub const CalendarDisplay = enum { + /// Display calendar only if not ISO. auto, + /// Always display calendar. always, + /// Never display calendar. never, + /// Display calendar as a critical flag. critical, }; +/// Options for `toString()` method. pub const ToStringOptions = struct { + /// Number of fractional second digits to include. fractional_second_digits: ?u8 = null, + /// The smallest unit to include in the output. smallest_unit: ?Unit = null, + /// Rounding mode for the output. rounding_mode: ?RoundingMode = null, + /// How to display the calendar in the output. calendar_display: ?CalendarDisplay = null, }; +/// Options for `toZonedDateTime()` method. pub const ToZonedDateTimeOptions = struct { + /// The time zone identifier (IANA string). timeZone: []const u8, + /// Disambiguation option for ambiguous times. disambiguation: ?[]const u8 = null, }; +/// Options for `with()` method. pub const WithOptions = struct { + /// Year value to override. year: ?i32 = null, + /// Month value to override. month: ?u8 = null, + /// Day value to override. day: ?u8 = null, + /// Hour value to override. hour: ?u8 = null, + /// Minute value to override. minute: ?u8 = null, + /// Second value to override. second: ?u8 = null, + /// Millisecond value to override. millisecond: ?u16 = null, + /// Microsecond value to override. microsecond: ?u16 = null, + /// Nanosecond value to override. nanosecond: ?u16 = null, }; @@ -76,7 +111,7 @@ const PartialDateTime = struct { nanosecond: ?u16 = null, }; -// Constructor - creates a PlainDateTime with all parameters +/// Creates a new PlainDateTime with all date and time components. pub fn init( year_val: i32, month_val: u8, @@ -102,6 +137,8 @@ pub fn init( )); } +/// Creates a new PlainDateTime with a specific calendar. +/// - `calendar`: Calendar identifier string (e.g., "iso8601"). pub fn calInit( year_val: i32, month_val: u8, @@ -133,7 +170,7 @@ pub fn calInit( const FromInit = union(enum) { plain_date: PlainDate, plain_date_time: PlainDateTime }; -// Parse from string or object +/// Creates a PlainDateTime from another PlainDateTime, PlainDate, PlainTime, or from a string (ISO 8601) or UTF-16 array. pub fn from(info: anytype, opts: FromOptions) !PlainDateTime { const T = @TypeOf(info); @@ -173,16 +210,17 @@ fn fromUtf16(utf16: []const u16) !PlainDateTime { return wrapPlainDateTime(abi.c.temporal_rs_PlainDateTime_from_parsed(ptr)); } -// Comparison +/// Compares two PlainDateTime objects. Returns -1, 0, or 1. pub fn compare(a: PlainDateTime, b: PlainDateTime) i8 { return abi.c.temporal_rs_PlainDateTime_compare(a._inner, b._inner); } +/// Returns true if two PlainDateTime objects represent the same date and time. pub fn equals(self: PlainDateTime, other: PlainDateTime) bool { return compare(self, other) == 0; } -// Arithmetic +/// Returns a new PlainDateTime by adding a Duration to this date-time. pub fn add(self: PlainDateTime, duration: Duration) !PlainDateTime { const overflow_opt = abi.c.ArithmeticOverflow_option{ .is_ok = true, @@ -192,6 +230,7 @@ pub fn add(self: PlainDateTime, duration: Duration) !PlainDateTime { return wrapPlainDateTime(abi.c.temporal_rs_PlainDateTime_add(self._inner, duration._inner, overflow_opt)); } +/// Returns a new PlainDateTime by subtracting a Duration from this date-time. pub fn subtract(self: PlainDateTime, duration: Duration) !PlainDateTime { const overflow_opt = abi.c.ArithmeticOverflow_option{ .is_ok = true, @@ -200,58 +239,68 @@ pub fn subtract(self: PlainDateTime, duration: Duration) !PlainDateTime { return wrapPlainDateTime(abi.c.temporal_rs_PlainDateTime_subtract(self._inner, duration._inner, overflow_opt)); } +/// Returns the Duration until another PlainDateTime, according to the given settings. pub fn until(self: PlainDateTime, other: PlainDateTime, options: DifferenceSettings) !Duration { const result = abi.c.temporal_rs_PlainDateTime_until(self._inner, other._inner, abi.to.diffsettings(options)); const ptr = (try abi.extractResult(result)) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } +/// Returns the Duration since another PlainDateTime, according to the given settings. pub fn since(self: PlainDateTime, other: PlainDateTime, options: DifferenceSettings) !Duration { const result = abi.c.temporal_rs_PlainDateTime_since(self._inner, other._inner, abi.to.diffsettings(options)); const ptr = (try abi.extractResult(result)) orelse return abi.TemporalError.Generic; return .{ ._inner = ptr }; } -// Rounding +/// Returns a new PlainDateTime rounded according to the given options. pub fn round(self: PlainDateTime, options: RoundOptions) !PlainDateTime { return wrapPlainDateTime(abi.c.temporal_rs_PlainDateTime_round(self._inner, abi.to.roundingOpts(options))); } -// Property accessors - Date fields +/// Returns the calendar identifier for this date-time. pub fn calendarId(self: PlainDateTime, allocator: std.mem.Allocator) ![]u8 { const calendar_ptr = abi.c.temporal_rs_PlainDateTime_calendar(self._inner) orelse return error.TemporalError; const cal_id_view = abi.c.temporal_rs_Calendar_identifier(calendar_ptr); return try allocator.dupe(u8, cal_id_view.data[0..cal_id_view.len]); } +/// Returns the day of the month (1-31). pub fn day(self: PlainDateTime) u8 { return abi.c.temporal_rs_PlainDateTime_day(self._inner); } +/// Returns the day of the week (1 = Monday, 7 = Sunday). pub fn dayOfWeek(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_day_of_week(self._inner); } +/// Returns the day of the year (1-366). pub fn dayOfYear(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_day_of_year(self._inner); } +/// Returns the number of days in the month for this date-time. pub fn daysInMonth(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_days_in_month(self._inner); } +/// Returns the number of days in the week for this date-time. pub fn daysInWeek(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_days_in_week(self._inner); } +/// Returns the number of days in the year for this date-time. pub fn daysInYear(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_days_in_year(self._inner); } +/// Returns the month (1-12). pub fn month(self: PlainDateTime) u8 { return abi.c.temporal_rs_PlainDateTime_month(self._inner); } +/// Returns the month code (e.g., "M03"). pub fn monthCode(self: PlainDateTime, allocator: std.mem.Allocator) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -259,18 +308,22 @@ pub fn monthCode(self: PlainDateTime, allocator: std.mem.Allocator) ![]u8 { return try write.toOwnedSlice(); } +/// Returns the number of months in the year for this date-time. pub fn monthsInYear(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_months_in_year(self._inner); } +/// Returns the year. pub fn year(self: PlainDateTime) i32 { return abi.c.temporal_rs_PlainDateTime_year(self._inner); } +/// Returns true if the year is a leap year. pub fn inLeapYear(self: PlainDateTime) bool { return abi.c.temporal_rs_PlainDateTime_in_leap_year(self._inner); } +/// Returns the era for this date-time, if any. pub fn era(self: PlainDateTime, allocator: std.mem.Allocator) !?[]u8 { const result = abi.c.temporal_rs_PlainDateTime_era(self._inner); if (!result.is_ok) return null; @@ -281,50 +334,58 @@ pub fn era(self: PlainDateTime, allocator: std.mem.Allocator) !?[]u8 { return try write.toOwnedSlice(); } +/// Returns the era year for this date-time, if any. pub fn eraYear(self: PlainDateTime) !?u32 { const result = abi.c.temporal_rs_PlainDateTime_era_year(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } +/// Returns the week of the year for this date-time, if any. pub fn weekOfYear(self: PlainDateTime) !?u16 { const result = abi.c.temporal_rs_PlainDateTime_week_of_year(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } +/// Returns the year of the week for this date-time, if any. pub fn yearOfWeek(self: PlainDateTime) !?i32 { const result = abi.c.temporal_rs_PlainDateTime_year_of_week(self._inner); if (!result.is_ok) return null; return result.unnamed_0.ok; } -// Property accessors - Time fields +/// Returns the hour (0-23). pub fn hour(self: PlainDateTime) u8 { return abi.c.temporal_rs_PlainDateTime_hour(self._inner); } +/// Returns the minute (0-59). pub fn minute(self: PlainDateTime) u8 { return abi.c.temporal_rs_PlainDateTime_minute(self._inner); } +/// Returns the second (0-59). pub fn second(self: PlainDateTime) u8 { return abi.c.temporal_rs_PlainDateTime_second(self._inner); } +/// Returns the millisecond (0-999). pub fn millisecond(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_millisecond(self._inner); } +/// Returns the microsecond (0-999). pub fn microsecond(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_microsecond(self._inner); } +/// Returns the nanosecond (0-999). pub fn nanosecond(self: PlainDateTime) u16 { return abi.c.temporal_rs_PlainDateTime_nanosecond(self._inner); } -// Modification methods +/// Returns a new PlainDateTime with some fields replaced. pub fn with(self: PlainDateTime, partial: WithOptions) !PlainDateTime { // Extract fields from partial, or use current values as defaults const new_year = partial.year orelse self.year(); @@ -358,6 +419,7 @@ pub fn with(self: PlainDateTime, partial: WithOptions) !PlainDateTime { )); } +/// Returns a new PlainDateTime with a different calendar. pub fn withCalendar(self: PlainDateTime, calendar: []const u8) !PlainDateTime { const cal_view = abi.toDiplomatStringView(calendar); const cal_result = abi.c.temporal_rs_AnyCalendarKind_parse_temporal_calendar_string(cal_view); @@ -367,6 +429,7 @@ pub fn withCalendar(self: PlainDateTime, calendar: []const u8) !PlainDateTime { return .{ ._inner = ptr }; } +/// Returns a new PlainDateTime with the time fields replaced by the given PlainTime (or zeroed if null). pub fn withPlainTime(self: PlainDateTime, time: ?PlainTime) !PlainDateTime { const new_hour: u8 = if (time) |tt| tt.hour() else 0; const new_minute: u8 = if (time) |tt| tt.minute() else 0; @@ -395,18 +458,20 @@ pub fn withPlainTime(self: PlainDateTime, time: ?PlainTime) !PlainDateTime { )); } -// Conversion methods +/// Returns a PlainDate representing the date part of this PlainDateTime. pub fn toPlainDate(self: PlainDateTime) !PlainDate { const ptr = abi.c.temporal_rs_PlainDateTime_to_plain_date(self._inner) orelse return error.TemporalError; return .{ ._inner = ptr }; } +/// Returns a PlainTime representing the time part of this PlainDateTime. pub fn toPlainTime(self: PlainDateTime) !PlainTime { const ptr = abi.c.temporal_rs_PlainDateTime_to_plain_time(self._inner) orelse return error.TemporalError; return .{ ._inner = ptr }; } +/// Returns a ZonedDateTime by combining this date-time with a time zone. pub fn toZonedDateTime(self: PlainDateTime, options: ToZonedDateTimeOptions) !ZonedDateTime { const tz_view = abi.toDiplomatStringView(options.timeZone); const tz_result = abi.c.temporal_rs_TimeZone_try_from_str(tz_view); @@ -422,6 +487,7 @@ pub fn toZonedDateTime(self: PlainDateTime, options: ToZonedDateTimeOptions) !Zo return .{ ._inner = ptr }; } +/// Returns a string representation of the date-time. pub fn toString(self: PlainDateTime, allocator: std.mem.Allocator, options: ToStringOptions) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -446,32 +512,36 @@ pub fn toString(self: PlainDateTime, allocator: std.mem.Allocator, options: ToSt return try write.toOwnedSlice(); } +/// Returns a string suitable for use as JSON. pub fn toJSON(self: PlainDateTime, allocator: std.mem.Allocator) ![]u8 { return try self.toString(allocator, .{}); } +/// Returns a locale-specific string representation of the date-time. pub fn toLocaleString(self: PlainDateTime, allocator: std.mem.Allocator) []const u8 { const s = self.toString(allocator, .{}) catch return "PlainDateTime.toLocaleString error"; return s; } +/// Not supported. Throws ComparisonNotSupported error. pub fn valueOf(self: PlainDateTime) !void { _ = self; return error.ComparisonNotSupported; } -// Helper functions +/// Returns a clone of this PlainDateTime. fn clone(self: PlainDateTime) PlainDateTime { return abi.c.temporal_rs_PlainDateTime_clone(self._inner); } +/// Frees resources associated with this PlainDateTime. pub fn deinit(self: *PlainDateTime) void { abi.c.temporal_rs_PlainDateTime_destroy(self._inner); } +/// Internal: Wraps a result as a PlainDateTime. fn wrapPlainDateTime(res: anytype) !PlainDateTime { const ptr = (try abi.extractResult(res)) orelse return abi.TemporalError.Generic; - return .{ ._inner = ptr }; } diff --git a/src/PlainMonthDay.zig b/src/PlainMonthDay.zig index 81f47a4..b267ad6 100644 --- a/src/PlainMonthDay.zig +++ b/src/PlainMonthDay.zig @@ -4,6 +4,11 @@ const t = @import("temporal.zig"); const PlainDate = @import("PlainDate.zig"); +/// # Temporal.PlainMonthDay +/// +/// The `Temporal.PlainMonthDay` object represents a month and day in a calendar, with no year or time. +/// +/// - [MDN Temporal.PlainMonthDay](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay) const PlainMonthDay = @This(); _inner: *abi.c.PlainMonthDay, @@ -32,7 +37,9 @@ fn wrapPlainMonthDay(result: anytype) !PlainMonthDay { return .{ ._inner = ptr }; } -// Constructor +/// Creates a new PlainMonthDay from the given month, day, and optional calendar. +/// Equivalent to the Temporal.PlainMonthDay constructor. +/// See [MDN Temporal.PlainMonthDay() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/PlainMonthDay) pub fn init(month_val: u8, day_val: u8, calendar: ?[]const u8) !PlainMonthDay { const cal_kind = if (calendar) |cal| blk: { const cal_view = abi.toDiplomatStringView(cal); @@ -52,7 +59,8 @@ pub fn init(month_val: u8, day_val: u8, calendar: ?[]const u8) !PlainMonthDay { )); } -// Parse from string +/// Parses a PlainMonthDay from a string. +/// See [MDN Temporal.PlainMonthDay.from()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/from) pub fn from(s: []const u8) !PlainMonthDay { return fromUtf8(s); } @@ -68,21 +76,29 @@ fn fromUtf16(utf16: []const u16) !PlainMonthDay { } // Comparison +/// Returns true if this PlainMonthDay is equal to another (same date and calendar). +/// See [MDN Temporal.PlainMonthDay.prototype.equals()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/equals) pub fn equals(self: PlainMonthDay, other: PlainMonthDay) bool { return abi.c.temporal_rs_PlainMonthDay_equals(self._inner, other._inner); } // Property accessors +/// Returns the calendar identifier used to interpret the internal ISO 8601 date. +/// See [MDN Temporal.PlainMonthDay.prototype.calendarId](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/calendarId) pub fn calendarId(self: PlainMonthDay, allocator: std.mem.Allocator) ![]u8 { const calendar_ptr = abi.c.temporal_rs_PlainMonthDay_calendar(self._inner) orelse return error.TemporalError; const cal_id_view = abi.c.temporal_rs_Calendar_identifier(calendar_ptr); return try allocator.dupe(u8, cal_id_view.data[0..cal_id_view.len]); } +/// Returns the 1-based day index in the month of this date. +/// See [MDN Temporal.PlainMonthDay.prototype.day](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/day) pub fn day(self: PlainMonthDay) u8 { return abi.c.temporal_rs_PlainMonthDay_day(self._inner); } +/// Returns the calendar-specific string representing the month of this date. +/// See [MDN Temporal.PlainMonthDay.prototype.monthCode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/monthCode) pub fn monthCode(self: PlainMonthDay, allocator: std.mem.Allocator) ![]const u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -92,6 +108,8 @@ pub fn monthCode(self: PlainMonthDay, allocator: std.mem.Allocator) ![]const u8 } // Modification +/// Returns a new PlainMonthDay with some fields replaced by new values. +/// See [MDN Temporal.PlainMonthDay.prototype.with()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/with) pub fn with(self: PlainMonthDay, options: WithOptions) !PlainMonthDay { // Build month_code view const month_code_view = if (options.month_code) |mc| @@ -123,6 +141,8 @@ pub fn with(self: PlainMonthDay, options: WithOptions) !PlainMonthDay { } // Conversion +/// Returns a PlainDate representing this month-day and a supplied year in the same calendar system. +/// See [MDN Temporal.PlainMonthDay.prototype.toPlainDate()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/toPlainDate) pub fn toPlainDate(self: PlainMonthDay, year: i32) !PlainDate { const partial_date = abi.c.PartialDate_option{ .is_ok = true, @@ -146,6 +166,8 @@ pub fn toPlainDate(self: PlainMonthDay, year: i32) !PlainDate { } // String conversions +/// Returns a string representing this month-day in RFC 9557 format. +/// See [MDN Temporal.PlainMonthDay.prototype.toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/toString) pub fn toString(self: PlainMonthDay, allocator: std.mem.Allocator) ![]u8 { return toStringWithOptions(self, allocator, .{}); } @@ -161,14 +183,20 @@ fn toStringWithOptions(self: PlainMonthDay, allocator: std.mem.Allocator, option return try write.toOwnedSlice(); } +/// Returns a string representing this month-day in RFC 9557 format (ISO 8601). +/// See [MDN Temporal.PlainMonthDay.prototype.toJSON()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/toJSON) pub fn toJSON(self: PlainMonthDay, allocator: std.mem.Allocator) ![]u8 { return toString(self, allocator); } +/// Returns a language-sensitive string representation of this month-day. +/// See [MDN Temporal.PlainMonthDay.prototype.toLocaleString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/toLocaleString) pub fn toLocaleString(self: PlainMonthDay, allocator: std.mem.Allocator) ![]u8 { return toString(self, allocator); } +/// Throws an error; valueOf() is not supported for PlainMonthDay. +/// See [MDN Temporal.PlainMonthDay.prototype.valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay/valueOf) pub fn valueOf(self: PlainMonthDay) !void { _ = self; return error.ValueError; diff --git a/src/PlainTime.zig b/src/PlainTime.zig index 08e8f29..5165701 100644 --- a/src/PlainTime.zig +++ b/src/PlainTime.zig @@ -4,6 +4,11 @@ const t = @import("temporal.zig"); const Duration = @import("Duration.zig"); +/// # Temporal.PlainTime +/// +/// The `Temporal.PlainTime` object represents a wall-clock time, with no date or time zone. +/// +/// - [MDN Temporal.PlainTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime) const PlainTime = @This(); _inner: *abi.c.PlainTime, @@ -29,7 +34,9 @@ fn wrapPlainTime(result: anytype) !PlainTime { return PlainTime{ ._inner = ptr }; } -// Constructor - creates a PlainTime with all parameters +/// Creates a new PlainTime from the given time components. +/// Equivalent to the Temporal.PlainTime constructor. +/// See [MDN Temporal.PlainTime() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/PlainTime) pub fn init( hour_val: u8, minute_val: u8, @@ -48,7 +55,8 @@ pub fn init( )); } -// Parse from string +/// Parses a PlainTime from a string. +/// See [MDN Temporal.PlainTime.from()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/from) pub fn from(s: []const u8) !PlainTime { return fromUtf8(s); } @@ -63,24 +71,33 @@ fn fromUtf16(utf16: []const u16) !PlainTime { return wrapPlainTime(abi.c.temporal_rs_PlainTime_from_utf16(view)); } -// Comparison +/// Compares two PlainTime instances by their time values. +/// Returns -1, 0, or 1 if the first is before, equal, or after the second. +/// See [MDN Temporal.PlainTime.compare()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/compare) pub fn compare(a: PlainTime, b: PlainTime) i8 { return abi.c.temporal_rs_PlainTime_compare(a._inner, b._inner); } +/// Returns true if this PlainTime is equal to another (same time values). +/// See [MDN Temporal.PlainTime.prototype.equals()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/equals) pub fn equals(self: PlainTime, other: PlainTime) bool { return abi.c.temporal_rs_PlainTime_equals(self._inner, other._inner); } -// Arithmetic +/// Returns a new PlainTime moved forward by the given duration, wrapping around the clock if necessary. +/// See [MDN Temporal.PlainTime.prototype.add()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/add) pub fn add(self: PlainTime, duration: Duration) !PlainTime { return wrapPlainTime(abi.c.temporal_rs_PlainTime_add(self._inner, duration._inner)); } +/// Returns a new PlainTime moved backward by the given duration, wrapping around the clock if necessary. +/// See [MDN Temporal.PlainTime.prototype.subtract()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/subtract) pub fn subtract(self: PlainTime, duration: Duration) !PlainTime { return wrapPlainTime(abi.c.temporal_rs_PlainTime_subtract(self._inner, duration._inner)); } +/// Returns the duration from this PlainTime to another. +/// See [MDN Temporal.PlainTime.prototype.until()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/until) pub fn until(self: PlainTime, other: PlainTime, options: DifferenceSettings) !Duration { const settings = abi.to.diffsettings(options); const result = abi.c.temporal_rs_PlainTime_until(self._inner, other._inner, settings); @@ -88,6 +105,8 @@ pub fn until(self: PlainTime, other: PlainTime, options: DifferenceSettings) !Du return .{ ._inner = ptr }; } +/// Returns the duration from another PlainTime to this one. +/// See [MDN Temporal.PlainTime.prototype.since()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/since) pub fn since(self: PlainTime, other: PlainTime, options: DifferenceSettings) !Duration { const settings = abi.to.diffsettings(options); const result = abi.c.temporal_rs_PlainTime_since(self._inner, other._inner, settings); @@ -96,36 +115,52 @@ pub fn since(self: PlainTime, other: PlainTime, options: DifferenceSettings) !Du } // Rounding +/// Returns a new PlainTime rounded to the given unit and options. +/// See [MDN Temporal.PlainTime.prototype.round()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/round) pub fn round(self: PlainTime, options: RoundOptions) !PlainTime { return wrapPlainTime(abi.c.temporal_rs_PlainTime_round(self._inner, abi.to.roundingOpts(options))); } // Property accessors +/// Returns the hour component of this time (0-23). +/// See [MDN Temporal.PlainTime.prototype.hour](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/hour) pub fn hour(self: PlainTime) u8 { return abi.c.temporal_rs_PlainTime_hour(self._inner); } +/// Returns the minute component of this time (0-59). +/// See [MDN Temporal.PlainTime.prototype.minute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/minute) pub fn minute(self: PlainTime) u8 { return abi.c.temporal_rs_PlainTime_minute(self._inner); } +/// Returns the second component of this time (0-59). +/// See [MDN Temporal.PlainTime.prototype.second](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/second) pub fn second(self: PlainTime) u8 { return abi.c.temporal_rs_PlainTime_second(self._inner); } +/// Returns the millisecond component of this time (0-999). +/// See [MDN Temporal.PlainTime.prototype.millisecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/millisecond) pub fn millisecond(self: PlainTime) u16 { return abi.c.temporal_rs_PlainTime_millisecond(self._inner); } +/// Returns the microsecond component of this time (0-999). +/// See [MDN Temporal.PlainTime.prototype.microsecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/microsecond) pub fn microsecond(self: PlainTime) u16 { return abi.c.temporal_rs_PlainTime_microsecond(self._inner); } +/// Returns the nanosecond component of this time (0-999). +/// See [MDN Temporal.PlainTime.prototype.nanosecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/nanosecond) pub fn nanosecond(self: PlainTime) u16 { return abi.c.temporal_rs_PlainTime_nanosecond(self._inner); } // Modification +/// Returns a new PlainTime with some fields replaced by new values. +/// See [MDN Temporal.PlainTime.prototype.with()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/with) pub fn with(self: PlainTime, options: WithOptions) !PlainTime { const partial = abi.c.PartialTime{ .hour = abi.toOption(abi.c.OptionU8, options.hour), @@ -143,6 +178,8 @@ pub fn with(self: PlainTime, options: WithOptions) !PlainTime { } // String conversions +/// Returns a string representing this PlainTime in RFC 9557 format. +/// See [MDN Temporal.PlainTime.prototype.toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/toString) pub fn toString(self: PlainTime, allocator: std.mem.Allocator) ![]u8 { return toStringWithOptions(self, allocator, .{}); } @@ -163,15 +200,21 @@ fn toStringWithOptions(self: PlainTime, allocator: std.mem.Allocator, options: t return try write.toOwnedSlice(); } +/// Returns a string representing this PlainTime in RFC 9557 format (ISO 8601). +/// See [MDN Temporal.PlainTime.prototype.toJSON()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/toJSON) pub fn toJSON(self: PlainTime, allocator: std.mem.Allocator) ![]u8 { return toString(self, allocator); } +/// Returns a language-sensitive string representation of this PlainTime. +/// See [MDN Temporal.PlainTime.prototype.toLocaleString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/toLocaleString) pub fn toLocaleString(self: PlainTime, allocator: std.mem.Allocator) ![]u8 { // For now, just use toString - locale-specific formatting would require more work return toString(self, allocator); } +/// Throws an error; valueOf() is not supported for PlainTime. +/// See [MDN Temporal.PlainTime.prototype.valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/valueOf) pub fn valueOf(self: PlainTime) !void { _ = self; // PlainTime should not be used in arithmetic/comparison operations implicitly diff --git a/src/PlainYearMonth.zig b/src/PlainYearMonth.zig index cb98680..8718ea1 100644 --- a/src/PlainYearMonth.zig +++ b/src/PlainYearMonth.zig @@ -5,6 +5,11 @@ const t = @import("temporal.zig"); const PlainDate = @import("PlainDate.zig"); const Duration = @import("Duration.zig"); +/// # Temporal.PlainYearMonth +/// +/// The `Temporal.PlainYearMonth` object represents a particular month in a specific year, with no day or time. +/// +/// - [MDN Temporal.PlainYearMonth](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth) const PlainYearMonth = @This(); _inner: *abi.c.PlainYearMonth, @@ -40,7 +45,9 @@ fn wrapPlainYearMonth(result: anytype) !PlainYearMonth { return .{ ._inner = ptr }; } -// Constructor +/// Creates a new PlainYearMonth from the given year, month, and optional calendar. +/// Equivalent to the Temporal.PlainYearMonth constructor. +/// See [MDN Temporal.PlainYearMonth() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/PlainYearMonth) pub fn init(year_val: i32, month_val: u8, calendar: ?[]const u8) !PlainYearMonth { const cal_kind = if (calendar) |cal| blk: { const cal_view = abi.toDiplomatStringView(cal); @@ -60,7 +67,8 @@ pub fn init(year_val: i32, month_val: u8, calendar: ?[]const u8) !PlainYearMonth )); } -// Parse from string +/// Parses a PlainYearMonth from a string. +/// See [MDN Temporal.PlainYearMonth.from()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/from) pub fn from(s: []const u8) !PlainYearMonth { return fromUtf8(s); } @@ -76,25 +84,36 @@ fn fromUtf16(utf16: []const u16) !PlainYearMonth { } // Comparison +/// Compares two PlainYearMonth instances by their ISO date values. +/// Returns -1, 0, or 1 if the first is before, equal, or after the second. +/// See [MDN Temporal.PlainYearMonth.compare()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/compare) pub fn compare(a: PlainYearMonth, b: PlainYearMonth) i8 { return abi.c.temporal_rs_PlainYearMonth_compare(a._inner, b._inner); } +/// Returns true if this PlainYearMonth is equal to another (same ISO date and calendar). +/// See [MDN Temporal.PlainYearMonth.prototype.equals()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/equals) pub fn equals(self: PlainYearMonth, other: PlainYearMonth) bool { return abi.c.temporal_rs_PlainYearMonth_equals(self._inner, other._inner); } // Arithmetic +/// Returns a new PlainYearMonth moved forward by the given duration. +/// See [MDN Temporal.PlainYearMonth.prototype.add()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/add) pub fn add(self: PlainYearMonth, duration: Duration) !PlainYearMonth { const overflow = abi.c.ArithmeticOverflow_Constrain; return wrapPlainYearMonth(abi.c.temporal_rs_PlainYearMonth_add(self._inner, duration._inner, overflow)); } +/// Returns a new PlainYearMonth moved backward by the given duration. +/// See [MDN Temporal.PlainYearMonth.prototype.subtract()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/subtract) pub fn subtract(self: PlainYearMonth, duration: Duration) !PlainYearMonth { const overflow = abi.c.ArithmeticOverflow_Constrain; return wrapPlainYearMonth(abi.c.temporal_rs_PlainYearMonth_subtract(self._inner, duration._inner, overflow)); } +/// Returns the duration from this PlainYearMonth to another. +/// See [MDN Temporal.PlainYearMonth.prototype.until()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/until) pub fn until(self: PlainYearMonth, other: PlainYearMonth, options: DifferenceSettings) !Duration { const settings = abi.to.diffsettings(options); const result = abi.c.temporal_rs_PlainYearMonth_until(self._inner, other._inner, settings); @@ -102,6 +121,8 @@ pub fn until(self: PlainYearMonth, other: PlainYearMonth, options: DifferenceSet return .{ ._inner = ptr }; } +/// Returns the duration from another PlainYearMonth to this one. +/// See [MDN Temporal.PlainYearMonth.prototype.since()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/since) pub fn since(self: PlainYearMonth, other: PlainYearMonth, options: DifferenceSettings) !Duration { const settings = abi.to.diffsettings(options); const result = abi.c.temporal_rs_PlainYearMonth_since(self._inner, other._inner, settings); @@ -110,20 +131,28 @@ pub fn since(self: PlainYearMonth, other: PlainYearMonth, options: DifferenceSet } // Property accessors +/// Returns the calendar identifier used to interpret the internal ISO 8601 date. +/// See [MDN Temporal.PlainYearMonth.prototype.calendarId](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/calendarId) pub fn calendarId(self: PlainYearMonth, allocator: std.mem.Allocator) ![]u8 { const calendar_ptr = abi.c.temporal_rs_PlainYearMonth_calendar(self._inner) orelse return error.TemporalError; const cal_id_view = abi.c.temporal_rs_Calendar_identifier(calendar_ptr); return try allocator.dupe(u8, cal_id_view.data[0..cal_id_view.len]); } +/// Returns the year of this year-month relative to the calendar's epoch. +/// See [MDN Temporal.PlainYearMonth.prototype.year](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/year) pub fn year(self: PlainYearMonth) i32 { return abi.c.temporal_rs_PlainYearMonth_year(self._inner); } +/// Returns the 1-based month index in the year of this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.month](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/month) pub fn month(self: PlainYearMonth) u8 { return abi.c.temporal_rs_PlainYearMonth_month(self._inner); } +/// Returns the calendar-specific string representing the month of this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.monthCode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/monthCode) pub fn monthCode(self: PlainYearMonth, allocator: std.mem.Allocator) ![]const u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -132,22 +161,32 @@ pub fn monthCode(self: PlainYearMonth, allocator: std.mem.Allocator) ![]const u8 return try write.toOwnedSlice(); } +/// Returns the number of days in the month of this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.daysInMonth](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/daysInMonth) pub fn daysInMonth(self: PlainYearMonth) u16 { return abi.c.temporal_rs_PlainYearMonth_days_in_month(self._inner); } +/// Returns the number of days in the year of this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.daysInYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/daysInYear) pub fn daysInYear(self: PlainYearMonth) u16 { return abi.c.temporal_rs_PlainYearMonth_days_in_year(self._inner); } +/// Returns the number of months in the year of this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.monthsInYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/monthsInYear) pub fn monthsInYear(self: PlainYearMonth) u16 { return abi.c.temporal_rs_PlainYearMonth_months_in_year(self._inner); } +/// Returns true if this year-month is in a leap year. +/// See [MDN Temporal.PlainYearMonth.prototype.inLeapYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/inLeapYear) pub fn inLeapYear(self: PlainYearMonth) bool { return abi.c.temporal_rs_PlainYearMonth_in_leap_year(self._inner); } +/// Returns the calendar-specific era of this year-month, or null if not applicable. +/// See [MDN Temporal.PlainYearMonth.prototype.era](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/era) pub fn era(self: PlainYearMonth, allocator: std.mem.Allocator) !?[]const u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -158,6 +197,8 @@ pub fn era(self: PlainYearMonth, allocator: std.mem.Allocator) !?[]const u8 { return result; } +/// Returns the year of this year-month within the era, or null if not applicable. +/// See [MDN Temporal.PlainYearMonth.prototype.eraYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/eraYear) pub fn eraYear(self: PlainYearMonth) ?i32 { const result = abi.c.temporal_rs_PlainYearMonth_era_year(self._inner); if (!result.is_ok) return null; @@ -165,6 +206,8 @@ pub fn eraYear(self: PlainYearMonth) ?i32 { } // Modification +/// Returns a new PlainYearMonth with some fields replaced by new values. +/// See [MDN Temporal.PlainYearMonth.prototype.with()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/with) pub fn with(self: PlainYearMonth, options: WithOptions) !PlainYearMonth { // Build month_code view const month_code_view = if (options.month_code) |mc| @@ -196,6 +239,8 @@ pub fn with(self: PlainYearMonth, options: WithOptions) !PlainYearMonth { } // Conversion +/// Returns a PlainDate representing this year-month and a supplied day in the same calendar system. +/// See [MDN Temporal.PlainYearMonth.prototype.toPlainDate()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/toPlainDate) pub fn toPlainDate(self: PlainYearMonth, day: u8) !PlainDate { const partial_date = abi.c.PartialDate_option{ .is_ok = true, @@ -219,6 +264,8 @@ pub fn toPlainDate(self: PlainYearMonth, day: u8) !PlainDate { } // String conversions +/// Returns a string representing this year-month in RFC 9557 format. +/// See [MDN Temporal.PlainYearMonth.prototype.toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/toString) pub fn toString(self: PlainYearMonth, allocator: std.mem.Allocator) ![]u8 { return toStringWithOptions(self, allocator, .{}); } @@ -234,14 +281,20 @@ fn toStringWithOptions(self: PlainYearMonth, allocator: std.mem.Allocator, optio return try write.toOwnedSlice(); } +/// Returns a JSON string representing this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.toJSON()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/toJSON) pub fn toJSON(self: PlainYearMonth, allocator: std.mem.Allocator) ![]u8 { return toString(self, allocator); } +/// Returns a locale-sensitive string representing this year-month. +/// See [MDN Temporal.PlainYearMonth.prototype.toLocaleString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth/toLocaleString) pub fn toLocaleString(self: PlainYearMonth, allocator: std.mem.Allocator) ![]u8 { return toString(self, allocator); } +/// Throws a TypeError, as PlainYearMonth objects cannot be converted to primitive values. +/// See [MDN Temporal.PlainYearMonth.prototype.valueOf()](https://developer.mozilla pub fn valueOf(self: PlainYearMonth) !void { _ = self; return error.ValueError; diff --git a/src/ZonedDateTime.zig b/src/ZonedDateTime.zig index 43a8390..ce9a101 100644 --- a/src/ZonedDateTime.zig +++ b/src/ZonedDateTime.zig @@ -12,16 +12,34 @@ const ZonedDateTime = @This(); _inner: *abi.c.ZonedDateTime, -// Import types from temporal.zig + +/// The unit of time used for rounding and difference calculations. +/// See [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) for details. pub const Unit = t.Unit; + +/// The rounding mode used for rounding operations. +/// See [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) for details. pub const RoundingMode = t.RoundingMode; + +/// The sign of a duration or difference. +/// See [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) for details. pub const Sign = t.Sign; + +/// Options for difference calculations between ZonedDateTime instances. +/// See [MDN Temporal.ZonedDateTime#instance_methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#instance_methods) for details. pub const DifferenceSettings = t.DifferenceSettings; + +/// Options for rounding ZonedDateTime instances. +/// See [MDN Temporal.ZonedDateTime#instance_methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#instance_methods) for details. pub const RoundOptions = t.RoundingOptions; + +/// Represents a time zone, identified by an IANA time zone identifier or a fixed offset. +/// See [MDN Temporal.ZonedDateTime#time-zones-and-offsets](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time-zones-and-offsets). pub const TimeZone = struct { _inner: abi.c.TimeZone, + /// Initialize a TimeZone from an IANA identifier or offset string. pub fn init(id: []const u8) !TimeZone { const view = abi.toDiplomatStringView(id); const result = abi.c.temporal_rs_TimeZone_try_from_str(view); @@ -30,6 +48,9 @@ pub const TimeZone = struct { } }; + +/// Disambiguation options for resolving ambiguous local times (e.g., during DST transitions). +/// See [MDN Temporal.ZonedDateTime#ambiguity-and-gaps-from-local-time-to-utc-time](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#ambiguity-and-gaps-from-local-time-to-utc-time). pub const Disambiguation = enum { compatible, earlier, @@ -37,6 +58,9 @@ pub const Disambiguation = enum { reject, }; + +/// Options for resolving offset ambiguity when parsing ZonedDateTime from a string. +/// See [MDN Temporal.ZonedDateTime#offset-ambiguity](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#offset-ambiguity). pub const OffsetDisambiguation = enum { use_offset, prefer_offset, @@ -44,6 +68,9 @@ pub const OffsetDisambiguation = enum { reject, }; + +/// Controls how the calendar is displayed in string output. +/// See [MDN Temporal.ZonedDateTime#rfc-9557-format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#rfc-9557-format). pub const CalendarDisplay = enum { auto, always, @@ -51,17 +78,26 @@ pub const CalendarDisplay = enum { critical, }; + +/// Controls how the offset is displayed in string output. +/// See [MDN Temporal.ZonedDateTime#rfc-9557-format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#rfc-9557-format). pub const DisplayOffset = enum { auto, never, }; + +/// Controls how the time zone is displayed in string output. +/// See [MDN Temporal.ZonedDateTime#rfc-9557-format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#rfc-9557-format). pub const DisplayTimeZone = enum { auto, never, critical, }; + +/// Options for formatting ZonedDateTime as a string. +/// See [MDN Temporal.ZonedDateTime#rfc-9557-format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#rfc-9557-format). pub const ToStringOptions = struct { fractional_second_digits: ?u8 = null, smallest_unit: ?Unit = null, @@ -77,47 +113,57 @@ fn wrapZonedDateTime(result: anytype) !ZonedDateTime { return .{ ._inner = ptr }; } -/// Create a ZonedDateTime from epoch nanoseconds +/// Creates a new ZonedDateTime from the given epoch nanoseconds and time zone. +/// Equivalent to the Temporal.ZonedDateTime constructor. +/// See [MDN Temporal.ZonedDateTime() constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/ZonedDateTime) pub fn init(epoch_ns: i128, time_zone: TimeZone) !ZonedDateTime { const ns_parts = abi.toI128Nanoseconds(epoch_ns); return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_from_epoch_nanoseconds(ns_parts, abi.to.toTimeZone(time_zone))); } -/// Create from epoch milliseconds +/// Creates a new ZonedDateTime from the given epoch milliseconds and time zone. +/// See [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) pub fn fromEpochMilliseconds(epoch_ms: i64, time_zone: TimeZone) !ZonedDateTime { return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_from_epoch_milliseconds(epoch_ms, abi.to.toTimeZone(time_zone))); } -/// Create from epoch nanoseconds +/// Creates a new ZonedDateTime from the given epoch nanoseconds and time zone. +/// See [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) pub fn fromEpochNanoseconds(epoch_ns: i128, time_zone: TimeZone) !ZonedDateTime { const ns_parts = abi.toI128Nanoseconds(epoch_ns); return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_from_epoch_nanoseconds(ns_parts, abi.to.toTimeZone(time_zone))); } -/// Parse from string +/// Parses a ZonedDateTime from a string, with optional disambiguation and offset options. +/// See [MDN Temporal.ZonedDateTime.from()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/from) pub fn from(s: []const u8, time_zone: ?TimeZone, disambiguation: Disambiguation, offset_disambiguation: OffsetDisambiguation) !ZonedDateTime { _ = time_zone; // The time zone is parsed from the string const view = abi.toDiplomatStringView(s); return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_from_utf8(view, abi.to.toDisambiguation(disambiguation), abi.to.toOffsetDisambiguation(offset_disambiguation))); } -/// Compare two ZonedDateTime instances +/// Compares two ZonedDateTime instances by their instant values. +/// Returns -1, 0, or 1 if the first is before, equal, or after the second. +/// See [MDN Temporal.ZonedDateTime.compare()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/compare) pub fn compare(a: ZonedDateTime, b: ZonedDateTime) i8 { return abi.c.temporal_rs_ZonedDateTime_compare_instant(a._inner, b._inner); } -/// Add a duration +/// Returns a new ZonedDateTime moved forward by the given duration. +/// See [MDN Temporal.ZonedDateTime.prototype.add()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/add) pub fn add(self: ZonedDateTime, duration: Duration) !ZonedDateTime { const overflow_opt = abi.toOption(abi.c.ArithmeticOverflow_option, null); return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_add(self._inner, duration._inner, overflow_opt)); } -/// Check equality +/// Returns true if this ZonedDateTime is equal to another (same instant, time zone, and calendar). +/// See [MDN Temporal.ZonedDateTime.prototype.equals()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/equals) pub fn equals(self: ZonedDateTime, other: ZonedDateTime) bool { return abi.c.temporal_rs_ZonedDateTime_equals(self._inner, other._inner); } -/// Get the time zone transition +/// Returns the first instant after or before this instant at which the time zone's UTC offset changes, or null if none. +/// See [MDN Temporal.ZonedDateTime.prototype.getTimeZoneTransition()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/getTimeZoneTransition) pub fn getTimeZoneTransition(self: ZonedDateTime, direction: enum { next, previous }) !?ZonedDateTime { const dir = switch (direction) { .next => abi.c.TransitionDirection_Next, @@ -131,63 +177,74 @@ pub fn getTimeZoneTransition(self: ZonedDateTime, direction: enum { next, previo return null; } -/// Round to the given options +/// Returns a new ZonedDateTime rounded to the given unit and options. +/// See [MDN Temporal.ZonedDateTime.prototype.round()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/round) pub fn round(self: ZonedDateTime, options: RoundOptions) !ZonedDateTime { return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_round(self._inner, abi.to.roundingOpts(options))); } -/// Calculate duration since another ZonedDateTime +/// Returns the duration from another ZonedDateTime to this one. +/// See [MDN Temporal.ZonedDateTime.prototype.since()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/since) pub fn since(self: ZonedDateTime, other: ZonedDateTime, settings: DifferenceSettings) !Duration { const ptr = try abi.extractResult(abi.c.temporal_rs_ZonedDateTime_since(self._inner, other._inner, abi.to.diffsettings(settings))); return .{ ._inner = ptr }; } -/// Get the start of the day +/// Returns a ZonedDateTime representing the start of the day in the time zone. +/// See [MDN Temporal.ZonedDateTime.prototype.startOfDay()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/startOfDay) pub fn startOfDay(self: ZonedDateTime) !ZonedDateTime { return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_start_of_day(self._inner)); } -/// Subtract a duration +/// Returns a new ZonedDateTime moved backward by the given duration. +/// See [MDN Temporal.ZonedDateTime.prototype.subtract()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/subtract) pub fn subtract(self: ZonedDateTime, duration: Duration) !ZonedDateTime { const overflow_opt = abi.toOption(abi.c.ArithmeticOverflow_option, null); return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_subtract(self._inner, duration._inner, overflow_opt)); } -/// Convert to Instant +/// Returns a new Instant representing the same instant as this ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.toInstant()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toInstant) pub fn toInstant(self: ZonedDateTime) !Instant { const instant_ptr = abi.c.temporal_rs_ZonedDateTime_to_instant(self._inner) orelse return error.TemporalError; return .{ ._inner = instant_ptr }; } -/// Convert to JSON string (ISO 8601 format) +/// Returns a string representing this ZonedDateTime in RFC 9557 format (ISO 8601 with time zone). +/// See [MDN Temporal.ZonedDateTime.prototype.toJSON()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toJSON) pub fn toJSON(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } -/// Convert to locale string (placeholder - returns ISO string) +/// Returns a language-sensitive string representation of this ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.toLocaleString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toLocaleString) pub fn toLocaleString(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { return self.toString(allocator, .{}); } -/// Convert to PlainDate +/// Returns a PlainDate representing the date portion of this ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.toPlainDate()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toPlainDate) pub fn toPlainDate(self: ZonedDateTime) !PlainDate { const ptr = abi.c.temporal_rs_ZonedDateTime_to_plain_date(self._inner) orelse return error.TemporalError; return .{ ._inner = ptr }; } -/// Convert to PlainDateTime +/// Returns a PlainDateTime representing the date and time portions of this ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.toPlainDateTime()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toPlainDateTime) pub fn toPlainDateTime(self: ZonedDateTime) !PlainDateTime { const ptr = abi.c.temporal_rs_ZonedDateTime_to_plain_datetime(self._inner) orelse return error.TemporalError; return .{ ._inner = ptr }; } -/// Convert to PlainTime +/// Returns a PlainTime representing the time portion of this ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.toPlainTime()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toPlainTime) pub fn toPlainTime(self: ZonedDateTime) !PlainTime { const ptr = abi.c.temporal_rs_ZonedDateTime_to_plain_time(self._inner) orelse return error.TemporalError; return .{ ._inner = ptr }; } -/// Convert to string with options +/// Returns a string representing this ZonedDateTime in RFC 9557 format, with options for formatting. +/// See [MDN Temporal.ZonedDateTime.prototype.toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/toString) pub fn toString(self: ZonedDateTime, allocator: std.mem.Allocator, opts: ToStringOptions) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -205,18 +262,21 @@ pub fn toString(self: ZonedDateTime, allocator: std.mem.Allocator, opts: ToStrin return try write.toOwnedSlice(); } -/// Calculate duration until another ZonedDateTime +/// Returns the duration from this ZonedDateTime to another. +/// See [MDN Temporal.ZonedDateTime.prototype.until()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/until) pub fn until(self: ZonedDateTime, other: ZonedDateTime, settings: DifferenceSettings) !Duration { const ptr = try abi.extractResult(abi.c.temporal_rs_ZonedDateTime_until(self._inner, other._inner, abi.to.diffsettings(settings))); return .{ ._inner = ptr }; } -/// valueOf() is not supported for ZonedDateTime +/// Throws an error; valueOf() is not supported for ZonedDateTime. +/// See [MDN Temporal.ZonedDateTime.prototype.valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/valueOf) pub fn valueOf(_: ZonedDateTime) !void { return error.ValueOfNotSupported; } -/// Create a new ZonedDateTime with some fields changed +/// Returns a new ZonedDateTime with some fields replaced by new values. +/// See [MDN Temporal.ZonedDateTime.prototype.with()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/with) pub fn with(self: ZonedDateTime, allocator: std.mem.Allocator, fields: anytype) !ZonedDateTime { _ = allocator; _ = fields; @@ -224,7 +284,8 @@ pub fn with(self: ZonedDateTime, allocator: std.mem.Allocator, fields: anytype) return error.Todo; // Need PartialZonedDateTime mapping } -/// Create a new ZonedDateTime with a different calendar +/// Returns a new ZonedDateTime interpreted in the new calendar system. +/// See [MDN Temporal.ZonedDateTime.prototype.withCalendar()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/withCalendar) pub fn withCalendar(self: ZonedDateTime, calendar: []const u8) !ZonedDateTime { const cal_view = abi.toDiplomatStringView(calendar); const cal_result = abi.c.temporal_rs_AnyCalendarKind_parse_temporal_calendar_string(cal_view); @@ -233,55 +294,77 @@ pub fn withCalendar(self: ZonedDateTime, calendar: []const u8) !ZonedDateTime { return .{ ._inner = ptr, .calendar_id = calendar }; } -/// Create a new ZonedDateTime with a different time +/// Returns a new ZonedDateTime with the time part replaced by the new time. +/// See [MDN Temporal.ZonedDateTime.prototype.withPlainTime()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/withPlainTime) pub fn withPlainTime(self: ZonedDateTime, time: ?PlainTime) !ZonedDateTime { const time_ptr = if (time) |tt| tt._inner else null; return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_with_plain_time(self._inner, time_ptr)); } -/// Create a new ZonedDateTime with a different time zone +/// Returns a new ZonedDateTime representing the same instant in a new time zone. +/// See [MDN Temporal.ZonedDateTime.prototype.withTimeZone()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/withTimeZone) pub fn withTimeZone(self: ZonedDateTime, time_zone: TimeZone) !ZonedDateTime { return wrapZonedDateTime(abi.c.temporal_rs_ZonedDateTime_with_timezone(self._inner, abi.to.toTimeZone(time_zone))); } // Property accessors +/// Returns the calendar identifier used to interpret the internal ISO 8601 date. +/// See [MDN Temporal.ZonedDateTime.prototype.calendarId](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/calendarId) pub fn calendarId(self: ZonedDateTime) []const u8 { return self.calendar_id; } +/// Returns the 1-based day index in the month of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.day](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/day) pub fn day(self: ZonedDateTime) u8 { return abi.c.temporal_rs_ZonedDateTime_day(self._inner); } +/// Returns the 1-based day index in the week of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.dayOfWeek](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/dayOfWeek) pub fn dayOfWeek(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_day_of_week(self._inner); } +/// Returns the 1-based day index in the year of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.dayOfYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/dayOfYear) pub fn dayOfYear(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_day_of_year(self._inner); } +/// Returns the number of days in the month of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.daysInMonth](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/daysInMonth) pub fn daysInMonth(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_days_in_month(self._inner); } +/// Returns the number of days in the week of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.daysInWeek](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/daysInWeek) pub fn daysInWeek(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_days_in_week(self._inner); } +/// Returns the number of days in the year of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.daysInYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/daysInYear) pub fn daysInYear(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_days_in_year(self._inner); } +/// Returns the number of milliseconds since the Unix epoch to this instant. +/// See [MDN Temporal.ZonedDateTime.prototype.epochMilliseconds](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/epochMilliseconds) pub fn epochMilliseconds(self: ZonedDateTime) i64 { return abi.c.temporal_rs_ZonedDateTime_epoch_milliseconds(self._inner); } +/// Returns the number of nanoseconds since the Unix epoch to this instant. +/// See [MDN Temporal.ZonedDateTime.prototype.epochNanoseconds](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/epochNanoseconds) pub fn epochNanoseconds(self: ZonedDateTime) i128 { const parts = abi.c.temporal_rs_ZonedDateTime_epoch_nanoseconds(self._inner); return abi.fromI128Nanoseconds(parts); } +/// Returns the calendar-specific era of this date, or null if not applicable. +/// See [MDN Temporal.ZonedDateTime.prototype.era](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/era) pub fn era(self: ZonedDateTime, allocator: std.mem.Allocator) !?[]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -294,40 +377,58 @@ pub fn era(self: ZonedDateTime, allocator: std.mem.Allocator) !?[]u8 { return result; } +/// Returns the year of this date within the era, or null if not applicable. +/// See [MDN Temporal.ZonedDateTime.prototype.eraYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/eraYear) pub fn eraYear(self: ZonedDateTime) ?i32 { const result = abi.c.temporal_rs_ZonedDateTime_era_year(self._inner); return abi.fromOption(result); } +/// Returns the hour component of this time (0-23). +/// See [MDN Temporal.ZonedDateTime.prototype.hour](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/hour) pub fn hour(self: ZonedDateTime) u8 { return abi.c.temporal_rs_ZonedDateTime_hour(self._inner); } +/// Returns the number of hours in the day of this date in the time zone. +/// See [MDN Temporal.ZonedDateTime.prototype.hoursInDay](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/hoursInDay) pub fn hoursInDay(self: ZonedDateTime) !f64 { const result = abi.c.temporal_rs_ZonedDateTime_hours_in_day(self._inner); return try abi.extractResult(result); } +/// Returns true if this date is in a leap year. +/// See [MDN Temporal.ZonedDateTime.prototype.inLeapYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/inLeapYear) pub fn inLeapYear(self: ZonedDateTime) bool { return abi.c.temporal_rs_ZonedDateTime_in_leap_year(self._inner); } +/// Returns the microsecond component of this time (0-999). +/// See [MDN Temporal.ZonedDateTime.prototype.microsecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/microsecond) pub fn microsecond(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_microsecond(self._inner); } +/// Returns the millisecond component of this time (0-999). +/// See [MDN Temporal.ZonedDateTime.prototype.millisecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/millisecond) pub fn millisecond(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_millisecond(self._inner); } +/// Returns the minute component of this time (0-59). +/// See [MDN Temporal.ZonedDateTime.prototype.minute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/minute) pub fn minute(self: ZonedDateTime) u8 { return abi.c.temporal_rs_ZonedDateTime_minute(self._inner); } +/// Returns the 1-based month index in the year of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.month](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/month) pub fn month(self: ZonedDateTime) u8 { return abi.c.temporal_rs_ZonedDateTime_month(self._inner); } +/// Returns the calendar-specific string representing the month of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.monthCode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/monthCode) pub fn monthCode(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -335,14 +436,20 @@ pub fn monthCode(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { return try write.toOwnedSlice(); } +/// Returns the number of months in the year of this date. +/// See [MDN Temporal.ZonedDateTime.prototype.monthsInYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/monthsInYear) pub fn monthsInYear(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_months_in_year(self._inner); } +/// Returns the nanosecond component of this time (0-999). +/// See [MDN Temporal.ZonedDateTime.prototype.nanosecond](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/nanosecond) pub fn nanosecond(self: ZonedDateTime) u16 { return abi.c.temporal_rs_ZonedDateTime_nanosecond(self._inner); } +/// Returns the offset used to interpret the internal instant, as a string (±HH:mm). +/// See [MDN Temporal.ZonedDateTime.prototype.offset](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/offset) pub fn offset(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { var write = abi.DiplomatWrite.init(allocator); defer write.deinit(); @@ -351,14 +458,20 @@ pub fn offset(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { return try write.toOwnedSlice(); } +/// Returns the offset used to interpret the internal instant, as a number of nanoseconds. +/// See [MDN Temporal.ZonedDateTime.prototype.offsetNanoseconds](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/offsetNanoseconds) pub fn offsetNanoseconds(self: ZonedDateTime) i64 { return abi.c.temporal_rs_ZonedDateTime_offset_nanoseconds(self._inner); } +/// Returns the second component of this time (0-59). +/// See [MDN Temporal.ZonedDateTime.prototype.second](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/second) pub fn second(self: ZonedDateTime) u8 { return abi.c.temporal_rs_ZonedDateTime_second(self._inner); } +/// Returns the time zone identifier used to interpret the internal instant. +/// See [MDN Temporal.ZonedDateTime.prototype.timeZoneId](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/timeZoneId) pub fn timeZoneId(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { const tz = abi.c.temporal_rs_ZonedDateTime_timezone(self._inner); var write = abi.DiplomatWrite.init(allocator); @@ -369,27 +482,33 @@ pub fn timeZoneId(self: ZonedDateTime, allocator: std.mem.Allocator) ![]u8 { return try write.toOwnedSlice(); } +/// Returns the 1-based week index in the year of this date, or null if not defined. +/// See [MDN Temporal.ZonedDateTime.prototype.weekOfYear](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/weekOfYear) pub fn weekOfYear(self: ZonedDateTime) ?u8 { const result = abi.c.temporal_rs_ZonedDateTime_week_of_year(self._inner); return abi.fromOption(result); } +/// Returns the year of this date relative to the calendar's epoch. +/// See [MDN Temporal.ZonedDateTime.prototype.year](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/year) pub fn year(self: ZonedDateTime) i32 { return abi.c.temporal_rs_ZonedDateTime_year(self._inner); } +/// Returns the year to be paired with the weekOfYear of this date, or null if not defined. +/// See [MDN Temporal.ZonedDateTime.prototype.yearOfWeek](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/yearOfWeek) pub fn yearOfWeek(self: ZonedDateTime) ?i32 { const result = abi.c.temporal_rs_ZonedDateTime_year_of_week(self._inner); return abi.fromOption(result); } -/// Clone this ZonedDateTime +/// Returns a clone of this ZonedDateTime instance. pub fn clone(self: ZonedDateTime) ZonedDateTime { const ptr = abi.c.temporal_rs_ZonedDateTime_clone(self._inner); return .{ ._inner = ptr }; } -/// Free the ZonedDateTime +/// Frees the resources associated with this ZonedDateTime instance. pub fn deinit(self: ZonedDateTime) void { abi.c.temporal_rs_ZonedDateTime_destroy(self._inner); } diff --git a/src/root.zig b/src/root.zig index 5db1b6c..d7b0e94 100644 --- a/src/root.zig +++ b/src/root.zig @@ -1,15 +1,54 @@ -pub const Duration = @import("Duration.zig"); -pub const Instant = @import("Instant.zig"); -pub const Now = @import("Now.zig"); -pub const PlainDate = @import("PlainDate.zig"); -pub const PlainDateTime = @import("PlainDateTime.zig"); -pub const PlainMonthDay = @import("PlainMonthDay.zig"); -pub const PlainTime = @import("PlainTime.zig"); -pub const PlainYearMonth = @import("PlainYearMonth.zig"); -pub const ZonedDateTime = @import("ZonedDateTime.zig"); - +// The `Temporal` namespace contains date and time related objects and functions, providing a modern alternative to the existing `Date` object in JavaScript. const Temporal = @This(); +/// The `Temporal.Duration` object represents a difference between two time points, which can be used in date/time arithmetic. +/// It is fundamentally represented as a combination of years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds values. +/// +/// - [MDN Temporal.Duration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration) +pub const Duration = @import("Duration.zig"); + +/// The `Temporal.Instant` object represents a unique point in time, with nanosecond precision. +/// It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system. +/// +/// - [MDN Temporal.Instant](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant) +pub const Instant = @import("Instant.zig"); + +/// The `Temporal.Now` namespace object contains static methods for getting the current time in various formats. +/// All properties and methods are static. +/// +/// - [MDN Temporal.Now](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Now) +pub const Now = @import("Now.zig"); + +/// The `Temporal.PlainDate` object represents a calendar date (year, month, day) with no time or time zone. +/// +/// - [MDN Temporal.PlainDate](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate) +pub const PlainDate = @import("PlainDate.zig"); + +/// The `Temporal.PlainDateTime` object represents a calendar date and wall-clock time, but no time zone or offset. +/// +/// - [MDN Temporal.PlainDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime) +pub const PlainDateTime = @import("PlainDateTime.zig"); + +/// The `Temporal.PlainMonthDay` object represents a month and day in a calendar, with no year or time. +/// +/// - [MDN Temporal.PlainMonthDay](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainMonthDay) +pub const PlainMonthDay = @import("PlainMonthDay.zig"); + +/// The `Temporal.PlainTime` object represents a wall-clock time, with no date or time zone. +/// +/// - [MDN Temporal.PlainTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime) +pub const PlainTime = @import("PlainTime.zig"); + +/// The `Temporal.PlainYearMonth` object represents a particular month in a specific year, with no day or time. +/// +/// - [MDN Temporal.PlainYearMonth](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainYearMonth) +pub const PlainYearMonth = @import("PlainYearMonth.zig"); + +/// The `Temporal.ZonedDateTime` object represents an exact time, including a time zone and calendar. +/// +/// - [MDN Temporal.ZonedDateTime](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime) +pub const ZonedDateTime = @import("ZonedDateTime.zig"); + test Temporal { const std = @import("std"); _ = @import("abi.zig"); diff --git a/src/temporal.zig b/src/temporal.zig index 3738efe..a463d8e 100644 --- a/src/temporal.zig +++ b/src/temporal.zig @@ -1,4 +1,10 @@ -/// Time unit for Temporal operations. +/// # Temporal Types and Utilities +/// +/// This file defines core types and options used throughout the Temporal API implementation. +/// +/// - [MDN Temporal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) +/// ## Unit +/// Time unit for Temporal operations (e.g., nanosecond, second, day, year). /// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal pub const Unit = enum { auto, @@ -14,6 +20,7 @@ pub const Unit = enum { year, }; +/// ## RoundingMode /// Rounding mode for Temporal operations. /// See: https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers pub const RoundingMode = enum { @@ -37,6 +44,7 @@ pub const RoundingMode = enum { half_even, }; +/// ## Sign /// Sign of a duration or time value. pub const Sign = enum { positive, @@ -44,8 +52,10 @@ pub const Sign = enum { negative, }; -/// Options for rounding operations (Instant.round, Duration.round, etc.). -/// MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round +/// ## RoundingOptions +/// Options for rounding operations (e.g., Instant.round, Duration.round). +/// +/// - [MDN: Duration.round](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/round) pub const RoundingOptions = struct { largest_unit: ?Unit = null, smallest_unit: ?Unit = null, @@ -53,8 +63,10 @@ pub const RoundingOptions = struct { rounding_increment: ?u32 = null, }; +/// ## DifferenceSettings /// Options for computing differences between instants. -/// MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/until +/// +/// - [MDN: Instant.until](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant/until) pub const DifferenceSettings = struct { largest_unit: ?Unit = null, smallest_unit: ?Unit = null, @@ -62,18 +74,22 @@ pub const DifferenceSettings = struct { rounding_increment: ?u32 = null, }; +/// ## ToStringRoundingOptions /// Options for Duration.toString() formatting. -/// MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/toString +/// +/// - [MDN: Duration.toString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/toString) pub const ToStringRoundingOptions = struct { fractional_second_digits: ?u8 = null, smallest_unit: ?Unit = null, rounding_mode: ?RoundingMode = null, }; -/// Time zone identifier for Temporal operations +/// ## TimeZone +/// Time zone identifier for Temporal operations. pub const TimeZone = struct { _inner: abi.c.TimeZone, + /// Initialize a TimeZone from an identifier string. pub fn init(id: []const u8) TimeZone { const view = abi.toDiplomatStringView(id); return .{ ._inner = .{ .id = view } };