std.time Package

Function Description

The time package provides time-related types, including date and time, time interval, monotonic time, and time zone, and provides functionality of calculation and comparison.

Time String Formats

Parsing time from a string has the following requirements:

The string must contain the information about the specific year, month, and day, for example, year (y) + month (M) and day (d), or year (y) and day of the year (D).
If information about the hour, minute, and second is not contained, the default value 0 is used. If information about the time zone is not contained, the default value of TimeZone.Local is used.
It is not allowed to assign a value twice to the formats represented by the same letter. For example, the year (y) format cannot be assigned a value twice. The O and Z formats cannot be used together to indicate the time zone.
The format of some other letters is used as auxiliary information for verification. For example, when "2023-04-24-Mon" is parsed using the "yyyy-MM-dd-www" format, the correctness of "Mon" is verified.

Meanings of Letters

Letter	Meaning
a	Daytime
y	Year
Y	Week-based year
M	Month
d	Day
D	Number of days in a year
w	Number of days in weeks
W	ISO 8601-compliant week date
h	Hour in 12-hour clock format
H	Hour in 24-hour clock format
m	Minutes
s	Seconds
S	Part less than one second
z	Time zone name and time zone ID
Z	Zero hour offset
O	Time zone offset
G	Calendar era

The following describes the rules of mapping of these letters.

Rules

Daytime

The valid number is 1, indicating morning or afternoon. The value is permanently AM or PM.

Year

Number of Letters	Parsing	Output
1, 3, or 4	A year in four digits, for example, 2023 and 0001.	A year in at least four digits, for example, 2023, 0001, and 99999. Zeros are added if there are less than four digits.
2	A year in two digits, for example, 23 and 69. If xx is greater than or equal to 69, the year is parsed as 19xx; otherwise, the year is parsed as 20xx. The same rule applies to negative numbers.	A year in two or more digits, for example, 23 and 69. The output of [1969, 1999] is [69, 99], and the output of [2000, 2068] is [00, 68]. The same rule applies to negative numbers. In other cases, the output contains at least four digits. Zeros are added if there are less than four digits.
5–9	A year in the corresponding number of digits.	A year in the corresponding number of digits. Zeros are added if the number of digits is less than the expected.

Month

Number of Letters	Parsing	Output
1	One to two digits, for example, 1, 01, and 11.	One to two digits, for example, 1 and 11.
2	Two digits, for example, 01 and 11.	Two digits, for example, 01 and 11.
3	An abbreviation of month, for example, Jan and Dec.	An abbreviation of month, for example, Jan and Dec.
4	A full name of month, for example, January and December.	A full name of month, for example, January and December.

Numeric Value

The representing range of data of different number types varies according to actual values.

Number of Letters	Parsing	Output
1	One to two digits, for example, 1, 01, and 11.	One to two digits, for example, 1 and 11.
2	Two digits, for example, 01 and 11.	Two digits, for example, 01 and 11.

Fractional Second

Number of Letters	Parsing	Output
1	Three digits, for example, 001 and 123 as milliseconds.	Three digits, for example, 001 and 123 as milliseconds.
2	Six digits, for example, 000001 and 123456 as microseconds.	Six digits, for example, 000001 and 123456 as microseconds.
3	Nine digits, for example, 000000001 and 123456789 as nanoseconds.	Nine digits, for example, 000000001 and 123456789 as nanoseconds.

Time Zone Offset

Number of Letters	Parsing	Output
1	Formats such as +08 and -08.	Formats such as +08 and -08. If not in full hours, the offset is truncated.
2	Formats such as +08:00 and -08:59.	Format such as +08:00 and -08:59. If not in full minutes, the offset is truncated.
3	Formats such as +08:00:00 and -08:59:59.	Formats such as +08:00:00 and -08:59:59.
4	Formats such as +08:00:00 and -08:59:59.	Formats such as case2 and case3. If the offset is 0, Z is output.

Time zone name and time zone ID

Number of Letters	Parsing	Output
1, 2, or 3	Formats such as CST and GMT.	Formats such as CST and GMT.
4	Time zone ID, in the format such as Asia/Shanghai.	Time zone ID, in the format such as Asia/Shanghai.

Zero hour offset

Number of Letters	Parsing	Output
1	Formats such as GMT+0 and GMT+10.	Formats such as GMT+0 and GMT+10.
2	Formats such as GMT+00:00 and GMT+10:00.	Formats such as GMT+00:00 and GMT+10:00.
3	Formats such as GMT+00:00:00 and GMT+10:00:00.	Formats such as GMT+00:00:00 and GMT+10:00:00.
4	Format with the number of 2 or 3.	Format with the number of 2 or 3.

Number of Days in a Year

Number of Letters	Parsing	Output
1	One to three digits, for example, 1, 01, and 001.	One to three digits, for example, 1, 12, and 123.
2	Two to three digits, for example, 01 and 001.	Two to three digits, for example, 001, 012, and 123.

Number of Days in Weeks

Number of Letters	Parsing	Output
1	One digit, for example, 0 and 6. 0 indicates Sunday, and the others indicate Monday to Saturday.	One digit, for example, 0 and 6. 0 indicates Sunday, and the others indicate Monday to Saturday.
2	Two digits, for example, 00 and 06. 00 indicates Sunday, and the others indicate Monday to Saturday.	Two digits, for example, 00 and 06. 00 indicates Sunday, and the others indicate Monday to Saturday.
3	An abbreviation of week, for example, Sun and Sat.	An abbreviation of week, for example, Sun and Sat.
4	A full name of week, for example, Sunday and Saturday.	A full name of week, for example, Sunday and Saturday.

Calendar Era

Number of Letters	Parsing	Output
1	A.	A.
2	AD.	AD.
3	Anno Domini.	Anno Domini.

API List

Interface

Name	Description
DurationExtension	Returns a multiplication with the new `Duration` instance as the product when extending the `Duration` instance as a right operand.

Class

Name	Description
DateTimeFormat	Provides time formats for parsing and generating DateTime.
TimeZone	Indicates the time zone. It records the time offsets of a region relative to the zero time zone at different times. It provides functionality such as loading a time zone from the system and customizing a time zone.

Enumeration

Name	Description
DayOfWeek	Indicates a day of a week. It provides functionality of `Int64` type conversion, equality judgment, and obtaining the string representation of enumerated values.
Month	Indicates a month, that is, a month in a year. It provides functionality of Int64 type conversion and calculation, equality judgment, and obtaining the string representation of enumerated values.

Struct

Name	Description
DateTime	Indicates a date-time, which is a time type describing a point of time. It provides functionality such as time zone-based date-time reading, calculation, comparison, and conversion, as well as serialization and deserialization.
Duration	Indicates a time interval, which is a time type describing a period of time. It provides common static instances and functionality such as calculation and comparison.
MonoTime	Indicates monotonic time, which is a time type used to measure the elapsed time. Similar to an ever-running stopwatch, it provides functionality such as obtaining current time, calculation, and comparison.

Exception Class

Name	Description
InvalidDataException	Indicates an exception that occurs during time zone loading.
TimeParseException	Indicates an exception that occurs during time string parsing.