0
# Instant and Time Representation
1

2
Core time representation using kotlin.time.Instant as the primary moment-in-time type, with extensive extensions for timezone-aware operations and formatting.
3

4
## Capabilities
5

6
### Primary Instant Type
7

8
The primary time representation in kotlinx-datetime is `kotlin.time.Instant`, which represents a specific moment in time on the UTC-SLS time scale.
9

10
```kotlin { .api }
11
/**
12
 * A point in time (from kotlin.time)
13
 * Represents a specific moment in time on the UTC-SLS time scale
14
 */
15
class Instant : Comparable<Instant> {
16
    /** Seconds since epoch (1970-01-01T00:00:00Z) */
17
    val epochSeconds: Long
18
    
19
    /** Additional nanoseconds within the second (0-999,999,999) */
20
    val nanosecondsOfSecond: Int
21
    
22
    /** Add a duration to this instant */
23
    fun plus(duration: Duration): Instant
24
    
25
    /** Subtract a duration from this instant */
26
    fun minus(duration: Duration): Instant
27
    
28
    /** Calculate duration between this and another instant */
29
    fun minus(other: Instant): Duration
30
    
31
    /** Compare this instant with another */
32
    override fun compareTo(other: Instant): Int
33
}
34
```
35

36
**Usage Example:**
37

38
```kotlin
39
import kotlin.time.Clock
40
import kotlin.time.Duration.Companion.seconds
41

42
val now = Clock.System.now()
43
val later = now.plus(30.seconds)
44
val duration = later.minus(now)
45
println("Duration: ${duration.inWholeSeconds} seconds")
46
```
47

48
### System Clock Access
49

50
Access to the current system time through the Clock interface.
51

52
```kotlin { .api }
53
/**
54
 * Source of current time information (from kotlin.time)
55
 */
56
interface Clock {
57
    /** Get the current instant */
58
    fun now(): Instant
59
    
60
    companion object {
61
        /** System clock implementation */
62
        val System: Clock
63
    }
64
}
65
```
66

67
### Time Zone Conversions
68

69
Convert instants to local date/time representations in specific time zones.
70

71
```kotlin { .api }
72
/**
73
 * Convert instant to local date/time in specified time zone
74
 * @param timeZone The time zone for conversion
75
 * @returns LocalDateTime in the specified time zone
76
 */
77
fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime
78

79
/**
80
 * Convert instant to local date/time with fixed offset
81
 * Note: This is an internal function in kotlinx-datetime
82
 * For public usage, convert via TimeZone instead
83
 * @param offset The UTC offset for conversion
84
 * @returns LocalDateTime with the specified offset
85
 */
86
internal fun Instant.toLocalDateTime(offset: UtcOffset): LocalDateTime
87

88
/**
89
 * Get the UTC offset for this instant in the specified time zone
90
 * @param timeZone The time zone to check
91
 * @returns UtcOffset for this instant in the time zone
92
 */
93
fun Instant.offsetIn(timeZone: TimeZone): UtcOffset
94
```
95

96
**Usage Examples:**
97

98
```kotlin
99
import kotlinx.datetime.*
100
import kotlin.time.Clock
101

102
val now = Clock.System.now()
103
val nyTimeZone = TimeZone.of("America/New_York")
104
val utcOffset = UtcOffset(hours = -5)
105

106
// Convert to local time in New York
107
val nyTime = now.toLocalDateTime(nyTimeZone)
108
println("New York time: $nyTime")
109

110
// Convert using fixed offset
111
val offsetTime = now.toLocalDateTime(utcOffset)
112
println("UTC-5 time: $offsetTime")
113

114
// Get current offset in New York (accounts for DST)
115
val currentOffset = now.offsetIn(nyTimeZone)
116
println("Current NY offset: $currentOffset")
117
```
118

119
### Date/Time Period Arithmetic
120

121
Perform calendar-aware arithmetic operations on instants using periods and units.
122

123
```kotlin { .api }
124
/**
125
 * Add a date/time period to this instant in the specified time zone
126
 * @param period The period to add (years, months, days, hours, etc.)
127
 * @param timeZone Time zone for calendar-aware calculations
128
 * @returns New instant after adding the period
129
 */
130
fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant
131

132
/**
133
 * Subtract a date/time period from this instant in the specified time zone
134
 * @param period The period to subtract
135
 * @param timeZone Time zone for calendar-aware calculations
136
 * @returns New instant after subtracting the period
137
 */
138
fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant
139

140
/**
141
 * Add a value of the specified unit to this instant
142
 * @param value Amount to add
143
 * @param unit The date/time unit (DAY, MONTH, YEAR, etc.)
144
 * @param timeZone Time zone for calendar-aware calculations
145
 * @returns New instant after adding the value
146
 */
147
fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant
148
fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant
149

150
/**
151
 * Subtract a value of the specified unit from this instant
152
 * @param value Amount to subtract
153
 * @param unit The date/time unit
154
 * @param timeZone Time zone for calendar-aware calculations
155
 * @returns New instant after subtracting the value
156
 */
157
fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant
158
fun Instant.minus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant
159
```
160

161
**Usage Examples:**
162

163
```kotlin
164
import kotlinx.datetime.*
165
import kotlin.time.Clock
166

167
val now = Clock.System.now()
168
val timeZone = TimeZone.currentSystemDefault()
169

170
// Add a complex period
171
val period = DateTimePeriod(months = 3, days = 15, hours = 2)
172
val future = now.plus(period, timeZone)
173

174
// Add simple units
175
val nextWeek = now.plus(1, DateTimeUnit.WEEK, timeZone)
176
val nextMonth = now.plus(1, DateTimeUnit.MONTH, timeZone)
177
val nextYear = now.plus(1, DateTimeUnit.YEAR, timeZone)
178
```
179

180
### Period Calculations
181

182
Calculate periods between instants in specific time zones.
183

184
```kotlin { .api }
185
/**
186
 * Calculate the number of whole units between this instant and another
187
 * @param other The target instant
188
 * @param unit The unit to measure in
189
 * @param timeZone Time zone for calendar-aware calculations
190
 * @returns Number of whole units between the instants
191
 */
192
fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long
193

194
/**
195
 * Calculate the number of whole days between this instant and another
196
 * @param other The target instant
197
 * @param timeZone Time zone for calendar-aware calculations
198
 * @returns Number of whole days
199
 */
200
fun Instant.daysUntil(other: Instant, timeZone: TimeZone): Int
201

202
/**
203
 * Calculate the number of whole months between this instant and another
204
 * @param other The target instant
205
 * @param timeZone Time zone for calendar-aware calculations
206
 * @returns Number of whole months
207
 */
208
fun Instant.monthsUntil(other: Instant, timeZone: TimeZone): Int
209

210
/**
211
 * Calculate the number of whole years between this instant and another
212
 * @param other The target instant
213
 * @param timeZone Time zone for calendar-aware calculations
214
 * @returns Number of whole years
215
 */
216
fun Instant.yearsUntil(other: Instant, timeZone: TimeZone): Int
217

218
/**
219
 * Calculate the period between this instant and another
220
 * @param other The target instant
221
 * @param timeZone Time zone for calendar-aware calculations
222
 * @returns DateTimePeriod representing the difference
223
 */
224
fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod
225
```
226

227
**Usage Examples:**
228

229
```kotlin
230
import kotlinx.datetime.*
231
import kotlin.time.Clock
232

233
val start = Clock.System.now()
234
val timeZone = TimeZone.currentSystemDefault()
235

236
// Simulate some time later
237
val end = start.plus(100, DateTimeUnit.DAY, timeZone)
238

239
// Calculate differences
240
val days = start.daysUntil(end, timeZone)
241
val months = start.monthsUntil(end, timeZone)
242
val period = start.periodUntil(end, timeZone)
243

244
println("Days: $days")
245
println("Months: $months") 
246
println("Period: $period")
247
```
248

249
### Instant Formatting
250

251
Format instants as strings using the formatting system.
252

253
```kotlin { .api }
254
/**
255
 * Format this instant using the specified format and offset
256
 * @param format The date/time format to use
257
 * @param offset The UTC offset to apply during formatting (defaults to UtcOffset.ZERO)
258
 * @returns Formatted string representation
259
 */
260
fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String
261
```
262

263
### Instant Parsing
264

265
Parse instants from strings using various formats.
266

267
```kotlin { .api }
268
/**
269
 * Parse a string representation of an instant
270
 * @param input The string to parse
271
 * @param format The date/time format to use for parsing
272
 * @returns Parsed Instant
273
 * @throws IllegalArgumentException if parsing fails
274
 */
275
fun Instant.Companion.parse(
276
    input: CharSequence,
277
    format: DateTimeFormat<DateTimeComponents>
278
): Instant
279
```
280

281
**Usage Examples:**
282

283
```kotlin
284
import kotlinx.datetime.*
285
import kotlinx.datetime.format.*
286

287
// Parse ISO 8601 format
288
val instant = Instant.parse(
289
    "2023-12-25T15:30:00Z",
290
    DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
291
)
292

293
// Format with custom offset
294
val formatted = instant.format(
295
    DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET,
296
    UtcOffset(hours = -5)
297
)
298
println("Formatted: $formatted")
299
```
300

301
### Current Date in Time Zone
302

303
Get the current date in a specific time zone.
304

305
```kotlin { .api }
306
/**
307
 * Get today's date in the specified time zone
308
 * @param timeZone The time zone to get the date for
309
 * @returns LocalDate representing today in the time zone
310
 */
311
fun Clock.todayIn(timeZone: TimeZone): LocalDate
312
```
313

314
**Usage Example:**
315

316
```kotlin
317
import kotlinx.datetime.*
318
import kotlin.time.Clock
319

320
val nyTimeZone = TimeZone.of("America/New_York")
321
val today = Clock.System.todayIn(nyTimeZone)
322
println("Today in New York: $today")
323
```
324

325
### Deprecated Instant Compatibility
326

327
For compatibility with older versions, conversion functions between deprecated and current Instant types.
328

329
```kotlin { .api }
330
/**
331
 * Convert deprecated kotlinx.datetime.Instant to kotlin.time.Instant
332
 * @deprecated Use kotlin.time.Instant directly instead
333
 */
334
@Deprecated("kotlinx.datetime.Instant is superseded by kotlin.time.Instant")
335
fun kotlinx.datetime.Instant.toStdlibInstant(): kotlin.time.Instant
336

337
/**
338
 * Convert kotlin.time.Instant to deprecated kotlinx.datetime.Instant  
339
 * @deprecated Use kotlin.time.Instant directly instead
340
 */
341
fun kotlin.time.Instant.toDeprecatedInstant(): kotlinx.datetime.Instant
342
```