0
# Zoned and Offset Operations
1

2
Functionality for working with time zones, offsets, and zone-aware temporal operations including conversions, zone information retrieval, and timezone-aware datetime creation.
3

4
## Capabilities
5

6
### ZonedDateTime Operations
7

8
ZonedDateTime represents a date-time with timezone information.
9

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

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

21
/**
22
 * Returns a ZonedDateTime one second after this date-time.
23
 */
24
ZonedDateTime next(ZonedDateTime self)
25

26
/**
27
 * Returns a ZonedDateTime one second before this date-time.
28
 */
29
ZonedDateTime previous(ZonedDateTime self)
30

31
/**
32
 * Returns a ZonedDateTime with the time portion cleared.
33
 */
34
ZonedDateTime clearTime(ZonedDateTime self)
35

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

41
/**
42
 * Formats this date-time in the provided, localized FormatStyle.
43
 */
44
String format(ZonedDateTime self, FormatStyle dateTimeStyle)
45

46
/**
47
 * Formats with ISO_LOCAL_DATE_TIME and appends the zone's short name.
48
 */
49
String getDateTimeString(ZonedDateTime self)
50

51
/**
52
 * Formats with ISO_LOCAL_DATE and appends the zone's short name.
53
 */
54
String getDateString(ZonedDateTime self)
55

56
/**
57
 * Formats with ISO_LOCAL_TIME and appends the zone's short name.
58
 */
59
String getTimeString(ZonedDateTime self)
60

61
/**
62
 * Converts to a java.util.Date (adjusted to system default timezone).
63
 */
64
Date toDate(ZonedDateTime self)
65

66
/**
67
 * Converts to a java.util.Calendar with the timezone from this ZonedDateTime.
68
 */
69
Calendar toCalendar(ZonedDateTime self)
70
```
71

72
**Usage Examples:**
73

74
```groovy
75
import java.time.*
76

77
def nyTime = ZonedDateTime.now(ZoneId.of('America/New_York'))
78

79
// Arithmetic operations
80
def inOneHour = nyTime + 3600
81
def yesterdaySameTime = nyTime - 86400
82

83
// Time manipulation
84
def startOfDay = nyTime.clearTime()
85

86
// Formatting with zone information
87
def formatted = nyTime.format('yyyy-MM-dd HH:mm:ss VV')
88
def dateTime = nyTime.dateTimeString  // "2024-12-25T14:30:25EST"
89
def dateOnly = nyTime.dateString      // "2024-12-25EST"
90
def timeOnly = nyTime.timeString      // "14:30:25EST"
91

92
// Conversion
93
def date = nyTime.toDate()
94
def calendar = nyTime.toCalendar()  // Preserves timezone
95
```
96

97

98
### ZoneId Operations
99

100
ZoneId represents a timezone identifier.
101

102
```groovy { .api }
103
/**
104
 * Converts to a java.util.TimeZone equivalent.
105
 */
106
TimeZone toTimeZone(ZoneId self)
107

108
/**
109
 * Returns the full display name in the default locale.
110
 */
111
String getFullName(ZoneId self)
112

113
/**
114
 * Returns the full display name in the specified locale.
115
 */
116
String getFullName(ZoneId self, Locale locale)
117

118
/**
119
 * Returns the short display name in the default locale.
120
 */
121
String getShortName(ZoneId self)
122

123
/**
124
 * Returns the short display name in the specified locale.
125
 */
126
String getShortName(ZoneId self, Locale locale)
127

128
/**
129
 * Returns the current ZoneOffset for this zone.
130
 */
131
ZoneOffset getOffset(ZoneId self)
132

133
/**
134
 * Returns the ZoneOffset for this zone at the specified instant.
135
 */
136
ZoneOffset getOffset(ZoneId self, Instant instant)
137

138
/**
139
 * Combines this zone with a LocalDateTime to create a ZonedDateTime.
140
 */
141
ZonedDateTime leftShift(ZoneId self, LocalDateTime dateTime)
142
```
143

144
**Usage Examples:**
145

146
```groovy
147
import java.time.*
148

149
def nyZone = ZoneId.of('America/New_York')
150
def utcZone = ZoneId.of('UTC')
151

152
// Zone information
153
def fullName = nyZone.fullName        // "Eastern Standard Time"
154
def shortName = nyZone.shortName      // "EST"
155
def currentOffset = nyZone.offset     // Current offset from UTC
156
def offsetAt = nyZone.getOffset(Instant.parse('2024-07-01T00:00:00Z'))
157

158
// Create zoned datetime
159
def zonedTime = nyZone << LocalDateTime.of(2024, 12, 25, 14, 30)
160

161
// Convert to legacy timezone
162
def timeZone = nyZone.toTimeZone()
163
```
164

165
### ZoneOffset Operations
166

167
ZoneOffset represents a fixed offset from UTC.
168

169
```groovy { .api }
170
/**
171
 * Converts to a java.util.TimeZone (truncated to minutes).
172
 */
173
TimeZone toTimeZone(ZoneOffset self)
174

175
/**
176
 * Returns the hours component of this offset.
177
 */
178
int getHours(ZoneOffset self)
179

180
/**
181
 * Returns the minutes component of this offset.
182
 */
183
int getMinutes(ZoneOffset self)
184

185
/**
186
 * Returns the seconds component of this offset.
187
 */
188
int getSeconds(ZoneOffset self)
189

190
/**
191
 * Supports subscript operator for accessing temporal fields.
192
 */
193
long getAt(ZoneOffset self, TemporalField field)
194

195
/**
196
 * Combines this offset with a LocalDateTime to create an OffsetDateTime.
197
 */
198
OffsetDateTime leftShift(ZoneOffset self, LocalDateTime dateTime)
199

200
/**
201
 * Combines this offset with a LocalTime to create an OffsetTime.
202
 */
203
OffsetTime leftShift(ZoneOffset self, LocalTime time)
204
```
205

206
**Usage Examples:**
207

208
```groovy
209
import java.time.*
210
import java.time.temporal.ChronoField
211

212
def offset = ZoneOffset.ofHoursMinutesSeconds(5, 30, 45)
213

214
// Offset components
215
def hours = offset.hours        // 5
216
def minutes = offset.minutes    // 30  
217
def seconds = offset.seconds    // 45
218
def totalSeconds = offset.totalSeconds  // 19845
219

220
// Field access using subscript operator
221
def hourField = offset[ChronoField.OFFSET_SECONDS]
222

223
// Create offset date/time
224
def offsetDateTime = offset << LocalDateTime.now()
225
def offsetTime = offset << LocalTime.of(14, 30)
226

227
// Convert to legacy timezone
228
def timeZone = offset.toTimeZone()  // GMT+05:30
229
```
230

231
### System Default Zone Methods
232

233
```groovy { .api }
234
/**
235
 * Returns the ZoneOffset currently associated with the system default ZoneId.
236
 */
237
ZoneOffset systemDefault(ZoneOffset type)
238
```
239

240
**Usage Examples:**
241

242
```groovy
243
import java.time.*
244

245
// Get system default offset (static method)
246
def systemOffset = ZoneOffset.systemDefault()
247
```