0
# Duration Utilities
1

2
Duration manipulation with support for various time units, string format conversion, validation, comparison, and arithmetic operations. All operations include proper normalization and range checking to ensure valid Duration protobuf messages.
3

4
## Capabilities
5

6
### Constants
7

8
Pre-defined duration constants for common reference values.
9

10
```java { .api }
11
/**
12
 * Minimum valid Duration: approximately -10,000 years
13
 */
14
public static final Duration MIN_VALUE;
15

16
/**
17
 * Maximum valid Duration: approximately +10,000 years  
18
 */
19
public static final Duration MAX_VALUE;
20

21
/**
22
 * Zero duration constant
23
 */
24
public static final Duration ZERO;
25
```
26

27
### Time Unit Creation
28

29
Create Duration instances from various time units.
30

31
```java { .api }
32
/**
33
 * Creates a Duration from number of days.
34
 * 
35
 * @param days Number of days
36
 * @return Duration representing the specified number of days
37
 */
38
public static Duration fromDays(long days);
39

40
/**
41
 * Creates a Duration from number of hours.
42
 * 
43
 * @param hours Number of hours
44
 * @return Duration representing the specified number of hours
45
 */
46
public static Duration fromHours(long hours);
47

48
/**
49
 * Creates a Duration from number of minutes.
50
 * 
51
 * @param minutes Number of minutes
52
 * @return Duration representing the specified number of minutes
53
 */
54
public static Duration fromMinutes(long minutes);
55

56
/**
57
 * Creates a Duration from number of seconds.
58
 * 
59
 * @param seconds Number of seconds
60
 * @return Duration representing the specified number of seconds
61
 */
62
public static Duration fromSeconds(long seconds);
63

64
/**
65
 * Creates a Duration from number of milliseconds.
66
 * 
67
 * @param milliseconds Number of milliseconds
68
 * @return Duration representing the specified number of milliseconds
69
 */
70
public static Duration fromMillis(long milliseconds);
71

72
/**
73
 * Creates a Duration from number of microseconds.
74
 * 
75
 * @param microseconds Number of microseconds
76
 * @return Duration representing the specified number of microseconds
77
 */
78
public static Duration fromMicros(long microseconds);
79

80
/**
81
 * Creates a Duration from number of nanoseconds.
82
 * 
83
 * @param nanoseconds Number of nanoseconds
84
 * @return Duration representing the specified number of nanoseconds
85
 */
86
public static Duration fromNanos(long nanoseconds);
87
```
88

89
### Time Unit Conversion
90

91
Extract time unit values from Duration instances.
92

93
```java { .api }
94
/**
95
 * Converts Duration to number of days.
96
 * Result is rounded towards 0 to the nearest day.
97
 * 
98
 * @param duration Duration to convert
99
 * @return Number of days
100
 */
101
public static long toDays(Duration duration);
102

103
/**
104
 * Converts Duration to number of hours.
105
 * Result is rounded towards 0 to the nearest hour.
106
 * 
107
 * @param duration Duration to convert
108
 * @return Number of hours
109
 */
110
public static long toHours(Duration duration);
111

112
/**
113
 * Converts Duration to number of minutes.
114
 * Result is rounded towards 0 to the nearest minute.
115
 * 
116
 * @param duration Duration to convert
117
 * @return Number of minutes
118
 */
119
public static long toMinutes(Duration duration);
120

121
/**
122
 * Converts Duration to number of seconds.
123
 * Result is rounded towards 0 to the nearest second.
124
 * 
125
 * @param duration Duration to convert
126
 * @return Number of seconds
127
 */
128
public static long toSeconds(Duration duration);
129

130
/**
131
 * Converts Duration to number of seconds as double.
132
 * This method should be used for APIs that only accept double values.
133
 * May lose precision.
134
 * 
135
 * @param duration Duration to convert
136
 * @return Number of seconds as double with fractional component
137
 */
138
public static double toSecondsAsDouble(Duration duration);
139

140
/**
141
 * Converts Duration to number of milliseconds.
142
 * Result is rounded towards 0 to the nearest millisecond.
143
 * 
144
 * @param duration Duration to convert
145
 * @return Number of milliseconds
146
 */
147
public static long toMillis(Duration duration);
148

149
/**
150
 * Converts Duration to number of microseconds.
151
 * Result is rounded towards 0 to the nearest microsecond.
152
 * 
153
 * @param duration Duration to convert
154
 * @return Number of microseconds
155
 */
156
public static long toMicros(Duration duration);
157

158
/**
159
 * Converts Duration to number of nanoseconds.
160
 * 
161
 * @param duration Duration to convert
162
 * @return Number of nanoseconds
163
 */
164
public static long toNanos(Duration duration);
165
```
166

167
### String Format Conversion
168

169
Convert between Duration and string format.
170

171
```java { .api }
172
/**
173
 * Converts Duration to string format.
174
 * Uses 3, 6, or 9 fractional digits as needed for precision.
175
 * Examples: "1s", "1.010s", "1.000000100s", "-3.100s"
176
 * 
177
 * @param duration Duration to convert
178
 * @return String representation of duration
179
 * @throws IllegalArgumentException if duration is invalid
180
 */
181
public static String toString(Duration duration);
182

183
/**
184
 * Parses a string to produce a Duration.
185
 * 
186
 * @param value String in duration format (e.g., "1.5s", "-2.100s")
187
 * @return Duration parsed from string
188
 * @throws ParseException if string is not in valid duration format
189
 */
190
public static Duration parse(String value) throws ParseException;
191

192
/**
193
 * Parses a string to produce a Duration.
194
 * Same as parse() but throws IllegalArgumentException instead of ParseException.
195
 * 
196
 * @param value String in duration format
197
 * @return Duration parsed from string
198
 * @throws IllegalArgumentException if parsing fails
199
 */
200
public static Duration parseUnchecked(String value);
201
```
202

203
### Validation
204

205
Validate Duration instances and check sign properties.
206

207
```java { .api }
208
/**
209
 * Checks if the given Duration is valid.
210
 * Seconds must be in range [-315,576,000,000, +315,576,000,000].
211
 * Nanos must be in range [-999,999,999, +999,999,999].
212
 * Seconds and nanos must have the same sign for durations >= 1 second.
213
 * 
214
 * @param duration Duration to validate
215
 * @return true if duration is valid, false otherwise
216
 */
217
public static boolean isValid(Duration duration);
218

219
/**
220
 * Checks if the given seconds and nanos form a valid Duration.
221
 * 
222
 * @param seconds Seconds component
223
 * @param nanos Nanoseconds component
224
 * @return true if combination is valid, false otherwise
225
 */
226
public static boolean isValid(long seconds, int nanos);
227

228
/**
229
 * Validates a Duration and throws exception if invalid.
230
 * 
231
 * @param duration Duration to validate
232
 * @return The same duration if valid
233
 * @throws IllegalArgumentException if duration is invalid
234
 */
235
public static Duration checkValid(Duration duration);
236

237
/**
238
 * Builds and validates a Duration from builder.
239
 * 
240
 * @param durationBuilder Duration builder to build and validate
241
 * @return Valid built Duration
242
 * @throws IllegalArgumentException if resulting duration is invalid
243
 */
244
public static Duration checkValid(Duration.Builder durationBuilder);
245

246
/**
247
 * Checks if the given Duration is negative.
248
 * 
249
 * @param duration Duration to check
250
 * @return true if duration is negative, false otherwise
251
 * @throws IllegalArgumentException if duration is invalid
252
 */
253
public static boolean isNegative(Duration duration);
254

255
/**
256
 * Checks if the given Duration is positive.
257
 * 
258
 * @param duration Duration to check
259
 * @return true if duration is positive (not zero or negative), false otherwise
260
 * @throws IllegalArgumentException if duration is invalid
261
 */
262
public static boolean isPositive(Duration duration);
263

264
/**
265
 * Ensures the given Duration is not negative.
266
 * 
267
 * @param duration Duration to check
268
 * @return The same duration if not negative
269
 * @throws IllegalArgumentException if duration is negative or invalid
270
 * @throws NullPointerException if duration is null
271
 */
272
public static Duration checkNotNegative(Duration duration);
273

274
/**
275
 * Ensures the given Duration is positive.
276
 * 
277
 * @param duration Duration to check
278
 * @return The same duration if positive
279
 * @throws IllegalArgumentException if duration is negative, zero, or invalid
280
 * @throws NullPointerException if duration is null
281
 */
282
public static Duration checkPositive(Duration duration);
283

284
/**
285
 * Ensures the given Duration is not negative.
286
 * 
287
 * @param duration Duration to check
288
 * @return The same duration if not negative
289
 * @throws IllegalArgumentException if duration is negative or invalid
290
 * @throws NullPointerException if duration is null
291
 */
292
public static Duration checkNotNegative(Duration duration);
293

294
/**
295
 * Ensures the given Duration is positive.
296
 * 
297
 * @param duration Duration to check
298
 * @return The same duration if positive
299
 * @throws IllegalArgumentException if duration is negative, zero, or invalid
300
 * @throws NullPointerException if duration is null
301
 */
302
public static Duration checkPositive(Duration duration);
303
```
304

305
### Comparison
306

307
Compare Duration instances with proper validation.
308

309
```java { .api }
310
/**
311
 * Returns a Comparator for Durations in increasing chronological order.
312
 * The comparator is serializable and validates inputs.
313
 * 
314
 * @return Comparator for Duration objects
315
 */
316
public static Comparator<Duration> comparator();
317

318
/**
319
 * Compares two durations.
320
 * 
321
 * @param x First duration
322
 * @param y Second duration
323
 * @return 0 if equal, negative if x < y, positive if x > y
324
 * @throws IllegalArgumentException if either duration is invalid
325
 */
326
public static int compare(Duration x, Duration y);
327
```
328

329
### Arithmetic Operations
330

331
Perform arithmetic operations on Duration instances.
332

333
```java { .api }
334
/**
335
 * Adds two durations.
336
 * 
337
 * @param d1 First duration
338
 * @param d2 Second duration
339
 * @return Duration representing d1 + d2
340
 * @throws IllegalArgumentException if either duration is invalid
341
 */
342
public static Duration add(Duration d1, Duration d2);
343

344
/**
345
 * Subtracts one duration from another.
346
 * 
347
 * @param d1 Duration to subtract from
348
 * @param d2 Duration to subtract
349
 * @return Duration representing d1 - d2
350
 * @throws IllegalArgumentException if either duration is invalid
351
 */
352
public static Duration subtract(Duration d1, Duration d2);
353
```
354

355
**Usage Examples:**
356

357
```java
358
import com.google.protobuf.util.Durations;
359
import com.google.protobuf.Duration;
360
import java.text.ParseException;
361

362
// Create durations from various time units
363
Duration oneDay = Durations.fromDays(1);
364
Duration twoHours = Durations.fromHours(2);
365
Duration thirtyMinutes = Durations.fromMinutes(30);
366
Duration fiveSeconds = Durations.fromSeconds(5);
367
Duration tenMillis = Durations.fromMillis(10);
368

369
// Convert to string format
370
String durationString = Durations.toString(twoHours);
371
System.out.println(durationString); // "7200s"
372

373
Duration precise = Durations.fromNanos(1500000000); // 1.5 seconds
374
System.out.println(Durations.toString(precise)); // "1.500s"
375

376
// Parse from string
377
try {
378
    Duration parsed = Durations.parse("2.5s");
379
    System.out.println("Parsed: " + Durations.toString(parsed));
380
} catch (ParseException e) {
381
    System.err.println("Parse error: " + e.getMessage());
382
}
383

384
// Validation and sign checking
385
if (Durations.isValid(oneDay)) {
386
    System.out.println("Duration is valid");
387
}
388

389
Duration negative = Durations.fromSeconds(-30);
390
if (Durations.isNegative(negative)) {
391
    System.out.println("Duration is negative");
392
}
393

394
// Comparison
395
Duration shorter = Durations.fromMinutes(10);
396
Duration longer = Durations.fromMinutes(20);
397
int comparison = Durations.compare(shorter, longer); // negative value
398

399
// Arithmetic operations
400
Duration total = Durations.add(twoHours, thirtyMinutes);
401
Duration difference = Durations.subtract(oneDay, twoHours);
402

403
System.out.println("Total: " + Durations.toString(total)); // "9000s"
404
System.out.println("Difference: " + Durations.toString(difference)); // "79200s"
405

406
// Convert to various time units
407
long totalSeconds = Durations.toSeconds(total);
408
long totalMinutes = Durations.toMinutes(total);
409
long totalHours = Durations.toHours(total);
410
double totalSecondsDouble = Durations.toSecondsAsDouble(total);
411

412
// Use constants
413
System.out.println("Zero: " + Durations.toString(Durations.ZERO));
414
System.out.println("Min: " + Durations.toString(Durations.MIN_VALUE));
415
System.out.println("Max: " + Durations.toString(Durations.MAX_VALUE));
416

417
// Validation with checks
418
try {
419
    Duration validated = Durations.checkPositive(twoHours);
420
    System.out.println("Duration is positive: " + Durations.toString(validated));
421
    
422
    Duration nonNegative = Durations.checkNotNegative(thirtyMinutes);
423
    System.out.println("Duration is not negative: " + Durations.toString(nonNegative));
424
} catch (IllegalArgumentException e) {
425
    System.err.println("Duration validation failed: " + e.getMessage());
426
}
427
```