0
# Calendar Intervals
1

2
The `CalendarInterval` class represents time intervals with separate month and microsecond components, providing precise handling of calendar-based time periods commonly used in SQL operations. This design accounts for the variable length of months while maintaining microsecond precision for sub-day intervals.
3

4
## Core Imports
5

6
```java
7
import org.apache.spark.unsafe.types.CalendarInterval;
8
```
9

10
## Usage Examples
11

12
### Creating Calendar Intervals
13

14
```java
15
// Create interval with 2 months and 1.5 days
16
CalendarInterval interval = new CalendarInterval(2, 1500000000L); // 1.5 days in microseconds
17

18
// Create intervals from string representations
19
CalendarInterval fromString = CalendarInterval.fromString("2 months 3 days");
20
CalendarInterval caseInsensitive = CalendarInterval.fromCaseInsensitiveString("2 MONTHS 3 DAYS");
21

22
// Parse specific formats
23
CalendarInterval yearMonth = CalendarInterval.fromYearMonthString("1-6"); // 1 year 6 months
24
CalendarInterval dayTime = CalendarInterval.fromDayTimeString("5 12:30:45.123"); // 5 days, 12:30:45.123
25
```
26

27
### Basic Interval Operations
28

29
```java
30
CalendarInterval interval1 = new CalendarInterval(1, CalendarInterval.MICROS_PER_DAY * 10); // 1 month, 10 days
31
CalendarInterval interval2 = new CalendarInterval(0, CalendarInterval.MICROS_PER_HOUR * 5);  // 5 hours
32

33
// Arithmetic operations
34
CalendarInterval sum = interval1.add(interval2);         // Add intervals
35
CalendarInterval diff = interval1.subtract(interval2);  // Subtract intervals
36
CalendarInterval negated = interval1.negate();          // Negate interval
37

38
// Get milliseconds component
39
long millis = interval1.milliseconds(); // Convert microseconds to milliseconds
40
```
41

42
### Working with Time Constants
43

44
```java
45
// Using predefined time constants
46
long fiveMinutes = 5 * CalendarInterval.MICROS_PER_MINUTE;
47
long twoHours = 2 * CalendarInterval.MICROS_PER_HOUR;
48
long threeDays = 3 * CalendarInterval.MICROS_PER_DAY;
49
long oneWeek = CalendarInterval.MICROS_PER_WEEK;
50

51
CalendarInterval timeInterval = new CalendarInterval(0, fiveMinutes + twoHours);
52
```
53

54
### Parsing Complex Intervals
55

56
```java
57
// Parse intervals with multiple units
58
CalendarInterval complex = CalendarInterval.fromString("1 year 2 months 3 weeks 4 days 5 hours 6 minutes 7 seconds");
59

60
// Parse year-month format (SQL standard)
61
CalendarInterval yearMonthInterval = CalendarInterval.fromYearMonthString("2-5"); // 2 years, 5 months
62

63
// Parse day-time format (SQL standard)
64
CalendarInterval dayTimeInterval = CalendarInterval.fromDayTimeString("10 15:30:45.500"); // 10 days, 15:30:45.500
65

66
// Parse single unit intervals
67
CalendarInterval hours = CalendarInterval.fromSingleUnitString("hour", "24");
68
CalendarInterval days = CalendarInterval.fromSingleUnitString("day", "7");
69
```
70

71
## API Reference
72

73
### Constructor and Fields
74

75
```java { .api }
76
public final class CalendarInterval {
77
    /**
78
     * Number of months in the interval.
79
     */
80
    public final int months;
81
    
82
    /**
83
     * Number of microseconds in the interval.
84
     */
85
    public final long microseconds;
86
    
87
    /**
88
     * Creates a calendar interval with specified months and microseconds.
89
     */
90
    public CalendarInterval(int months, long microseconds);
91
}
92
```
93

94
### Time Constants
95

96
```java { .api }
97
public static final long MICROS_PER_MILLI = 1000L;
98
public static final long MICROS_PER_SECOND = 1000000L;
99
public static final long MICROS_PER_MINUTE = 60000000L;
100
public static final long MICROS_PER_HOUR = 3600000000L;
101
public static final long MICROS_PER_DAY = 86400000000L;
102
public static final long MICROS_PER_WEEK = 604800000000L;
103
```
104

105
### Conversion Methods
106

107
```java { .api }
108
/**
109
 * Returns microseconds converted to milliseconds.
110
 */
111
public long milliseconds();
112
```
113

114
### Arithmetic Operations
115

116
```java { .api }
117
/**
118
 * Adds two calendar intervals.
119
 */
120
public CalendarInterval add(CalendarInterval that);
121

122
/**
123
 * Subtracts one interval from another.
124
 */
125
public CalendarInterval subtract(CalendarInterval that);
126

127
/**
128
 * Returns the negated interval.
129
 */
130
public CalendarInterval negate();
131
```
132

133
### String Parsing Methods
134

135
```java { .api }
136
/**
137
 * Parses interval from string representation (case-sensitive).
138
 * Supports formats like "1 year 2 months 3 days 4 hours 5 minutes 6 seconds".
139
 */
140
public static CalendarInterval fromString(String s);
141

142
/**
143
 * Parses interval from string representation (case-insensitive).
144
 */
145
public static CalendarInterval fromCaseInsensitiveString(String s);
146

147
/**
148
 * Parses year-month format interval (e.g., "1-6" for 1 year 6 months).
149
 */
150
public static CalendarInterval fromYearMonthString(String s);
151

152
/**
153
 * Parses day-time format interval (e.g., "5 12:30:45.123").
154
 */
155
public static CalendarInterval fromDayTimeString(String s);
156

157
/**
158
 * Parses single unit interval (e.g., unit="day", s="5").
159
 */
160
public static CalendarInterval fromSingleUnitString(String unit, String s);
161
```
162

163
### Utility Methods
164

165
```java { .api }
166
/**
167
 * Parses long value with range validation.
168
 */
169
public static long toLongWithRange(String fieldName, String s, long minValue, long maxValue);
170

171
/**
172
 * Parses seconds with nanosecond precision, returns microseconds.
173
 */
174
public static long parseSecondNano(String secondNano);
175
```
176

177
### Object Methods
178

179
```java { .api }
180
/**
181
 * Compares intervals for equality.
182
 */
183
public boolean equals(Object other);
184

185
/**
186
 * Returns hash code for the interval.
187
 */
188
public int hashCode();
189

190
/**
191
 * Returns string representation of the interval.
192
 */
193
public String toString();
194
```
195

196
## Supported String Formats
197

198
### General Format
199

200
The general string format supports combinations of the following units:
201
- `year`, `years`
202
- `month`, `months` 
203
- `week`, `weeks`
204
- `day`, `days`
205
- `hour`, `hours`
206
- `minute`, `minutes`
207
- `second`, `seconds`
208
- `millisecond`, `milliseconds`
209
- `microsecond`, `microseconds`
210

211
Examples:
212
```java
213
CalendarInterval.fromString("1 year 2 months")
214
CalendarInterval.fromString("3 days 4 hours 30 minutes")
215
CalendarInterval.fromString("2 weeks 5 seconds 500 milliseconds")
216
```
217

218
### Year-Month Format
219

220
SQL standard format for year-month intervals:
221
- Format: `"Y-M"` where Y is years and M is months
222
- Examples: `"1-6"` (1 year 6 months), `"0-18"` (18 months)
223

224
### Day-Time Format
225

226
SQL standard format for day-time intervals:
227
- Format: `"D H:M:S.f"` where D is days, H is hours, M is minutes, S is seconds, f is fractional seconds
228
- Examples: `"5 12:30:45"`, `"10 15:30:45.500"`
229

230
### Single Unit Format
231

232
For parsing single units with a specific value:
233
```java
234
CalendarInterval.fromSingleUnitString("day", "5")    // 5 days
235
CalendarInterval.fromSingleUnitString("hour", "24")  // 24 hours
236
```
237

238
## Usage Notes
239

240
1. **Month Precision**: Months are stored separately because they have variable lengths (28-31 days).
241

242
2. **Microsecond Precision**: Sub-day intervals are stored with microsecond precision for maximum accuracy.
243

244
3. **Immutability**: CalendarInterval objects are immutable; arithmetic operations return new instances.
245

246
4. **SQL Compatibility**: String parsing follows SQL standard formats for INTERVAL types.
247

248
5. **Range Limitations**: Be aware of overflow when working with very large intervals.
249

250
6. **Parsing Errors**: Invalid string formats will throw exceptions during parsing.
251

252
7. **Case Sensitivity**: Use `fromCaseInsensitiveString()` for case-insensitive parsing.
253

254
## Common Patterns
255

256
### Creating Common Intervals
257

258
```java
259
// Common time periods
260
CalendarInterval oneDay = new CalendarInterval(0, CalendarInterval.MICROS_PER_DAY);
261
CalendarInterval oneWeek = new CalendarInterval(0, CalendarInterval.MICROS_PER_WEEK);
262
CalendarInterval oneMonth = new CalendarInterval(1, 0);
263
CalendarInterval oneYear = new CalendarInterval(12, 0);
264

265
// Mixed intervals
266
CalendarInterval quarter = new CalendarInterval(3, 0); // 3 months
267
CalendarInterval businessWeek = new CalendarInterval(0, 5 * CalendarInterval.MICROS_PER_DAY);
268
```
269

270
### Validation and Error Handling
271

272
```java
273
try {
274
    CalendarInterval interval = CalendarInterval.fromString("invalid format");
275
} catch (IllegalArgumentException e) {
276
    // Handle parsing errors
277
    System.err.println("Invalid interval format: " + e.getMessage());
278
}
279
```