0
# Date and Time Operations
1

2
Date parsing, formatting, manipulation, and calendar operations with support for both legacy Date API and Java 8+ time API through the DateUtil class.
3

4
## Capabilities
5

6
### Date Formatting
7

8
Convert Date objects to formatted strings using various patterns.
9

10
```java { .api }
11
/**
12
 * Format date using specified pattern
13
 * @param date the date to format
14
 * @param format the format pattern (e.g., "yyyy-MM-dd HH:mm:ss")
15
 * @return formatted date string
16
 */
17
public static String format(Date date, String format);
18

19
/**
20
 * Format date using predefined DateTime format (yyyy-MM-dd HH:mm:ss)
21
 * @param date the date to format
22
 * @return formatted date string
23
 */
24
public static String formatDateTime(Date date);
25

26
/**
27
 * Format date using predefined Date format (yyyy-MM-dd)
28
 * @param date the date to format
29
 * @return formatted date string
30
 */
31
public static String formatDate(Date date);
32

33
/**
34
 * Format date using predefined Time format (HH:mm:ss)
35
 * @param date the date to format
36
 * @return formatted time string
37
 */
38
public static String formatTime(Date date);
39
```
40

41
**Usage Examples:**
42

43
```java
44
import cn.hutool.core.date.DateUtil;
45
import java.util.Date;
46

47
Date now = new Date();
48

49
// Custom formatting
50
String custom = DateUtil.format(now, "yyyy-MM-dd HH:mm:ss");
51
String iso = DateUtil.format(now, "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
52

53
// Predefined formats
54
String dateTime = DateUtil.formatDateTime(now);  // "2023-01-15 14:30:25"
55
String dateOnly = DateUtil.formatDate(now);      // "2023-01-15"
56
String timeOnly = DateUtil.formatTime(now);      // "14:30:25"
57
```
58

59
### Date Parsing
60

61
Parse strings into Date objects using various patterns with intelligent format detection.
62

63
```java { .api }
64
/**
65
 * Parse date string using specified format
66
 * @param dateStr the date string to parse
67
 * @param format the format pattern
68
 * @return parsed Date object
69
 * @throws DateException if parsing fails
70
 */
71
public static Date parse(String dateStr, String format);
72

73
/**
74
 * Parse date string with automatic format detection
75
 * @param dateStr the date string to parse
76
 * @return parsed Date object
77
 * @throws DateException if parsing fails
78
 */
79
public static Date parse(String dateStr);
80

81
/**
82
 * Parse date string safely, returning null if parsing fails
83
 * @param dateStr the date string to parse
84
 * @param format the format pattern
85
 * @return parsed Date object or null if parsing fails
86
 */
87
public static Date parseQuietly(String dateStr, String format);
88
```
89

90
**Usage Examples:**
91

92
```java
93
// Explicit format parsing
94
Date date1 = DateUtil.parse("2023-01-15 14:30:25", "yyyy-MM-dd HH:mm:ss");
95
Date date2 = DateUtil.parse("15/01/2023", "dd/MM/yyyy");
96

97
// Automatic format detection
98
Date date3 = DateUtil.parse("2023-01-15");           // Detects yyyy-MM-dd
99
Date date4 = DateUtil.parse("2023-01-15 14:30:25");  // Detects yyyy-MM-dd HH:mm:ss
100

101
// Safe parsing
102
Date date5 = DateUtil.parseQuietly("invalid-date", "yyyy-MM-dd"); // Returns null
103
```
104

105
### Date Calculation
106

107
Perform date arithmetic and calculate differences between dates.
108

109
```java { .api }
110
/**
111
 * Calculate difference between two dates
112
 * @param beginDate start date
113
 * @param endDate end date
114
 * @param unit the unit for the result (MS, SECOND, MINUTE, HOUR, DAY, WEEK)
115
 * @return difference in specified unit
116
 */
117
public static long between(Date beginDate, Date endDate, DateUnit unit);
118

119
/**
120
 * Add specified amount to date
121
 * @param date base date
122
 * @param amount amount to add (can be negative for subtraction)
123
 * @param dateField Calendar field constant (Calendar.YEAR, Calendar.MONTH, etc.)
124
 * @return new Date with added amount
125
 */
126
public static Date offset(Date date, int amount, int dateField);
127

128
/**
129
 * Add days to date
130
 * @param date base date
131
 * @param numberOfDays number of days to add
132
 * @return new Date with added days
133
 */
134
public static Date offsetDay(Date date, int numberOfDays);
135

136
/**
137
 * Add hours to date
138
 * @param date base date
139
 * @param numberOfHours number of hours to add
140
 * @return new Date with added hours
141
 */
142
public static Date offsetHour(Date date, int numberOfHours);
143
```
144

145
**Usage Examples:**
146

147
```java
148
Date startDate = DateUtil.parse("2023-01-01", "yyyy-MM-dd");
149
Date endDate = DateUtil.parse("2023-01-15", "yyyy-MM-dd");
150

151
// Calculate differences
152
long days = DateUtil.between(startDate, endDate, DateUnit.DAY);     // 14
153
long hours = DateUtil.between(startDate, endDate, DateUnit.HOUR);   // 336
154
long minutes = DateUtil.between(startDate, endDate, DateUnit.MINUTE); // 20160
155

156
// Date arithmetic
157
Date tomorrow = DateUtil.offsetDay(startDate, 1);        // 2023-01-02
158
Date nextWeek = DateUtil.offsetDay(startDate, 7);        // 2023-01-08
159
Date nextHour = DateUtil.offsetHour(startDate, 1);       // Add 1 hour
160
Date lastMonth = DateUtil.offset(startDate, -1, Calendar.MONTH); // Subtract 1 month
161
```
162

163
### Date Range Operations
164

165
Work with date ranges and check if dates fall within specific periods.
166

167
```java { .api }
168
/**
169
 * Check if date is in specified range (inclusive)
170
 * @param date date to check
171
 * @param beginDate range start
172
 * @param endDate range end
173
 * @return true if date is within range
174
 */
175
public static boolean isIn(Date date, Date beginDate, Date endDate);
176

177
/**
178
 * Get start of day (00:00:00.000)
179
 * @param date the date
180
 * @return new Date representing start of day
181
 */
182
public static Date beginOfDay(Date date);
183

184
/**
185
 * Get end of day (23:59:59.999)
186
 * @param date the date
187
 * @return new Date representing end of day
188
 */
189
public static Date endOfDay(Date date);
190

191
/**
192
 * Get start of month
193
 * @param date the date
194
 * @return new Date representing start of month
195
 */
196
public static Date beginOfMonth(Date date);
197

198
/**
199
 * Get end of month
200
 * @param date the date
201
 * @return new Date representing end of month
202
 */
203
public static Date endOfMonth(Date date);
204
```
205

206
### Date Comparison
207

208
Compare dates and determine relationships between them.
209

210
```java { .api }
211
/**
212
 * Check if two dates are on the same day
213
 * @param date1 first date
214
 * @param date2 second date
215
 * @return true if dates are on the same day
216
 */
217
public static boolean isSameDay(Date date1, Date date2);
218

219
/**
220
 * Check if date is today
221
 * @param date date to check
222
 * @return true if date is today
223
 */
224
public static boolean isToday(Date date);
225

226
/**
227
 * Check if date is yesterday
228
 * @param date date to check
229
 * @return true if date is yesterday
230
 */
231
public static boolean isYesterday(Date date);
232

233
/**
234
 * Compare two dates
235
 * @param date1 first date
236
 * @param date2 second date
237
 * @return negative if date1 < date2, zero if equal, positive if date1 > date2
238
 */
239
public static int compare(Date date1, Date date2);
240
```
241

242
### Age and Birthday Calculations
243

244
Calculate ages and work with birthday-related operations.
245

246
```java { .api }
247
/**
248
 * Calculate age from birthday to current date
249
 * @param birthday the birthday
250
 * @return age in years
251
 */
252
public static int age(Date birthday);
253

254
/**
255
 * Calculate age from birthday to specific date
256
 * @param birthday the birthday
257
 * @param dateToCompare date to compare against
258
 * @return age in years
259
 */
260
public static int age(Date birthday, Date dateToCompare);
261

262
/**
263
 * Check if current year is leap year
264
 * @return true if current year is leap year
265
 */
266
public static boolean isLeapYear();
267

268
/**
269
 * Check if specified year is leap year
270
 * @param year the year to check
271
 * @return true if specified year is leap year
272
 */
273
public static boolean isLeapYear(int year);
274
```
275

276
**Usage Examples:**
277

278
```java
279
Date birthday = DateUtil.parse("1990-05-15", "yyyy-MM-dd");
280
Date today = new Date();
281

282
// Age calculation
283
int currentAge = DateUtil.age(birthday);  // Current age
284
int ageAtDate = DateUtil.age(birthday, DateUtil.parse("2020-01-01", "yyyy-MM-dd"));
285

286
// Date comparisons
287
boolean isToday = DateUtil.isToday(today);        // true
288
boolean sameDay = DateUtil.isSameDay(today, new Date()); // true
289

290
// Date ranges
291
Date startOfDay = DateUtil.beginOfDay(today);     // Today at 00:00:00.000
292
Date endOfDay = DateUtil.endOfDay(today);         // Today at 23:59:59.999
293
Date startOfMonth = DateUtil.beginOfMonth(today); // First day of current month
294

295
// Range checking
296
boolean inRange = DateUtil.isIn(today, startOfMonth, DateUtil.endOfMonth(today)); // true
297

298
// Leap year
299
boolean isLeap = DateUtil.isLeapYear(2024);  // true
300
boolean currentLeap = DateUtil.isLeapYear(); // depends on current year
301
```
302

303
## Java 8+ Time API Integration
304

305
DateUtil also provides integration with Java 8+ time classes through LocalDateTimeUtil:
306

307
```java { .api }
308
public class LocalDateTimeUtil {
309
    public static String format(LocalDateTime localDateTime, String format);
310
    public static LocalDateTime parse(String dateStr, String format);
311
    public static long between(LocalDateTime startTime, LocalDateTime endTime, ChronoUnit unit);
312
    public static LocalDateTime offset(LocalDateTime time, long number, TemporalUnit field);
313
}
314
```
315

316
## Date Unit Enumeration
317

318
```java { .api }
319
public enum DateUnit {
320
    MS(1),              // Milliseconds
321
    SECOND(1000),       // Seconds
322
    MINUTE(60 * 1000),  // Minutes
323
    HOUR(60 * 60 * 1000), // Hours
324
    DAY(24 * 60 * 60 * 1000), // Days
325
    WEEK(7 * 24 * 60 * 60 * 1000); // Weeks
326
}
327
```
328

329
## Time Zone Operations
330

331
ZoneUtil provides time zone related utilities:
332

333
```java { .api }
334
public class ZoneUtil {
335
    public static ZoneId getZoneId(String zoneId);
336
    public static ZoneOffset getZoneOffset(int offsetHours);
337
    public static Set<String> getAvailableZoneIds();
338
}
339
```