Instant and Time Representation

/**
 * A point in time (from kotlin.time)
 * Represents a specific moment in time on the UTC-SLS time scale
 */
class Instant : Comparable<Instant> {
    /** Seconds since epoch (1970-01-01T00:00:00Z) */
    val epochSeconds: Long
    
    /** Additional nanoseconds within the second (0-999,999,999) */
    val nanosecondsOfSecond: Int
    
    /** Add a duration to this instant */
    fun plus(duration: Duration): Instant
    
    /** Subtract a duration from this instant */
    fun minus(duration: Duration): Instant
    
    /** Calculate duration between this and another instant */
    fun minus(other: Instant): Duration
    
    /** Compare this instant with another */
    override fun compareTo(other: Instant): Int
}

import kotlin.time.Clock
import kotlin.time.Duration.Companion.seconds

val now = Clock.System.now()
val later = now.plus(30.seconds)
val duration = later.minus(now)
println("Duration: ${duration.inWholeSeconds} seconds")

/**
 * Source of current time information (from kotlin.time)
 */
interface Clock {
    /** Get the current instant */
    fun now(): Instant
    
    companion object {
        /** System clock implementation */
        val System: Clock
    }
}

/**
 * Convert instant to local date/time in specified time zone
 * @param timeZone The time zone for conversion
 * @returns LocalDateTime in the specified time zone
 */
fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime

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

/**
 * Get the UTC offset for this instant in the specified time zone
 * @param timeZone The time zone to check
 * @returns UtcOffset for this instant in the time zone
 */
fun Instant.offsetIn(timeZone: TimeZone): UtcOffset

import kotlinx.datetime.*
import kotlin.time.Clock

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

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

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

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

/**
 * Add a date/time period to this instant in the specified time zone
 * @param period The period to add (years, months, days, hours, etc.)
 * @param timeZone Time zone for calendar-aware calculations
 * @returns New instant after adding the period
 */
fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant

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

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

/**
 * Subtract a value of the specified unit from this instant
 * @param value Amount to subtract
 * @param unit The date/time unit
 * @param timeZone Time zone for calendar-aware calculations
 * @returns New instant after subtracting the value
 */
fun Instant.minus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant
fun Instant.minus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant

import kotlinx.datetime.*
import kotlin.time.Clock

val now = Clock.System.now()
val timeZone = TimeZone.currentSystemDefault()

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

// Add simple units
val nextWeek = now.plus(1, DateTimeUnit.WEEK, timeZone)
val nextMonth = now.plus(1, DateTimeUnit.MONTH, timeZone)
val nextYear = now.plus(1, DateTimeUnit.YEAR, timeZone)

/**
 * Calculate the number of whole units between this instant and another
 * @param other The target instant
 * @param unit The unit to measure in
 * @param timeZone Time zone for calendar-aware calculations
 * @returns Number of whole units between the instants
 */
fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long

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

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

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

/**
 * Calculate the period between this instant and another
 * @param other The target instant
 * @param timeZone Time zone for calendar-aware calculations
 * @returns DateTimePeriod representing the difference
 */
fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod

import kotlinx.datetime.*
import kotlin.time.Clock

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

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

// Calculate differences
val days = start.daysUntil(end, timeZone)
val months = start.monthsUntil(end, timeZone)
val period = start.periodUntil(end, timeZone)

println("Days: $days")
println("Months: $months") 
println("Period: $period")

/**
 * Format this instant using the specified format and offset
 * @param format The date/time format to use
 * @param offset The UTC offset to apply during formatting (defaults to UtcOffset.ZERO)
 * @returns Formatted string representation
 */
fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String

/**
 * Parse a string representation of an instant
 * @param input The string to parse
 * @param format The date/time format to use for parsing
 * @returns Parsed Instant
 * @throws IllegalArgumentException if parsing fails
 */
fun Instant.Companion.parse(
    input: CharSequence,
    format: DateTimeFormat<DateTimeComponents>
): Instant

import kotlinx.datetime.*
import kotlinx.datetime.format.*

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

// Format with custom offset
val formatted = instant.format(
    DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET,
    UtcOffset(hours = -5)
)
println("Formatted: $formatted")

/**
 * Get today's date in the specified time zone
 * @param timeZone The time zone to get the date for
 * @returns LocalDate representing today in the time zone
 */
fun Clock.todayIn(timeZone: TimeZone): LocalDate

import kotlinx.datetime.*
import kotlin.time.Clock

val nyTimeZone = TimeZone.of("America/New_York")
val today = Clock.System.todayIn(nyTimeZone)
println("Today in New York: $today")

/**
 * Convert deprecated kotlinx.datetime.Instant to kotlin.time.Instant
 * @deprecated Use kotlin.time.Instant directly instead
 */
@Deprecated("kotlinx.datetime.Instant is superseded by kotlin.time.Instant")
fun kotlinx.datetime.Instant.toStdlibInstant(): kotlin.time.Instant

/**
 * Convert kotlin.time.Instant to deprecated kotlinx.datetime.Instant  
 * @deprecated Use kotlin.time.Instant directly instead
 */
fun kotlin.time.Instant.toDeprecatedInstant(): kotlinx.datetime.Instant