0
# Date Conversion
1

2
Functions for converting between date types, calendar systems, and timezones with proper handling of ambiguous time situations.
3

4
## Capabilities
5

6
### Type Conversion Functions
7

8
Convert between different date and time object types while preserving appropriate information.
9

10
```typescript { .api }
11
/**
12
 * Extracts date components from date/time objects
13
 * @param dateTime - Any object with date components
14
 * @returns CalendarDate with only date information
15
 */
16
function toCalendarDate(dateTime: AnyCalendarDate): CalendarDate;
17

18
/**
19
 * Converts to CalendarDateTime with optional time
20
 * @param date - Date object to convert
21
 * @param time - Optional time to combine with date
22
 * @returns CalendarDateTime object
23
 */
24
function toCalendarDateTime(date: CalendarDate | CalendarDateTime | ZonedDateTime, time?: AnyTime): CalendarDateTime;
25

26
/**
27
 * Extracts time components from datetime objects
28
 * @param dateTime - Object with time components
29
 * @returns Time object with only time information
30
 */
31
function toTime(dateTime: CalendarDateTime | ZonedDateTime): Time;
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { 
38
  toCalendarDate, 
39
  toCalendarDateTime, 
40
  toTime,
41
  ZonedDateTime,
42
  Time
43
} from "@internationalized/date";
44

45
const zonedDT = new ZonedDateTime(2024, 3, 15, 'UTC', 0, 14, 30);
46

47
// Extract date part
48
const dateOnly = toCalendarDate(zonedDT); // CalendarDate: 2024-03-15
49

50
// Convert to CalendarDateTime
51
const dateTime = toCalendarDateTime(dateOnly, new Time(9, 30));
52

53
// Extract time part
54
const timeOnly = toTime(zonedDT); // Time: 14:30:00
55
```
56

57
### Calendar System Conversion
58

59
Convert dates between different calendar systems while maintaining the same absolute point in time.
60

61
```typescript { .api }
62
/**
63
 * Converts date between calendar systems
64
 * @param date - Date in any calendar system
65
 * @param calendar - Target calendar system
66
 * @returns Date converted to target calendar system
67
 */
68
function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T;
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
import { 
75
  toCalendar, 
76
  CalendarDate, 
77
  createCalendar,
78
  GregorianCalendar 
79
} from "@internationalized/date";
80

81
const gregorianDate = new CalendarDate(2024, 3, 15);
82
const buddhist = createCalendar('buddhist');
83
const persian = createCalendar('persian');
84

85
// Convert to Buddhist calendar (BE 2567)
86
const buddhistDate = toCalendar(gregorianDate, buddhist);
87

88
// Convert to Persian calendar  
89
const persianDate = toCalendar(gregorianDate, persian);
90

91
// Convert back to Gregorian
92
const backToGregorian = toCalendar(buddhistDate, new GregorianCalendar());
93
```
94

95
### Timezone Conversion Functions
96

97
Convert between timezones and handle timezone-aware operations with DST disambiguation.
98

99
```typescript { .api }
100
/**
101
 * Converts to ZonedDateTime in specified timezone
102
 * @param date - Date to convert
103
 * @param timeZone - Target IANA timezone identifier
104
 * @param disambiguation - How to handle ambiguous times during DST transitions
105
 * @returns ZonedDateTime in specified timezone
106
 */
107
function toZoned(
108
  date: CalendarDate | CalendarDateTime | ZonedDateTime, 
109
  timeZone: string, 
110
  disambiguation?: Disambiguation
111
): ZonedDateTime;
112

113
/**
114
 * Converts ZonedDateTime between timezones
115
 * @param date - ZonedDateTime to convert
116
 * @param timeZone - Target IANA timezone identifier
117
 * @returns ZonedDateTime in new timezone representing same instant
118
 */
119
function toTimeZone(date: ZonedDateTime, timeZone: string): ZonedDateTime;
120

121
/**
122
 * Converts to user's local timezone
123
 * @param date - ZonedDateTime to convert
124
 * @returns ZonedDateTime in local timezone
125
 */
126
function toLocalTimeZone(date: ZonedDateTime): ZonedDateTime;
127

128
type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import { 
135
  toZoned, 
136
  toTimeZone, 
137
  toLocalTimeZone,
138
  CalendarDateTime 
139
} from "@internationalized/date";
140

141
const dateTime = new CalendarDateTime(2024, 3, 15, 14, 30);
142

143
// Convert to specific timezone
144
const nyTime = toZoned(dateTime, 'America/New_York');
145
const tokyoTime = toZoned(dateTime, 'Asia/Tokyo');
146

147
// Handle DST ambiguity during "fall back"
148
const ambiguousTime = new CalendarDateTime(2024, 11, 3, 1, 30); // DST ends
149
const earlierTime = toZoned(ambiguousTime, 'America/New_York', 'earlier');
150
const laterTime = toZoned(ambiguousTime, 'America/New_York', 'later');
151

152
// Convert between timezones (same instant, different representation)
153
const parisTime = toTimeZone(nyTime, 'Europe/Paris');
154

155
// Convert to user's local timezone
156
const localTime = toLocalTimeZone(nyTime);
157
```
158

159
### JavaScript Date Conversion
160

161
Convert between the library's date objects and native JavaScript Date objects.
162

163
```typescript { .api }
164
/**
165
 * Converts JavaScript Date to ZonedDateTime
166
 * @param date - JavaScript Date object
167
 * @param timeZone - IANA timezone identifier for interpretation
168
 * @returns ZonedDateTime representing the same instant
169
 */
170
function fromDate(date: Date, timeZone: string): ZonedDateTime;
171

172
/**
173
 * Converts Unix timestamp to ZonedDateTime
174
 * @param ms - Unix timestamp in milliseconds
175
 * @param timeZone - IANA timezone identifier for representation
176
 * @returns ZonedDateTime representing the timestamp
177
 */
178
function fromAbsolute(ms: number, timeZone: string): ZonedDateTime;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
import { fromDate, fromAbsolute } from "@internationalized/date";
185

186
// Convert JavaScript Date
187
const jsDate = new Date('2024-03-15T14:30:00Z');
188
const zonedFromJS = fromDate(jsDate, 'America/New_York');
189

190
// Convert Unix timestamp
191
const timestamp = Date.now();
192
const zonedFromTimestamp = fromAbsolute(timestamp, 'Europe/London');
193

194
// Use with different timezones
195
const utcTime = fromAbsolute(timestamp, 'UTC');
196
const localTime = fromAbsolute(timestamp, 'America/Los_Angeles');
197
```
198

199
### Advanced Conversion Scenarios
200

201
Handle complex conversion scenarios with multiple steps and edge cases.
202

203
**Converting Between Calendar Systems and Timezones:**
204

205
```typescript
206
import { 
207
  CalendarDate, 
208
  createCalendar, 
209
  toCalendar, 
210
  toZoned,
211
  toTimeZone 
212
} from "@internationalized/date";
213

214
// Start with Persian date
215
const persianDate = new CalendarDate(createCalendar('persian'), 1403, 1, 26);
216

217
// Convert to Gregorian calendar
218
const gregorianDate = toCalendar(persianDate, createCalendar('gregory'));
219

220
// Add time and timezone
221
const zonedDT = toZoned(gregorianDate.set({ hour: 14, minute: 30 }), 'Asia/Tehran');
222

223
// Convert to different timezone
224
const nyTime = toTimeZone(zonedDT, 'America/New_York');
225
```
226

227
**DST Transition Handling:**
228

229
```typescript
230
import { CalendarDateTime, toZoned } from "@internationalized/date";
231

232
// Spring forward - 2:30 AM doesn't exist
233
const springForward = new CalendarDateTime(2024, 3, 10, 2, 30);
234

235
// Different disambiguation strategies
236
const compatible = toZoned(springForward, 'America/New_York', 'compatible'); // 3:30 AM
237
const earlier = toZoned(springForward, 'America/New_York', 'earlier'); // 1:30 AM  
238
const later = toZoned(springForward, 'America/New_York', 'later'); // 3:30 AM
239

240
// Fall back - 1:30 AM happens twice
241
const fallBack = new CalendarDateTime(2024, 11, 3, 1, 30);
242
const firstOccurrence = toZoned(fallBack, 'America/New_York', 'earlier'); // First 1:30 AM
243
const secondOccurrence = toZoned(fallBack, 'America/New_York', 'later'); // Second 1:30 AM
244
```
245

246
## Types
247

248
```typescript { .api }
249
/**
250
 * Disambiguation strategy for handling ambiguous times during DST transitions
251
 */
252
type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
253

254
/**
255
 * Interface compatible with any object with date fields
256
 */
257
interface AnyCalendarDate {
258
  readonly calendar: Calendar;
259
  readonly era: string;
260
  readonly year: number;
261
  readonly month: number;
262
  readonly day: number;
263
  copy(): this;
264
}
265

266
/**
267
 * Interface compatible with any object with time fields
268
 */
269
interface AnyTime {
270
  readonly hour: number;
271
  readonly minute: number;
272
  readonly second: number;
273
  readonly millisecond: number;
274
  copy(): this;
275
}
276
```