blob: 7f81e98446f8395e6201b3e4801fa82933123bd7 [file] [log] [blame]
// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.intl;
using zx;
type TimeZonesError = flexible enum : int32 {
/// An internal error has occurred within the service.
/// The requested time zone ID is invalid.
/// The provided date is out of range or invalid.
/// During a transition from daylight savings to standard time (when the clock is turned back), a
/// civil time can correspond to two possible absolute times. This setting determines which of those
/// times should be assumed during the conversion to absolute time.
type RepeatedTimeConversion = flexible enum : int32 {
/// Returns the wall clock time before the transition.
/// For example, in "America/New_York" on the night of the fall transition to standard time,
/// `1:30 AM` is interpreted as `01:30-04:00` (EDT), which is `05:30Z`.
/// During a transition from standard time to daylight savings time (when the clock is turned
/// forward), a span of civil times is skipped (usually one hour). This setting determines how
/// invalid civil times within this span should be treated.
type SkippedTimeConversion = flexible enum : int32 {
/// Returns `TimeZonesError::INVALID_DATE` when trying to convert a skipped civil time.
/// Returns the closest valid time after the requested time.
/// For example, in "America/New_York" on the night of the spring transition to daylight savings
/// time, `2:30 AM` doesn't exist, so the next valid time, `3:00 AM` (EDT) is returned instead.
/// Options for `TimeZones.CivilToAbsoluteTime`.
type CivilToAbsoluteTimeOptions = table {
/// Optional setting for handling repeated times during backward daylight savings time
/// transitions.
1: repeated_time_conversion RepeatedTimeConversion;
/// Optional setting for handling skipped times during forward daylight savings time
/// transitions.
/// Default: `NEXT_VALID_TIME`.
2: skipped_time_conversion SkippedTimeConversion;
/// Provides information about time zones and offers date-time conversion methods.
/// TODO( Add time zone info methods, including offsets from UTC.
protocol TimeZones {
/// Converts the given absolute time to a civil date and time in the given time zone, using the
/// Gregorian calendar.
AbsoluteToCivilTime(struct {
/// The time zone in which to calculate a civil date and time.
time_zone_id TimeZoneId;
/// The number of nanoseconds since the Unix epoch.
/// For example, `at_time == 0` corresponds to 1970-01-01T00:00:00.000000000Z.
absolute_time zx.time;
}) -> (struct {
civil_time CivilTime;
}) error TimeZonesError;
/// Converts the given civil date and time in the given time zone to nanoseconds since the Unix
/// epoch.
CivilToAbsoluteTime(struct {
/// The civil date and time to convert.
/// Note that `civil_time.weekday` and `civil_time.year_day` may be omitted for this method.
/// If present, they must be consistent with the other fields.
civil_time CivilTime;
/// Conversion options for civil times that cross a daylight savings transition.
options CivilToAbsoluteTimeOptions;
}) -> (struct {
absolute_time zx.time;
}) error TimeZonesError;
/// Retrieves details about a time zone at a specified one.
GetTimeZoneInfo(struct {
/// The time zone ID for which to retrieve information.
time_zone_id TimeZoneId;
/// The date and time at which to calculate values, in nanoseconds since the Unix epoch.
/// For example, `at_time == 0` corresponds to 1970-01-01T00:00:00.000000000Z.
at_time zx.time;
}) -> (struct {
time_zone_info TimeZoneInfo;
}) error TimeZonesError;
/// Describes a time on a civil calendar (Gregorian), with nanosecond precision. This is roughly
/// equivalent to the `tm` struct in `time.h` in the C standard library, and is intended as a
/// structured intermediate format for printing or parsing dates.
type CivilTime = table {
/// Year, in the closed range `[1678, 2262]`.
1: year uint16;
/// Month of the year.
2: month Month;
/// Day of the month, in the closed range `[1, 31]`.
3: day uint8;
/// Hour of the day, in the closed range `[0, 23]`.
4: hour uint8;
/// Minute of the hour, in the closed range `[0, 59]`.
5: minute uint8;
/// Second of the minute, in the closed range `[0, 59]`.
/// (Note that Fuchsia does not currently calculate leap seconds when converting dates.)
6: second uint8;
/// Nanosecond, in the closed range `[0, 999_999_999]`.
7: nanos uint64;
/// Day of the week.
8: weekday DayOfWeek;
/// Day of the year, in the closed range `[0, 365]`.
9: year_day uint16;
/// The time zone corresponding to this time. If omitted, the default is UTC.
10: time_zone_id TimeZoneId;
/// Describes a Time Zone's properties at a particular moment in time.
/// TODO( Additional fields with a breakdown of offsets and DST status.
type TimeZoneInfo = table {
/// The time zone's IANA ID.
1: id TimeZoneId;
/// The total offset (including Daylight Savings, if the time zone is in Daylight Savings Time)
/// from UTC at the queried time (`at_time`). If the time zone is ahead of UTC, this will be a
/// positive value; if behind UTC, a negative value.
2: total_offset_at_time zx.duration;
/// Indicates whether the time zone is in Daylight Savings Time at the queried time
/// (`at_time`).
3: in_dst_at_time bool;