0
# Timestamp Utilities
1

2
Complete timestamp manipulation supporting RFC 3339 format, various time unit conversions, validation, comparison, and arithmetic operations. All operations include comprehensive range checking and normalization to ensure valid Timestamp protobuf messages.
3

4
## Capabilities
5

6
### Constants
7

8
Pre-defined timestamp constants for common reference points.
9

10
```java { .api }
11
/**
12
 * Minimum valid Timestamp: 0001-01-01T00:00:00Z
13
 */
14
public static final Timestamp MIN_VALUE;
15

16
/**
17
 * Maximum valid Timestamp: 9999-12-31T23:59:59.999999999Z  
18
 */
19
public static final Timestamp MAX_VALUE;
20

21
/**
22
 * Epoch timestamp: 1970-01-01T00:00:00.000000000Z
23
 */
24
public static final Timestamp EPOCH;
25
```
26

27
### Current Time
28

29
Get the current time using the best available system clock.
30

31
```java { .api }
32
/**
33
 * Creates a Timestamp using the best-available system clock.
34
 * Uses nanosecond precision when available, falls back to millisecond precision.
35
 * 
36
 * @return Timestamp representing the current time
37
 */
38
public static Timestamp now();
39
```
40

41
### Time Unit Conversions - Creation
42

43
Create Timestamp instances from various time units.
44

45
```java { .api }
46
/**
47
 * Creates a Timestamp from seconds since epoch.
48
 * 
49
 * @param seconds Number of seconds since Unix epoch
50
 * @return Timestamp representing the specified time
51
 */
52
public static Timestamp fromSeconds(long seconds);
53

54
/**
55
 * Creates a Timestamp from milliseconds since epoch.
56
 * 
57
 * @param milliseconds Number of milliseconds since Unix epoch
58
 * @return Timestamp representing the specified time
59
 */
60
public static Timestamp fromMillis(long milliseconds);
61

62
/**
63
 * Creates a Timestamp from microseconds since epoch.
64
 * 
65
 * @param microseconds Number of microseconds since Unix epoch
66
 * @return Timestamp representing the specified time
67
 */
68
public static Timestamp fromMicros(long microseconds);
69

70
/**
71
 * Creates a Timestamp from nanoseconds since epoch.
72
 * 
73
 * @param nanoseconds Number of nanoseconds since Unix epoch
74
 * @return Timestamp representing the specified time
75
 */
76
public static Timestamp fromNanos(long nanoseconds);
77

78
/**
79
 * Creates a Timestamp from a Date object.
80
 * Preserves full nanosecond precision if input is java.sql.Timestamp.
81
 * 
82
 * @param date Date object to convert
83
 * @return Timestamp representing the date
84
 * @throws IllegalArgumentException if year is before 1 CE or after 9999 CE
85
 */
86
public static Timestamp fromDate(Date date);
87
```
88

89
### Time Unit Conversions - Extraction
90

91
Extract various time unit values from Timestamp instances.
92

93
```java { .api }
94
/**
95
 * Converts Timestamp to seconds since epoch.
96
 * Result is rounded down to nearest second.
97
 * 
98
 * @param timestamp Timestamp to convert
99
 * @return Number of seconds since Unix epoch
100
 */
101
public static long toSeconds(Timestamp timestamp);
102

103
/**
104
 * Converts Timestamp to milliseconds since epoch.
105
 * Result is rounded down to nearest millisecond.
106
 * 
107
 * @param timestamp Timestamp to convert
108
 * @return Number of milliseconds since Unix epoch  
109
 */
110
public static long toMillis(Timestamp timestamp);
111

112
/**
113
 * Converts Timestamp to microseconds since epoch.
114
 * Result is rounded down to nearest microsecond.
115
 * 
116
 * @param timestamp Timestamp to convert
117
 * @return Number of microseconds since Unix epoch
118
 */
119
public static long toMicros(Timestamp timestamp);
120

121
/**
122
 * Converts Timestamp to nanoseconds since epoch.
123
 * 
124
 * @param timestamp Timestamp to convert
125
 * @return Number of nanoseconds since Unix epoch
126
 */
127
public static long toNanos(Timestamp timestamp);
128
```
129

130
### String Format Conversion
131

132
Convert between Timestamp and RFC 3339 string format.
133

134
```java { .api }
135
/**
136
 * Converts Timestamp to RFC 3339 date string format.
137
 * Output is Z-normalized and uses 0, 3, 6, or 9 fractional digits as needed.
138
 * 
139
 * @param timestamp Timestamp to convert
140
 * @return RFC 3339 formatted string (e.g., "1972-01-01T10:00:20.021Z")
141
 * @throws IllegalArgumentException if timestamp is not in valid range
142
 */
143
public static String toString(Timestamp timestamp);
144

145
/**
146
 * Parses RFC 3339 date string to Timestamp.
147
 * Accepts any fractional digits and any timezone offset.
148
 * 
149
 * @param value RFC 3339 formatted string (e.g., "1972-01-01T10:00:20.021-05:00")
150
 * @return Timestamp parsed from the string
151
 * @throws ParseException if parsing fails
152
 */
153
public static Timestamp parse(String value) throws ParseException;
154

155
/**
156
 * Parses RFC 3339 string to Timestamp.
157
 * Same as parse() but throws IllegalArgumentException instead of ParseException.
158
 * 
159
 * @param value RFC 3339 formatted string
160
 * @return Timestamp parsed from the string
161
 * @throws IllegalArgumentException if parsing fails
162
 */
163
public static Timestamp parseUnchecked(String value);
164
```
165

166
### Validation
167

168
Validate Timestamp instances and component values.
169

170
```java { .api }
171
/**
172
 * Checks if the given Timestamp is valid.
173
 * Seconds must be in range [-62,135,596,800, +253,402,300,799].
174
 * Nanos must be in range [0, +999,999,999].
175
 * 
176
 * @param timestamp Timestamp to validate
177
 * @return true if timestamp is valid, false otherwise
178
 */
179
public static boolean isValid(Timestamp timestamp);
180

181
/**
182
 * Checks if the given seconds and nanos form a valid Timestamp.
183
 * 
184
 * @param seconds Seconds component
185
 * @param nanos Nanoseconds component
186
 * @return true if combination is valid, false otherwise
187
 */
188
public static boolean isValid(long seconds, int nanos);
189

190
/**
191
 * Validates a Timestamp and throws exception if invalid.
192
 * 
193
 * @param timestamp Timestamp to validate
194
 * @return The same timestamp if valid
195
 * @throws IllegalArgumentException if timestamp is invalid
196
 */
197
public static Timestamp checkValid(Timestamp timestamp);
198

199
/**
200
 * Builds and validates a Timestamp from builder.
201
 * 
202
 * @param timestampBuilder Timestamp builder to build and validate
203
 * @return Valid built Timestamp
204
 * @throws IllegalArgumentException if resulting timestamp is invalid
205
 */
206
public static Timestamp checkValid(Timestamp.Builder timestampBuilder);
207
```
208

209
### Comparison
210

211
Compare Timestamp instances with proper validation.
212

213
```java { .api }
214
/**
215
 * Returns a Comparator for Timestamps in increasing chronological order.
216
 * The comparator is serializable and validates inputs.
217
 * 
218
 * @return Comparator for Timestamp objects
219
 */
220
public static Comparator<Timestamp> comparator();
221

222
/**
223
 * Compares two timestamps.
224
 * 
225
 * @param x First timestamp
226
 * @param y Second timestamp
227
 * @return 0 if equal, negative if x < y, positive if x > y
228
 * @throws IllegalArgumentException if either timestamp is invalid
229
 */
230
public static int compare(Timestamp x, Timestamp y);
231
```
232

233
### Arithmetic Operations
234

235
Perform arithmetic operations between timestamps and durations.
236

237
```java { .api }
238
/**
239
 * Calculates the duration between two timestamps.
240
 * 
241
 * @param from Start timestamp
242
 * @param to End timestamp
243
 * @return Duration representing the time difference
244
 * @throws IllegalArgumentException if either timestamp is invalid
245
 */
246
public static Duration between(Timestamp from, Timestamp to);
247

248
/**
249
 * Adds a duration to a timestamp.
250
 * 
251
 * @param start Starting timestamp
252
 * @param length Duration to add
253
 * @return New timestamp representing start + length
254
 * @throws IllegalArgumentException if timestamp or duration is invalid
255
 */
256
public static Timestamp add(Timestamp start, Duration length);
257

258
/**
259
 * Subtracts a duration from a timestamp.
260
 * 
261
 * @param start Starting timestamp
262
 * @param length Duration to subtract
263
 * @return New timestamp representing start - length
264
 * @throws IllegalArgumentException if timestamp or duration is invalid
265
 */
266
public static Timestamp subtract(Timestamp start, Duration length);
267
```
268

269
**Usage Examples:**
270

271
```java
272
import com.google.protobuf.util.Timestamps;
273
import com.google.protobuf.util.Durations;
274
import com.google.protobuf.Timestamp;
275
import com.google.protobuf.Duration;
276
import java.text.ParseException;
277

278
// Get current time
279
Timestamp now = Timestamps.now();
280

281
// Create timestamps from various time units
282
Timestamp fromEpoch = Timestamps.fromSeconds(0); // Unix epoch
283
Timestamp fromMillis = Timestamps.fromMillis(System.currentTimeMillis());
284
Timestamp fromDate = Timestamps.fromDate(new Date());
285

286
// Convert to string format
287
String timeString = Timestamps.toString(now);
288
System.out.println(timeString); // "2024-01-15T10:30:45.123456789Z"
289

290
// Parse from string
291
try {
292
    Timestamp parsed = Timestamps.parse("2024-01-15T10:30:45.123Z");
293
    System.out.println("Parsed: " + Timestamps.toString(parsed));
294
} catch (ParseException e) {
295
    System.err.println("Parse error: " + e.getMessage());
296
}
297

298
// Validation
299
if (Timestamps.isValid(now)) {
300
    System.out.println("Timestamp is valid");
301
}
302

303
// Comparison
304
Timestamp earlier = Timestamps.fromSeconds(1000);
305
Timestamp later = Timestamps.fromSeconds(2000);
306
int comparison = Timestamps.compare(earlier, later); // negative value
307

308
// Arithmetic operations
309
Duration oneHour = Durations.fromHours(1);
310
Timestamp oneHourLater = Timestamps.add(now, oneHour);
311
Timestamp oneHourEarlier = Timestamps.subtract(now, oneHour);
312

313
// Calculate duration between timestamps
314
Duration elapsed = Timestamps.between(earlier, later);
315
System.out.println("Elapsed: " + Durations.toString(elapsed));
316

317
// Convert to various time units
318
long epochSeconds = Timestamps.toSeconds(now);
319
long epochMillis = Timestamps.toMillis(now);
320
long epochMicros = Timestamps.toMicros(now);
321
long epochNanos = Timestamps.toNanos(now);
322

323
// Use constants
324
System.out.println("Min: " + Timestamps.toString(Timestamps.MIN_VALUE));
325
System.out.println("Max: " + Timestamps.toString(Timestamps.MAX_VALUE));
326
System.out.println("Epoch: " + Timestamps.toString(Timestamps.EPOCH));
327
```