0
# Groovy DateTime Extensions
1

2
Groovy DateTime Extensions provides enhanced date/time functionality for Groovy applications by extending Java 8+ `java.time` API classes with convenient methods. The library offers operator overloading, iteration capabilities, formatting utilities, and seamless conversion between legacy `java.util.Date/Calendar` and modern `java.time` types.
3

4
## Package Information
5

6
- **Package Name**: org.codehaus.groovy:groovy-datetime
7
- **Package Type**: maven
8
- **Language**: Java/Groovy
9
- **Installation**: Add to Gradle: `implementation 'org.codehaus.groovy:groovy-datetime:3.0.25'`
10

11
## Core Imports
12

13
The package provides extension methods that are automatically available in Groovy when the library is in the classpath. Import temporal types as needed:
14

15
```groovy
16
@Grab('org.codehaus.groovy:groovy-datetime:3.0.25')
17

18
import java.time.*
19
import java.time.format.*
20
import java.time.temporal.*
21
```
22

23
Java usage requires static imports:
24

25
```java
26
import static org.apache.groovy.datetime.extensions.DateTimeExtensions.*;
27
import static org.apache.groovy.datetime.extensions.DateTimeStaticExtensions.*;
28
```
29

30
## Basic Usage
31

32
```groovy
33
import java.time.*
34

35
// Operator overloading for arithmetic
36
def today = LocalDate.now()
37
def nextWeek = today + 7  // Add 7 days
38
def lastMonth = today - 30  // Subtract 30 days
39

40
// Iteration over date ranges
41
def start = LocalDate.of(2024, 1, 1)
42
def end = start + 5
43
start.upto(end) { date ->
44
    println date.dayOfWeek
45
}
46

47
// Formatting with patterns
48
def datetime = LocalDateTime.now()
49
println datetime.format('yyyy-MM-dd HH:mm:ss')
50
println datetime.dateString  // ISO format
51

52
// Static parsing
53
def parsed = LocalDate.parse('2024-12-25', 'yyyy-MM-dd')
54

55
// Conversion between legacy and modern types
56
def legacyDate = new Date()
57
def localDate = legacyDate.toLocalDate()
58
def backToDate = localDate.toDate()
59

60
// Zone and offset operations  
61
def zoned = LocalDateTime.now() << ZoneId.of('America/New_York')
62
def offset = LocalTime.now() << ZoneOffset.ofHours(-5)
63
```
64

65
## Architecture
66

67
The library consists of two main extension classes:
68

69
- **DateTimeExtensions**: Instance methods added to `java.time` types (formatting, arithmetic, iteration, conversion)
70
- **DateTimeStaticExtensions**: Static factory and parsing methods for `java.time` types
71

72
Extensions follow Groovy conventions for operator overloading:
73
- `+` and `-` operators for temporal arithmetic
74
- `++` and `--` for next/previous operations  
75
- `<<` (left shift) for combining temporal objects
76
- `>>` (right shift) for calculating periods/durations between objects
77
- `[]` (subscript) for accessing temporal fields and units
78

79
## Capabilities
80

81
### Core Date/Time Operations
82

83
Essential operations for date, time, and datetime manipulation including arithmetic, formatting, and navigation.
84

85
```groovy { .api }
86
// LocalDate operations
87
LocalDate plus(LocalDate self, long days)
88
LocalDate minus(LocalDate self, long days)
89
String format(LocalDate self, String pattern)
90
String getDateString(LocalDate self)
91

92
// LocalDateTime operations  
93
LocalDateTime plus(LocalDateTime self, long seconds)
94
LocalDateTime clearTime(LocalDateTime self)
95
String getDateTimeString(LocalDateTime self)
96

97
// LocalTime operations
98
LocalTime plus(LocalTime self, long seconds)
99
String getTimeString(LocalTime self)
100
```
101

102
[Date and Time Operations](./date-time-operations.md)
103

104
### Zoned and Offset Date/Time
105

106
Working with time zones, offsets, and zone-aware temporal operations.
107

108
```groovy { .api }
109
// Zone operations
110
ZonedDateTime leftShift(LocalDateTime self, ZoneId zone)
111
OffsetDateTime leftShift(LocalDateTime self, ZoneOffset offset)
112
ZoneOffset getOffset(ZoneId self)
113
String getShortName(ZoneId self)
114

115
// Offset operations
116
int getHours(ZoneOffset self)
117
TimeZone toTimeZone(ZoneOffset self)
118
```
119

120
[Zoned and Offset Operations](./zone-offset-operations.md)
121

122
### Temporal Iteration and Ranges
123

124
Iterating over temporal ranges with custom units and step sizes.
125

126
```groovy { .api }
127
// Iteration methods
128
void upto(Temporal from, Temporal to, Closure closure)
129
void upto(Temporal from, Temporal to, TemporalUnit unit, Closure closure)
130
void downto(Temporal from, Temporal to, Closure closure)
131
TemporalAmount rightShift(Temporal self, Temporal other)
132
```
133

134
[Temporal Iteration](./temporal-iteration.md)
135

136
### Duration and Period Arithmetic
137

138
Mathematical operations on durations and periods with operator overloading.
139

140
```groovy { .api }
141
// Duration operations
142
Duration plus(Duration self, long seconds)
143
Duration multiply(Duration self, long scalar)
144
Duration negative(Duration self)
145
boolean isPositive(Duration self)
146

147
// Period operations  
148
Period plus(Period self, long days)
149
Period multiply(Period self, int scalar)
150
Period positive(Period self)
151
```
152

153
[Duration and Period Operations](./duration-period-operations.md)
154

155
### Parsing and Static Methods
156

157
Static parsing methods with custom patterns and factory methods.
158

159
```groovy { .api }
160
// Static parsing methods
161
LocalDate parse(LocalDate type, CharSequence text, String pattern)
162
LocalDateTime parse(LocalDateTime type, CharSequence text, String pattern)
163
ZonedDateTime parse(ZonedDateTime type, CharSequence text, String pattern)
164

165
// Factory methods
166
ZoneOffset systemDefault(ZoneOffset type)
167
Period between(Period type, Year startInclusive, Year endExclusive)
168
```
169

170
[Parsing and Factory Methods](./parsing-factory-methods.md)
171

172
### Legacy Date/Calendar Conversion
173

174
Bidirectional conversion between legacy `java.util.Date/Calendar` and modern `java.time` types.
175

176
```groovy { .api }
177
// Calendar to java.time conversions
178
LocalDate toLocalDate(Calendar self)
179
LocalDateTime toLocalDateTime(Calendar self)
180
ZonedDateTime toZonedDateTime(Calendar self)
181
ZoneId getZoneId(Calendar self)
182

183
// java.time to legacy conversions
184
Date toDate(LocalDate self)
185
Calendar toCalendar(LocalDateTime self)
186
```
187

188
[Legacy Conversion](./legacy-conversion.md)
189

190
### Enum Extensions
191

192
Enhanced functionality for `DayOfWeek` and `Month` enums with arithmetic and utility methods.
193

194
```groovy { .api }
195
// DayOfWeek operations
196
DayOfWeek plus(DayOfWeek self, int days)
197
boolean isWeekend(DayOfWeek self)
198
boolean isWeekday(DayOfWeek self)
199

200
// Month operations
201
Month plus(Month self, int months)
202
MonthDay leftShift(Month self, int dayOfMonth)
203
```
204

205
[Enum Extensions](./enum-extensions.md)
206

207
### Year and YearMonth Operations
208

209
Comprehensive operations for Year and YearMonth temporal objects including arithmetic, period calculations, and temporal object creation.
210

211
```groovy { .api }
212
// Year operations
213
Year plus(Year self, long years)
214
Year minus(Year self, long years)
215
Period rightShift(Year self, Year year)
216
YearMonth leftShift(Year self, Month month)
217

218
// YearMonth operations
219
YearMonth plus(YearMonth self, long months)
220
YearMonth minus(YearMonth self, long months)
221
LocalDate leftShift(YearMonth self, int dayOfMonth)
222
Period rightShift(YearMonth self, YearMonth other)
223
```
224

225
[Year and YearMonth Operations](./year-month-operations.md)
226

227
## Types
228

229
```groovy { .api }
230
// All standard java.time types are supported:
231
// LocalDate, LocalTime, LocalDateTime
232
// OffsetTime, OffsetDateTime  
233
// ZonedDateTime, Instant
234
// Duration, Period
235
// Year, YearMonth, MonthDay
236
// DayOfWeek, Month
237
// ZoneId, ZoneOffset
238
// TemporalAccessor, TemporalAmount, Temporal
239
// TemporalField, TemporalUnit
240
// DateTimeFormatter, FormatStyle
241
```