0
# Date & Time
1

2
GMT date handling with HTTP date format support and timezone operations. Provides comprehensive date and time utilities specifically designed for web applications and HTTP protocol compatibility.
3

4
## Capabilities
5

6
### GMTDate Class
7

8
Core date class representing GMT/UTC time with full date components.
9

10
```kotlin { .api }
11
/**
12
 * Represents a GMT date with all date components
13
 */
14
class GMTDate(
15
    val seconds: Int,      // 0-59
16
    val minutes: Int,      // 0-59  
17
    val hours: Int,        // 0-23
18
    val dayOfMonth: Int,   // 1-31
19
    val month: Month,      // Month enum
20
    val year: Int,         // Full year (e.g., 2023)
21
    val dayOfWeek: WeekDay, // WeekDay enum
22
    val dayOfYear: Int,    // 1-366
23
    val timestamp: Long    // Unix timestamp in milliseconds
24
) {
25
    /** String representation in HTTP date format */
26
    override fun toString(): String
27
    
28
    /** Equality comparison */
29
    override fun equals(other: Any?): Boolean
30
    
31
    /** Hash code based on timestamp */
32
    override fun hashCode(): Int
33
}
34
```
35

36
**Usage Examples:**
37

38
```kotlin
39
import io.ktor.util.date.*
40

41
// Create GMTDate from components
42
val date = GMTDate(
43
    seconds = 30,
44
    minutes = 45, 
45
    hours = 14,
46
    dayOfMonth = 25,
47
    month = Month.DECEMBER,
48
    year = 2023,
49
    dayOfWeek = WeekDay.MONDAY,
50
    dayOfYear = 359,
51
    timestamp = System.currentTimeMillis()
52
)
53

54
println(date) // HTTP date format
55
println("Year: ${date.year}, Month: ${date.month}")
56
println("Timestamp: ${date.timestamp}")
57
```
58

59
### GMTDate Factory Functions
60

61
Functions for creating GMTDate instances from various sources.
62

63
```kotlin { .api }
64
/**
65
 * Create GMTDate from Unix timestamp
66
 * @param timestamp Unix timestamp in milliseconds
67
 * @return GMTDate instance
68
 */
69
fun GMTDate(timestamp: Long): GMTDate
70

71
/**
72
 * Create GMTDate from current time
73
 * @return GMTDate representing current GMT time
74
 */
75
fun GMTDate(): GMTDate
76

77
/**
78
 * Create GMTDate from individual components
79
 * @param year Full year
80
 * @param month Month (1-12)
81
 * @param day Day of month (1-31)
82
 * @param hour Hour (0-23)
83
 * @param minute Minute (0-59)
84
 * @param second Second (0-59)
85
 * @return GMTDate instance
86
 */
87
fun GMTDate(
88
    year: Int,
89
    month: Int,
90
    day: Int,
91
    hour: Int = 0,
92
    minute: Int = 0,
93
    second: Int = 0
94
): GMTDate
95
```
96

97
**Usage Examples:**
98

99
```kotlin
100
import io.ktor.util.date.*
101

102
// Create from timestamp
103
val fromTimestamp = GMTDate(1703516400000L) // Dec 25, 2023
104

105
// Create current date
106
val now = GMTDate()
107

108
// Create from components
109
val specificDate = GMTDate(
110
    year = 2024,
111
    month = 6,    // June
112
    day = 15,
113
    hour = 10,
114
    minute = 30,
115
    second = 45
116
)
117

118
println("Current time: $now")
119
println("Specific date: $specificDate")
120
```
121

122
### Month Enumeration
123

124
Enumeration representing months of the year.
125

126
```kotlin { .api }
127
/**
128
 * Months of the year
129
 */
130
enum class Month(val value: String) {
131
    JANUARY("Jan"),
132
    FEBRUARY("Feb"),
133
    MARCH("Mar"),
134
    APRIL("Apr"),
135
    MAY("May"),
136
    JUNE("Jun"),
137
    JULY("Jul"),
138
    AUGUST("Aug"),
139
    SEPTEMBER("Sep"),
140
    OCTOBER("Oct"),
141
    NOVEMBER("Nov"),
142
    DECEMBER("Dec");
143
    
144
    companion object {
145
        /** Lookup month by ordinal */
146
        fun from(ordinal: Int): Month
147
        
148
        /** Lookup month by short name */
149
        fun from(value: String): Month
150
    }
151
}
152
```
153

154
**Usage Examples:**
155

156
```kotlin
157
import io.ktor.util.date.*
158

159
// Work with months
160
val currentMonth = Month.DECEMBER
161
println("Month: ${currentMonth.name}") // "DECEMBER"
162
println("Short name: ${currentMonth.value}") // "Dec"
163

164
// Iterate through months
165
for (month in Month.values()) {
166
    println("${month.name}: ${month.value}")
167
}
168

169
// Find month by short name
170
val monthByValue = Month.from("Jun") // JUNE
171
val monthByOrdinal = Month.from(5) // JUNE (0-based)
172
```
173

174
### WeekDay Enumeration
175

176
Enumeration representing days of the week.
177

178
```kotlin { .api }
179
/**
180
 * Days of the week
181
 */
182
enum class WeekDay(val value: String) {
183
    MONDAY("Mon"),
184
    TUESDAY("Tue"),
185
    WEDNESDAY("Wed"),
186
    THURSDAY("Thu"),
187
    FRIDAY("Fri"),
188
    SATURDAY("Sat"),
189
    SUNDAY("Sun");
190
    
191
    companion object {
192
        /** Lookup day by ordinal */
193
        fun from(ordinal: Int): WeekDay
194
        
195
        /** Lookup day by short name */
196
        fun from(value: String): WeekDay
197
    }
198
}
199
```
200

201
**Usage Examples:**
202

203
```kotlin
204
import io.ktor.util.date.*
205

206
// Work with weekdays
207
val today = WeekDay.FRIDAY
208
println("Today is: ${today.name}") // "FRIDAY"
209
println("Short name: ${today.value}") // "Fri"
210

211
// Find by short name or ordinal
212
val dayByName = WeekDay.from("Fri") // FRIDAY
213
val dayByOrdinal = WeekDay.from(4) // FRIDAY (0-based)
214

215
// Check weekend
216
fun isWeekend(day: WeekDay): Boolean {
217
    return day == WeekDay.SATURDAY || day == WeekDay.SUNDAY
218
}
219

220
println("Is Friday weekend? ${isWeekend(WeekDay.FRIDAY)}") // false
221
```
222

223
### HTTP Date Formatting
224

225
Functions for converting between GMTDate and HTTP date strings.
226

227
```kotlin { .api }
228
/**
229
 * Convert GMTDate to HTTP date string
230
 * @return HTTP-formatted date string (RFC 7231)
231
 */
232
fun GMTDate.toHttpDate(): String
233

234
/**
235
 * Parse HTTP date string to GMTDate
236
 * @param httpDate HTTP-formatted date string
237
 * @return Parsed GMTDate instance
238
 * @throws IllegalArgumentException if format is invalid
239
 */
240
fun String.fromHttpDate(): GMTDate
241
```
242

243
**Usage Examples:**
244

245
```kotlin
246
import io.ktor.util.date.*
247

248
// Convert to HTTP date format
249
val date = GMTDate(2023, 12, 25, 14, 30, 0)
250
val httpDate = date.toHttpDate()
251
println(httpDate) // "Mon, 25 Dec 2023 14:30:00 GMT"
252

253
// Parse HTTP date string
254
val httpDateString = "Tue, 15 Nov 1994 08:12:31 GMT"
255
val parsedDate = httpDateString.fromHttpDate()
256
println("Parsed: ${parsedDate.year}-${parsedDate.month.value}-${parsedDate.dayOfMonth}")
257

258
// Use in HTTP headers
259
val headers = mutableMapOf<String, String>()
260
headers["Date"] = GMTDate().toHttpDate()
261
headers["Last-Modified"] = lastModified.toHttpDate()
262
headers["Expires"] = expirationDate.toHttpDate()
263
```
264

265
### GMT Date Parser
266

267
Advanced parsing utilities for various date formats.
268

269
```kotlin { .api }
270
/**
271
 * GMT date parser with support for multiple formats
272
 */
273
object GMTDateParser {
274
    /** Parse date from various common formats */
275
    fun parse(dateString: String): GMTDate
276
    
277
    /** Parse HTTP date format (RFC 7231) */
278
    fun parseHttpDate(httpDate: String): GMTDate
279
    
280
    /** Parse ISO 8601 format */
281
    fun parseISODate(isoDate: String): GMTDate
282
    
283
    /** Try parsing with multiple format attempts */
284
    fun tryParse(dateString: String): GMTDate?
285
}
286
```
287

288
**Usage Examples:**
289

290
```kotlin
291
import io.ktor.util.date.*
292

293
// Parse different date formats
294
val httpDate = GMTDateParser.parseHttpDate("Mon, 25 Dec 2023 14:30:00 GMT")
295
val isoDate = GMTDateParser.parseISODate("2023-12-25T14:30:00Z")
296

297
// Try parsing unknown format
298
val unknownFormat = "25/12/2023 14:30:00"
299
val parsed = GMTDateParser.tryParse(unknownFormat)
300
if (parsed != null) {
301
    println("Successfully parsed: $parsed")
302
} else {
303
    println("Could not parse date")
304
}
305

306
// Generic parsing
307
val flexibleDate = GMTDateParser.parse("December 25, 2023")
308
```
309

310
### Date Arithmetic
311

312
Utilities for date calculations and comparisons.
313

314
```kotlin { .api }
315
/**
316
 * Date arithmetic extension functions
317
 */
318

319
/** Add milliseconds to GMTDate */
320
fun GMTDate.plus(milliseconds: Long): GMTDate
321

322
/** Subtract milliseconds from GMTDate */
323
fun GMTDate.minus(milliseconds: Long): GMTDate
324

325
/** Get difference in milliseconds between dates */
326
operator fun GMTDate.minus(other: GMTDate): Long
327

328
/** Check if date is before another */
329
fun GMTDate.isBefore(other: GMTDate): Boolean
330

331
/** Check if date is after another */
332
fun GMTDate.isAfter(other: GMTDate): Boolean
333

334
/** Check if dates are on same day */
335
fun GMTDate.isSameDay(other: GMTDate): Boolean
336
```
337

338
**Usage Examples:**
339

340
```kotlin
341
import io.ktor.util.date.*
342

343
val baseDate = GMTDate(2023, 12, 25, 12, 0, 0)
344

345
// Date arithmetic
346
val oneHourLater = baseDate.plus(60 * 60 * 1000) // Add 1 hour
347
val oneDayEarlier = baseDate.minus(24 * 60 * 60 * 1000) // Subtract 1 day
348

349
// Date comparisons
350
val now = GMTDate()
351
if (baseDate.isBefore(now)) {
352
    println("Base date is in the past")
353
}
354

355
// Calculate duration
356
val start = GMTDate(2023, 1, 1, 0, 0, 0)
357
val end = GMTDate(2023, 12, 31, 23, 59, 59) 
358
val durationMs = end - start
359
val durationDays = durationMs / (24 * 60 * 60 * 1000)
360
println("Duration: $durationDays days")
361

362
// Check same day
363
val morning = GMTDate(2023, 12, 25, 9, 0, 0)
364
val evening = GMTDate(2023, 12, 25, 21, 0, 0)
365
println("Same day: ${morning.isSameDay(evening)}") // true
366
```
367

368
### Time Zone Utilities
369

370
Additional utilities for timezone-aware operations.
371

372
```kotlin { .api }
373
/**
374
 * Time zone conversion utilities
375
 */
376
object TimeZoneUtils {
377
    /** Convert GMT date to local time zone */
378
    fun GMTDate.toLocalTime(): LocalDateTime
379
    
380
    /** Convert local time to GMT */
381
    fun LocalDateTime.toGMTDate(): GMTDate
382
    
383
    /** Get current timezone offset from GMT */
384
    fun getCurrentTimezoneOffset(): Int
385
    
386
    /** Format date with timezone information */
387
    fun GMTDate.formatWithTimezone(zoneId: String): String
388
}
389
```
390

391
**Usage Examples:**
392

393
```kotlin
394
import io.ktor.util.date.*
395

396
// Timezone conversions
397
val gmtDate = GMTDate()
398
val localTime = TimeZoneUtils.run { gmtDate.toLocalTime() }
399
val backToGmt = TimeZoneUtils.run { localTime.toGMTDate() }
400

401
// Get timezone offset
402
val offsetMinutes = TimeZoneUtils.getCurrentTimezoneOffset()
403
println("Current timezone offset: $offsetMinutes minutes from GMT")
404

405
// Format with timezone
406
val formatted = TimeZoneUtils.run { 
407
    gmtDate.formatWithTimezone("America/New_York") 
408
}
409
println("Date in NY timezone: $formatted")
410
```
411

412
## Constants and Utilities
413

414
```kotlin { .api }
415
/** Milliseconds in a second */
416
const val MILLIS_PER_SECOND = 1000L
417

418
/** Milliseconds in a minute */
419
const val MILLIS_PER_MINUTE = 60 * MILLIS_PER_SECOND
420

421
/** Milliseconds in an hour */
422
const val MILLIS_PER_HOUR = 60 * MILLIS_PER_MINUTE
423

424
/** Milliseconds in a day */
425
const val MILLIS_PER_DAY = 24 * MILLIS_PER_HOUR
426
```