parseUnitFromZoned

Signature

parseUnitFromZoned(value: string, unit: ZonedParseUnit, optionsArg?: { weekStartsOn?: "monday" | "sunday"; }): string

Return the requested unit value from an ISO 8601 zoned datetime string.

• Valid units: “year”, “month”, “week”, “day”, “dayOfWeek”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”, “timeZone”.
• Uses Temporal.ZonedDateTime.from to parse.
• unit accepts the singular or plural name of a Temporal unit ("hour" or "hours"), as Temporal does; "dayOfWeek" has no plural.
• Returns "" for invalid input.
• The "year" unit is written as Temporal writes a year: four digits ("2024", "0005"), or a sign and six digits outside 0000–9999 ("+010000", "-000005").

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
unit	ZonedParseUnit	unit to extract

Options

optionsArg

optional setting for the week’s first day; a non-object value (such as null) is invalid

Option	Type	Default	Description
weekStartsOn?	"monday" | "sunday"	"monday"	The first day of the week, which sets how the "week" unit is numbered. "monday" gives the ISO 8601 week number, where week 1 holds the year’s first Thursday; "sunday" gives the UTS #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other value returns "", whatever the unit.

Returns

string representation of the requested unit or "" when invalid

Types

ZonedParseUnit

Units supported by parseUnitFromZoned when extracting a value from a zoned ISO string. Includes timeZone for reading the zone identifier. Each Temporal unit is also accepted in its plural form ("months"), as Temporal accepts.

import type { ZonedParseUnit } from "@northguild/gmt";

"dayOfWeek" | SmallestUnit<"year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "timeZone"

Examples

import { parseUnitFromZoned } from "@northguild/gmt/zoned/parse";

parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"

value

output

 

Source

zoned/parse/parseUnitFromZoned.ts