0
# Date and Time Operations
1

2
Core functionality for working with dates, times, and date-time objects including arithmetic operations, formatting, navigation, and conversions.
3

4
## Capabilities
5

6
### LocalDate Operations
7

8
LocalDate represents a date without time or timezone information.
9

10
```groovy { .api }
11
/**
12
 * Returns a LocalDate that is the specified number of days after this date.
13
 */
14
LocalDate plus(LocalDate self, long days)
15

16
/**
17
 * Returns a LocalDate that is the specified number of days before this date.
18
 */
19
LocalDate minus(LocalDate self, long days)
20

21
/**
22
 * Calculates the number of days between two dates.
23
 */
24
long minus(LocalDate self, LocalDate other)
25

26
/**
27
 * Returns a LocalDate one day after this date.
28
 */
29
LocalDate next(LocalDate self)
30

31
/**
32
 * Returns a LocalDate one day before this date.
33
 */
34
LocalDate previous(LocalDate self)
35

36
/**
37
 * Formats this date with the provided DateTimeFormatter pattern.
38
 */
39
String format(LocalDate self, String pattern)
40

41
/**
42
 * Formats this date in the provided, localized FormatStyle.
43
 */
44
String format(LocalDate self, FormatStyle dateStyle)
45

46
/**
47
 * Formats this date with the ISO_LOCAL_DATE formatter.
48
 */
49
String getDateString(LocalDate self)
50

51
/**
52
 * Combines this date with a LocalTime to create a LocalDateTime.
53
 */
54
LocalDateTime leftShift(LocalDate self, LocalTime time)
55

56
/**
57
 * Combines this date with an OffsetTime to create an OffsetDateTime.
58
 */
59
OffsetDateTime leftShift(LocalDate self, OffsetTime time)
60

61
/**
62
 * Returns a Period between this date (inclusive) and the provided date (exclusive).
63
 */
64
Period rightShift(LocalDate self, LocalDate other)
65

66
/**
67
 * Converts to a java.util.Date with time portion cleared.
68
 */
69
Date toDate(LocalDate self)
70

71
/**
72
 * Converts to a java.util.Calendar with time portion cleared.
73
 */
74
Calendar toCalendar(LocalDate self)
75
```
76

77
**Usage Examples:**
78

79
```groovy
80
import java.time.*
81
import java.time.format.FormatStyle
82

83
def today = LocalDate.now()
84

85
// Arithmetic operations
86
def nextWeek = today + 7
87
def lastMonth = today - 30
88
def daysBetween = nextWeek - today  // Returns 7
89

90
// Navigation
91
def tomorrow = today.next()
92
def yesterday = today.previous()
93

94
// Formatting
95
def formatted = today.format('MM/dd/yyyy')  // "12/25/2024"
96
def localized = today.format(FormatStyle.LONG)  // "December 25, 2024"
97
def iso = today.dateString  // "2024-12-25"
98

99
// Combining with time
100
def datetime = today << LocalTime.of(14, 30)  // LocalDateTime
101
def offsetDateTime = today << OffsetTime.of(14, 30, 0, 0, ZoneOffset.ofHours(5))
102

103
// Period calculation
104
def period = today >> (today + 30)  // Period of 30 days
105
```
106

107
### LocalTime Operations
108

109
LocalTime represents a time without date or timezone information.
110

111
```groovy { .api }
112
/**
113
 * Returns a LocalTime that is the specified number of seconds after this time.
114
 */
115
LocalTime plus(LocalTime self, long seconds)
116

117
/**
118
 * Returns a LocalTime that is the specified number of seconds before this time.
119
 */
120
LocalTime minus(LocalTime self, long seconds)
121

122
/**
123
 * Returns a LocalTime one second after this time.
124
 */
125
LocalTime next(LocalTime self)
126

127
/**
128
 * Returns a LocalTime one second before this time.
129
 */
130
LocalTime previous(LocalTime self)
131

132
/**
133
 * Formats this time with the provided DateTimeFormatter pattern.
134
 */
135
String format(LocalTime self, String pattern)
136

137
/**
138
 * Formats this time in the provided, localized FormatStyle.
139
 */
140
String format(LocalTime self, FormatStyle timeStyle)
141

142
/**
143
 * Formats this time with the ISO_LOCAL_TIME formatter.
144
 */
145
String getTimeString(LocalTime self)
146

147
/**
148
 * Combines this time with a LocalDate to create a LocalDateTime.
149
 */
150
LocalDateTime leftShift(LocalTime self, LocalDate date)
151

152
/**
153
 * Combines this time with a ZoneOffset to create an OffsetTime.
154
 */
155
OffsetTime leftShift(LocalTime self, ZoneOffset offset)
156

157
/**
158
 * Converts to a java.util.Date (using today's date).
159
 */
160
Date toDate(LocalTime self)
161

162
/**
163
 * Converts to a java.util.Calendar (using today's date).
164
 */
165
Calendar toCalendar(LocalTime self)
166
```
167

168
**Usage Examples:**
169

170
```groovy
171
import java.time.*
172

173
def now = LocalTime.now()
174

175
// Arithmetic operations
176
def inOneMinute = now + 60  // Add 60 seconds
177
def tenSecondsAgo = now - 10
178

179
// Navigation
180
def nextSecond = now.next()
181
def previousSecond = now.previous()
182

183
// Formatting
184
def formatted = now.format('HH:mm:ss')  // "14:30:25"
185
def timeString = now.timeString  // "14:30:25.123"
186

187
// Combining with date and offset
188
def datetime = now << LocalDate.of(2024, 12, 25)
189
def offsetTime = now << ZoneOffset.ofHours(-5)
190
```
191

192
### LocalDateTime Operations
193

194
LocalDateTime represents a date-time without timezone information.
195

196
```groovy { .api }
197
/**
198
 * Returns a LocalDateTime that is the specified number of seconds after this date-time.
199
 */
200
LocalDateTime plus(LocalDateTime self, long seconds)
201

202
/**
203
 * Returns a LocalDateTime that is the specified number of seconds before this date-time.
204
 */
205
LocalDateTime minus(LocalDateTime self, long seconds)
206

207
/**
208
 * Returns a LocalDateTime one second after this date-time.
209
 */
210
LocalDateTime next(LocalDateTime self)
211

212
/**
213
 * Returns a LocalDateTime one second before this date-time.
214
 */
215
LocalDateTime previous(LocalDateTime self)
216

217
/**
218
 * Returns a LocalDateTime with the time portion cleared (truncated to days).
219
 */
220
LocalDateTime clearTime(LocalDateTime self)
221

222
/**
223
 * Formats this date-time with the provided DateTimeFormatter pattern.
224
 */
225
String format(LocalDateTime self, String pattern)
226

227
/**
228
 * Formats this date-time in the provided, localized FormatStyle.
229
 */
230
String format(LocalDateTime self, FormatStyle dateTimeStyle)
231

232
/**
233
 * Formats this date-time with the ISO_LOCAL_DATE_TIME formatter.
234
 */
235
String getDateTimeString(LocalDateTime self)
236

237
/**
238
 * Formats the date portion with the ISO_LOCAL_DATE formatter.
239
 */
240
String getDateString(LocalDateTime self)
241

242
/**
243
 * Formats the time portion with the ISO_LOCAL_TIME formatter.
244
 */
245
String getTimeString(LocalDateTime self)
246

247
/**
248
 * Combines this date-time with a ZoneOffset to create an OffsetDateTime.
249
 */
250
OffsetDateTime leftShift(LocalDateTime self, ZoneOffset offset)
251

252
/**
253
 * Combines this date-time with a ZoneId to create a ZonedDateTime.
254
 */
255
ZonedDateTime leftShift(LocalDateTime self, ZoneId zone)
256

257
/**
258
 * Converts to a java.util.Date.
259
 */
260
Date toDate(LocalDateTime self)
261

262
/**
263
 * Converts to a java.util.Calendar.
264
 */
265
Calendar toCalendar(LocalDateTime self)
266
```
267

268
**Usage Examples:**
269

270
```groovy
271
import java.time.*
272
import java.time.format.FormatStyle
273

274
def now = LocalDateTime.now()
275

276
// Arithmetic operations
277
def inFiveMinutes = now + 300  // Add 300 seconds
278
def anHourAgo = now - 3600
279

280
// Time manipulation
281
def startOfDay = now.clearTime()  // Same date at 00:00:00
282

283
// Formatting
284
def custom = now.format('yyyy-MM-dd HH:mm:ss')
285
def iso = now.dateTimeString  // ISO format
286
def dateOnly = now.dateString  // Date part only
287
def timeOnly = now.timeString  // Time part only
288

289
// Adding timezone information
290
def offsetDateTime = now << ZoneOffset.ofHours(2)
291
def zonedDateTime = now << ZoneId.of('Europe/London')
292
```
293

294
### Instant Operations
295

296
Instant represents a point in time on the UTC timeline.
297

298
```groovy { .api }
299
/**
300
 * Returns an Instant that is the specified number of seconds after this instant.
301
 */
302
Instant plus(Instant self, long seconds)
303

304
/**
305
 * Returns an Instant that is the specified number of seconds before this instant.
306
 */
307
Instant minus(Instant self, long seconds)
308

309
/**
310
 * Returns an Instant one second after this instant.
311
 */
312
Instant next(Instant self)
313

314
/**
315
 * Returns an Instant one second before this instant.
316
 */
317
Instant previous(Instant self)
318

319
/**
320
 * Converts to a java.util.Date.
321
 */
322
Date toDate(Instant self)
323

324
/**
325
 * Converts to a java.util.Calendar in GMT timezone.
326
 */
327
Calendar toCalendar(Instant self)
328
```
329

330
**Usage Examples:**
331

332
```groovy
333
import java.time.*
334

335
def now = Instant.now()
336

337
// Arithmetic operations
338
def inOneMinute = now + 60
339
def fiveSecondsAgo = now - 5
340

341
// Navigation
342
def nextInstant = now.next()
343
def previousInstant = now.previous()
344

345
// Conversion to legacy types
346
def date = now.toDate()
347
def calendar = now.toCalendar()  // GMT timezone
348
```
349

350
### OffsetDateTime Operations
351

352
OffsetDateTime represents a date-time with an offset from UTC/Greenwich.
353

354
```groovy { .api }
355
/**
356
 * Returns an OffsetDateTime that is the specified number of seconds after this date-time.
357
 */
358
OffsetDateTime plus(OffsetDateTime self, long seconds)
359

360
/**
361
 * Returns an OffsetDateTime that is the specified number of seconds before this date-time.
362
 */
363
OffsetDateTime minus(OffsetDateTime self, long seconds)
364

365
/**
366
 * Returns an OffsetDateTime one second after this date-time.
367
 */
368
OffsetDateTime next(OffsetDateTime self)
369

370
/**
371
 * Returns an OffsetDateTime one second before this date-time.
372
 */
373
OffsetDateTime previous(OffsetDateTime self)
374

375
/**
376
 * Returns an OffsetDateTime with the time portion cleared (truncated to days).
377
 */
378
OffsetDateTime clearTime(OffsetDateTime self)
379

380
/**
381
 * Formats this offset date-time with the provided DateTimeFormatter pattern.
382
 */
383
String format(OffsetDateTime self, String pattern)
384

385
/**
386
 * Formats this offset date-time in the provided, localized FormatStyle.
387
 */
388
String format(OffsetDateTime self, FormatStyle dateTimeStyle)
389

390
/**
391
 * Formats this offset date-time with the ISO_OFFSET_DATE_TIME formatter.
392
 */
393
String getDateTimeString(OffsetDateTime self)
394

395
/**
396
 * Formats the date portion with the ISO_OFFSET_DATE formatter.
397
 */
398
String getDateString(OffsetDateTime self)
399

400
/**
401
 * Formats the time portion with the ISO_OFFSET_TIME formatter.
402
 */
403
String getTimeString(OffsetDateTime self)
404

405
/**
406
 * Converts to a java.util.Date.
407
 */
408
Date toDate(OffsetDateTime self)
409

410
/**
411
 * Converts to a java.util.Calendar.
412
 */
413
Calendar toCalendar(OffsetDateTime self)
414
```
415

416
**Usage Examples:**
417

418
```groovy
419
import java.time.*
420
import java.time.format.FormatStyle
421

422
def offsetDateTime = OffsetDateTime.now()
423

424
// Arithmetic operations
425
def inTenMinutes = offsetDateTime + 600  // Add 600 seconds
426
def anHourAgo = offsetDateTime - 3600
427

428
// Time manipulation
429
def startOfDay = offsetDateTime.clearTime()  // Same date at 00:00:00 with same offset
430

431
// Formatting
432
def custom = offsetDateTime.format('yyyy-MM-dd HH:mm:ss XXX')
433
def iso = offsetDateTime.dateTimeString  // ISO format with offset
434
def dateOnly = offsetDateTime.dateString  // Date part with offset
435
def timeOnly = offsetDateTime.timeString  // Time part with offset
436

437
// Conversion to legacy types
438
def date = offsetDateTime.toDate()
439
def calendar = offsetDateTime.toCalendar()
440
```
441

442
### OffsetTime Operations
443

444
OffsetTime represents a time with an offset from UTC/Greenwich.
445

446
```groovy { .api }
447
/**
448
 * Returns an OffsetTime that is the specified number of seconds after this time.
449
 */
450
OffsetTime plus(OffsetTime self, long seconds)
451

452
/**
453
 * Returns an OffsetTime that is the specified number of seconds before this time.
454
 */
455
OffsetTime minus(OffsetTime self, long seconds)
456

457
/**
458
 * Returns an OffsetTime one second after this time.
459
 */
460
OffsetTime next(OffsetTime self)
461

462
/**
463
 * Returns an OffsetTime one second before this time.
464
 */
465
OffsetTime previous(OffsetTime self)
466

467
/**
468
 * Formats this offset time with the provided DateTimeFormatter pattern.
469
 */
470
String format(OffsetTime self, String pattern)
471

472
/**
473
 * Formats this offset time in the provided, localized FormatStyle.
474
 */
475
String format(OffsetTime self, FormatStyle timeStyle)
476

477
/**
478
 * Formats this offset time with the ISO_OFFSET_TIME formatter.
479
 */
480
String getTimeString(OffsetTime self)
481

482
/**
483
 * Combines this offset time with a LocalDate to create an OffsetDateTime.
484
 */
485
OffsetDateTime leftShift(OffsetTime self, LocalDate date)
486

487
/**
488
 * Converts to a java.util.Date (using today's date).
489
 */
490
Date toDate(OffsetTime self)
491

492
/**
493
 * Converts to a java.util.Calendar (using today's date).
494
 */
495
Calendar toCalendar(OffsetTime self)
496
```
497

498
**Usage Examples:**
499

500
```groovy
501
import java.time.*
502

503
def offsetTime = OffsetTime.now()
504

505
// Arithmetic operations
506
def inFiveMinutes = offsetTime + 300  // Add 300 seconds
507
def tenSecondsAgo = offsetTime - 10
508

509
// Navigation
510
def nextSecond = offsetTime.next()
511
def previousSecond = offsetTime.previous()
512

513
// Formatting
514
def formatted = offsetTime.format('HH:mm:ss XXX')  // "14:30:25 +05:00"
515
def timeString = offsetTime.timeString  // ISO format with offset
516

517
// Combining with date
518
def offsetDateTime = offsetTime << LocalDate.of(2024, 12, 25)
519

520
// Conversion to legacy types
521
def date = offsetTime.toDate()
522
def calendar = offsetTime.toCalendar()
523
```