0
# String Parsing
1

2
ISO 8601 string parsing for dates, times, durations, and timezone-aware datetimes with comprehensive format support.
3

4
## Capabilities
5

6
### Date Parsing
7

8
Parse ISO 8601 date strings into CalendarDate objects.
9

10
```typescript { .api }
11
/**
12
 * Parses an ISO 8601 date string, with no time components
13
 * @param value - ISO 8601 date string (e.g., "2024-03-15")
14
 * @returns CalendarDate object representing the parsed date
15
 * @throws Error if string format is invalid
16
 */
17
function parseDate(value: string): CalendarDate;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { parseDate } from "@internationalized/date";
24

25
// Basic date parsing
26
const date1 = parseDate("2024-03-15"); // March 15, 2024
27
const date2 = parseDate("2024-12-31"); // December 31, 2024
28

29
// Extended year format (6 digits)
30
const ancientDate = parseDate("+001985-01-01"); // Year 1985
31
const futureDate = parseDate("+012024-06-15"); // Year 12024
32

33
// Negative years (BCE)
34
const bceDate = parseDate("-000100-07-20"); // 100 BCE
35
```
36

37
### Time Parsing
38

39
Parse ISO 8601 time strings into Time objects.
40

41
```typescript { .api }
42
/**
43
 * Parses an ISO 8601 time string
44
 * @param value - ISO 8601 time string (e.g., "14:30:00", "09:15:30.750")
45
 * @returns Time object representing the parsed time
46
 * @throws Error if string format is invalid
47
 */
48
function parseTime(value: string): Time;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { parseTime } from "@internationalized/date";
55

56
// Basic time formats
57
const time1 = parseTime("14:30"); // 2:30 PM (seconds and ms default to 0)
58
const time2 = parseTime("14:30:00"); // 2:30:00 PM
59
const time3 = parseTime("14:30:45"); // 2:30:45 PM
60

61
// With milliseconds
62
const preciseTime = parseTime("14:30:45.750"); // 2:30:45.750 PM
63
const moreMs = parseTime("09:15:30.123456"); // 9:15:30.123 AM (truncated to ms)
64

65
// Edge cases
66
const midnight = parseTime("00:00:00"); // Midnight
67
const almostMidnight = parseTime("23:59:59.999"); // 11:59:59.999 PM
68
```
69

70
### DateTime Parsing
71

72
Parse ISO 8601 datetime strings into CalendarDateTime objects.
73

74
```typescript { .api }
75
/**
76
 * Parses an ISO 8601 datetime string
77
 * @param value - ISO 8601 datetime string (e.g., "2024-03-15T14:30:00")
78
 * @returns CalendarDateTime object representing the parsed datetime
79
 * @throws Error if string format is invalid
80
 */
81
function parseDateTime(value: string): CalendarDateTime;
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import { parseDateTime } from "@internationalized/date";
88

89
// Basic datetime formats
90
const dt1 = parseDateTime("2024-03-15T14:30:00"); // March 15, 2024 at 2:30 PM
91
const dt2 = parseDateTime("2024-03-15T14:30"); // Seconds default to 0
92
const dt3 = parseDateTime("2024-03-15T14"); // Minutes and seconds default to 0
93

94
// With milliseconds
95
const preciseDateTime = parseDateTime("2024-03-15T14:30:45.750");
96

97
// Extended formats
98
const extendedYear = parseDateTime("+012024-12-31T23:59:59");
99
const bceDateTime = parseDateTime("-001000-06-15T12:00:00");
100
```
101

102
### Absolute Time Parsing
103

104
Parse ISO 8601 absolute time strings with UTC offsets into ZonedDateTime objects.
105

106
```typescript { .api }
107
/**
108
 * Parses an ISO 8601 absolute time with UTC offset
109
 * @param value - ISO 8601 string with UTC offset (e.g., "2024-03-15T14:30:00Z", "2024-03-15T14:30:00-05:00")
110
 * @param timeZone - IANA timezone identifier for the resulting ZonedDateTime
111
 * @returns ZonedDateTime representing the parsed absolute time
112
 * @throws Error if string format is invalid
113
 */
114
function parseAbsolute(value: string, timeZone: string): ZonedDateTime;
115

116
/**
117
 * Parses an ISO 8601 absolute time to local timezone
118
 * @param value - ISO 8601 string with UTC offset
119
 * @returns ZonedDateTime in user's local timezone
120
 * @throws Error if string format is invalid
121
 */
122
function parseAbsoluteToLocal(value: string): ZonedDateTime;
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { parseAbsolute, parseAbsoluteToLocal } from "@internationalized/date";
129

130
// UTC time (Z suffix)
131
const utcTime = parseAbsolute("2024-03-15T14:30:00Z", "America/New_York");
132

133
// With timezone offsets
134
const withOffset1 = parseAbsolute("2024-03-15T14:30:00-05:00", "UTC");
135
const withOffset2 = parseAbsolute("2024-03-15T14:30:00+09:00", "Asia/Tokyo");
136

137
// Different offset formats
138
const colonOffset = parseAbsolute("2024-03-15T14:30:00-05:00", "America/New_York");
139
const noColonOffset = parseAbsolute("2024-03-15T14:30:00-0500", "America/New_York");
140

141
// Parse to local timezone
142
const localTime = parseAbsoluteToLocal("2024-03-15T14:30:00Z");
143
const localWithOffset = parseAbsoluteToLocal("2024-03-15T14:30:00-05:00");
144
```
145

146
### Zoned DateTime Parsing
147

148
Parse ISO 8601 strings with timezone identifiers into ZonedDateTime objects.
149

150
```typescript { .api }
151
/**
152
 * Parses an ISO 8601 zoned datetime string
153
 * @param value - ISO 8601 string with timezone (e.g., "2024-03-15T14:30:00[America/New_York]")
154
 * @param disambiguation - How to handle ambiguous times during DST transitions
155
 * @returns ZonedDateTime representing the parsed zoned datetime
156
 * @throws Error if string format is invalid
157
 */
158
function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { parseZonedDateTime } from "@internationalized/date";
165

166
// Basic zoned datetime
167
const zonedDT = parseZonedDateTime("2024-03-15T14:30:00[America/New_York]");
168

169
// With UTC offset and timezone
170
const fullFormat = parseZonedDateTime("2024-03-15T14:30:00-05:00[America/New_York]");
171

172
// Different timezone formats
173
const utcZoned = parseZonedDateTime("2024-03-15T14:30:00Z[UTC]");
174
const europeZoned = parseZonedDateTime("2024-03-15T14:30:00+01:00[Europe/Paris]");
175

176
// Handle DST ambiguity
177
const ambiguousTime = "2024-11-03T01:30:00[America/New_York]"; // DST ends, 1:30 happens twice
178
const firstOccurrence = parseZonedDateTime(ambiguousTime, 'earlier');
179
const secondOccurrence = parseZonedDateTime(ambiguousTime, 'later');
180

181
// Invalid time during spring forward
182
const invalidTime = "2024-03-10T02:30:00[America/New_York]"; // 2:30 AM doesn't exist
183
const resolvedTime = parseZonedDateTime(invalidTime, 'compatible'); // Resolved to 3:30 AM
184
```
185

186
### Duration Parsing
187

188
Parse ISO 8601 duration strings into duration objects.
189

190
```typescript { .api }
191
/**
192
 * Parses an ISO 8601 duration string
193
 * @param value - ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
194
 * @returns Required<DateTimeDuration> with all duration fields present
195
 * @throws Error if string format is invalid
196
 */
197
function parseDuration(value: string): Required<DateTimeDuration>;
198
```
199

200
**Usage Examples:**
201

202
```typescript
203
import { parseDuration } from "@internationalized/date";
204

205
// Basic duration formats
206
const duration1 = parseDuration("P1Y"); // 1 year
207
const duration2 = parseDuration("P2M"); // 2 months  
208
const duration3 = parseDuration("P3D"); // 3 days
209
const duration4 = parseDuration("PT4H"); // 4 hours
210
const duration5 = parseDuration("PT5M"); // 5 minutes
211
const duration6 = parseDuration("PT6S"); // 6 seconds
212

213
// Combined durations
214
const combined = parseDuration("P1Y2M3DT4H5M6S"); // 1y 2m 3d 4h 5m 6s
215
const dateOnly = parseDuration("P1Y6M15D"); // 1 year 6 months 15 days
216
const timeOnly = parseDuration("PT8H30M45S"); // 8 hours 30 minutes 45 seconds
217

218
// Weeks
219
const weeks = parseDuration("P2W"); // 2 weeks
220
const weeksAndDays = parseDuration("P2W3D"); // 2 weeks 3 days
221

222
// Fractional values
223
const fractionalHours = parseDuration("PT2.5H"); // 2.5 hours
224
const fractionalMinutes = parseDuration("PT30.75M"); // 30.75 minutes
225
const fractionalSeconds = parseDuration("PT45.123S"); // 45.123 seconds
226

227
// Negative durations
228
const negative = parseDuration("-P1Y2M3D"); // Negative 1y 2m 3d
229

230
// Use with date arithmetic
231
const date = parseDate("2024-03-15");
232
const duration = parseDuration("P1M2D");
233
const futureDate = date.add(duration); // April 17, 2024
234
```
235

236
### Advanced Parsing Scenarios
237

238
Handle complex parsing scenarios and error cases.
239

240
**Parsing with Error Handling:**
241

242
```typescript
243
import { 
244
  parseDate, 
245
  parseDateTime, 
246
  parseZonedDateTime 
247
} from "@internationalized/date";
248

249
function safeParse(dateString: string) {
250
  try {
251
    // Try different parsing strategies
252
    if (dateString.includes('T')) {
253
      if (dateString.includes('[')) {
254
        return parseZonedDateTime(dateString);
255
      } else {
256
        return parseDateTime(dateString);
257
      }
258
    } else {
259
      return parseDate(dateString);
260
    }
261
  } catch (error) {
262
    console.error('Failed to parse date string:', dateString, error);
263
    return null;
264
  }
265
}
266

267
// Usage
268
const parsed1 = safeParse("2024-03-15"); // CalendarDate
269
const parsed2 = safeParse("2024-03-15T14:30:00"); // CalendarDateTime  
270
const parsed3 = safeParse("2024-03-15T14:30:00[UTC]"); // ZonedDateTime
271
const parsed4 = safeParse("invalid"); // null
272
```
273

274
**Complex Duration Parsing:**
275

276
```typescript
277
import { parseDuration, CalendarDateTime } from "@internationalized/date";
278

279
// Parse and apply different duration types
280
const baseDateTime = new CalendarDateTime(2024, 1, 1, 12, 0, 0);
281

282
const yearDuration = parseDuration("P1Y");
283
const monthDuration = parseDuration("P6M");
284
const weekDuration = parseDuration("P2W");
285
const dayDuration = parseDuration("P10D");
286
const timeDuration = parseDuration("PT12H30M");
287
const complexDuration = parseDuration("P1Y2M3DT4H5M6.789S");
288

289
// Apply durations
290
const afterYear = baseDateTime.add(yearDuration);
291
const afterMonth = baseDateTime.add(monthDuration);
292
const afterComplex = baseDateTime.add(complexDuration);
293
```
294

295
## Types
296

297
```typescript { .api }
298
/**
299
 * Disambiguation strategy for handling ambiguous times during DST transitions
300
 */
301
type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
302

303
/**
304
 * Represents an amount of time with both date and time components
305
 */
306
interface DateTimeDuration extends DateDuration, TimeDuration {}
307

308
/**
309
 * Represents an amount of time in calendar-specific units
310
 */
311
interface DateDuration {
312
  years?: number;
313
  months?: number;
314
  weeks?: number;
315
  days?: number;
316
}
317

318
/**
319
 * Represents an amount of time in time units
320
 */
321
interface TimeDuration {
322
  hours?: number;
323
  minutes?: number;
324
  seconds?: number;
325
  milliseconds?: number;
326
}
327
```