Skip to content

Commit

Permalink
Rename Unix epoch-related properties/functions for consistency (#75)
Browse files Browse the repository at this point in the history
  • Loading branch information
@erikc5000
erikc5000 committed Jun 1, 2020
2 parents 5de90c5 + 7dd8e29 commit 42a49d7
Show file tree
Hide file tree
Showing 23 changed files with 538 additions and 239 deletions.
37 changes: 23 additions & 14 deletions core/src/commonMain/kotlin/io/islandtime/Date.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -276,42 +276,51 @@ class Date(
) = Date(year, dayOfYear)

companion object {
val MIN = Date(Year.MIN_VALUE, 1)
val MAX = Date(Year.MAX_VALUE, Year.MAX.lastDay)
/**
* The smallest supported [Date], which can be used as a "far past" sentinel.
*/
val MIN = Date(Year.MIN_VALUE, Month.JANUARY, 1)

/**
* Create the [Date] that falls a certain number of days from the Unix epoch of 1970-01-01
* The largest supported [Date], which can be used as a "far future" sentinel.
*/
val MAX = Date(Year.MAX_VALUE, Month.DECEMBER, 31)

/**
* Create a [Date] from a duration of days relative to the Unix epoch of 1970-01-01.
* @param days the number of days relative to the Unix epoch
* @return a new [Date]
* @throws DateTimeException if outside of the supported date range
*/
fun fromDaysSinceUnixEpoch(days: LongDays): Date {
return fromUnixEpochDay(days.value)
}
fun fromDaysSinceUnixEpoch(days: LongDays): Date = fromDayOfUnixEpoch(days.value)

/**
* Create a [Date] from the day of the Unix epoch.
* @param day the day of the Unix epoch
* @return a new [Date]
* @throws DateTimeException if outside of the supported date range
*/
fun fromUnixEpochDay(day: Long): Date {
fun fromDayOfUnixEpoch(day: Long): Date {
if (day !in -365243219162L..365241780471L) {
throw DateTimeException("The Unix epoch day '$day' is outside the supported range")
throw DateTimeException("The day '$day' of the Unix epoch is outside the supported range")
}

return withComponentizedDayOfUnixEpoch(day) { year, month, dayOfMonth ->
Date(year, month, dayOfMonth)
}
}

@Deprecated(
"Use fromDayOfUnixEpoch() instead.",
ReplaceWith("Date.fromDayOfUnixEpoch(day)"),
DeprecationLevel.WARNING
)
fun fromUnixEpochDay(day: Long): Date = fromDayOfUnixEpoch(day)
}
}

/**
* Create a [Date] from a year and day of year
* @param year the year
* @param dayOfYear the day of the calendar year
* @return a new [Date]
* @throws DateTimeException if the year or day of year are invalid
*/
@Suppress("FunctionName")
Expand All @@ -330,9 +339,9 @@ fun Date(year: Int, dayOfYear: Int): Date {
* Convert an [Instant] into the [Date] represented by it at a particular UTC offset.
*/
fun Instant.toDateAt(offset: UtcOffset): Date {
val adjustedSeconds = unixEpochSecond + offset.totalSeconds.value
val unixEpochDay = adjustedSeconds floorDiv SECONDS_PER_DAY
return Date.fromUnixEpochDay(unixEpochDay)
val adjustedSeconds = secondOfUnixEpoch + offset.totalSeconds.value
val dayOfUnixEpoch = adjustedSeconds floorDiv SECONDS_PER_DAY
return Date.fromDayOfUnixEpoch(dayOfUnixEpoch)
}

/**
Expand Down
125 changes: 87 additions & 38 deletions core/src/commonMain/kotlin/io/islandtime/DateTime.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -508,22 +508,28 @@ class DateTime(
* value, so 1 nanosecond before the Unix epoch will be at a distance of 1 second.
*
* @param offset the offset from UTC
* @see nanoOfSecondsSinceUnixEpoch
* @see unixEpochSecondAt
* @see additionalNanosecondsSinceUnixEpoch
*/
fun secondsSinceUnixEpochAt(offset: UtcOffset): LongSeconds {
return (date.daysSinceUnixEpoch.inSecondsUnchecked.value +
time.secondsSinceStartOfDay.value -
offset.totalSeconds.value).seconds
}

@Deprecated(
"Use additionalNanosecondsSinceUnixEpoch instead.",
ReplaceWith("this.additionalNanosecondsSinceUnixEpoch"),
DeprecationLevel.WARNING
)
val nanoOfSecondsSinceUnixEpoch: IntNanoseconds
get() = additionalNanosecondsSinceUnixEpoch

/**
* The number of additional nanoseconds that should be applied on top of the number of seconds since the Unix epoch
* returned by [secondsSinceUnixEpochAt].
* @see secondsSinceUnixEpochAt
* @see unixEpochNanoOfSecond
*/
val nanoOfSecondsSinceUnixEpoch: IntNanoseconds
val additionalNanosecondsSinceUnixEpoch: IntNanoseconds
get() = nanosecond.nanoseconds

/**
Expand All @@ -537,34 +543,48 @@ class DateTime(
offset.totalSeconds.inMilliseconds.value).milliseconds
}

@Deprecated(
"Use secondOfUnixEpochAt() instead.",
ReplaceWith("this.secondOfUnixEpochAt(offset)"),
DeprecationLevel.WARNING
)
fun unixEpochSecondAt(offset: UtcOffset): Long = secondOfUnixEpochAt(offset)

/**
* The second of the Unix epoch.
*
* @param offset the offset from UTC
* @see nanoOfSecondsSinceUnixEpoch
* @see unixEpochSecondAt
* @see additionalNanosecondsSinceUnixEpoch
*/
fun unixEpochSecondAt(offset: UtcOffset): Long = secondsSinceUnixEpochAt(offset).value

/**
* The nanosecond of the second of the Unix Epoch.
* @see nanoOfSecondsSinceUnixEpoch
* @see unixEpochSecondAt
*/
val unixEpochNanoOfSecond: Int get() = nanosecond
fun secondOfUnixEpochAt(offset: UtcOffset): Long = secondsSinceUnixEpochAt(offset).value

@Deprecated(
"Use nanosecond instead.",
ReplaceWith("this.nanosecond"),
DeprecationLevel.WARNING
)
val unixEpochNanoOfSecond: Int
get() = nanosecond

@Deprecated(
"Use millisecondOfUnixEpoch() instead.",
ReplaceWith("this.millisecondOfUnixEpochAt(offset)"),
DeprecationLevel.WARNING
)
fun unixEpochMillisecondAt(offset: UtcOffset): Long = millisecondOfUnixEpochAt(offset)

/**
* The millisecond of the Unix epoch.
* @param offset the offset from UTC
*/
fun unixEpochMillisecondAt(offset: UtcOffset): Long = millisecondsSinceUnixEpochAt(offset).value
fun millisecondOfUnixEpochAt(offset: UtcOffset): Long = millisecondsSinceUnixEpochAt(offset).value

/**
* The [Instant] represented by this date-time at a particular offset from UTC.
* @param offset the offset from UTC
*/
fun instantAt(offset: UtcOffset): Instant {
return Instant.fromUnixEpochSecond(unixEpochSecondAt(offset), nanosecond)
return Instant.fromSecondOfUnixEpoch(secondOfUnixEpochAt(offset), nanosecond)
}

companion object {
Expand All @@ -578,42 +598,71 @@ class DateTime(
*/
val MAX = DateTime(Date.MAX, Time.MAX)

fun fromUnixEpochMillisecond(millisecond: Long, offset: UtcOffset): DateTime {
return fromMillisecondsSinceUnixEpoch(millisecond.milliseconds, offset)
}

fun fromMillisecondsSinceUnixEpoch(milliseconds: LongMilliseconds, offset: UtcOffset): DateTime {
val localMilliseconds = milliseconds + offset.totalSeconds
val localEpochDays = (localMilliseconds.value floorDiv MILLISECONDS_PER_DAY).days
/**
* Create a [DateTime] from a duration of milliseconds relative to the Unix epoch at [offset].
*/
fun fromMillisecondsSinceUnixEpoch(millisecondsSinceUnixEpoch: LongMilliseconds, offset: UtcOffset): DateTime {
val localMilliseconds = millisecondsSinceUnixEpoch + offset.totalSeconds
val localEpochDay = localMilliseconds.value floorDiv MILLISECONDS_PER_DAY
val nanosecondOfDay =
(localMilliseconds.value floorMod MILLISECONDS_PER_DAY).milliseconds.inNanosecondsUnchecked.value
val date = Date.fromDaysSinceUnixEpoch(localEpochDays)
val date = Date.fromDayOfUnixEpoch(localEpochDay)
val time = Time.fromNanosecondOfDay(nanosecondOfDay)
return DateTime(date, time)
}

fun fromUnixEpochSecond(second: Long, nanosecondAdjustment: Int = 0, offset: UtcOffset): DateTime {
return fromSecondsSinceUnixEpoch(second.seconds, nanosecondAdjustment.nanoseconds, offset)
}

/**
* Create the [DateTime] that falls a given number of seconds relative to the Unix epoch, plus some number of
* additional nanoseconds
* Create a [DateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, with some
* number of additional nanoseconds added to it.
*/
fun fromSecondsSinceUnixEpoch(
seconds: LongSeconds,
secondsSinceUnixEpoch: LongSeconds,
nanosecondAdjustment: IntNanoseconds = 0.nanoseconds,
offset: UtcOffset
): DateTime {
val adjustedSeconds = seconds + (nanosecondAdjustment.value floorDiv NANOSECONDS_PER_SECOND).seconds
val nanosecondOfDay = nanosecondAdjustment.value floorMod NANOSECONDS_PER_SECOND
val adjustedSeconds =
secondsSinceUnixEpoch + (nanosecondAdjustment.value floorDiv NANOSECONDS_PER_SECOND).seconds
val nanosecond = nanosecondAdjustment.value floorMod NANOSECONDS_PER_SECOND
val localSeconds = adjustedSeconds + offset.totalSeconds
val localEpochDays = (localSeconds.value floorDiv SECONDS_PER_DAY).days
val localEpochDay = (localSeconds.value floorDiv SECONDS_PER_DAY)
val secondOfDay = (localSeconds.value floorMod SECONDS_PER_DAY).toInt()
val date = Date.fromDaysSinceUnixEpoch(localEpochDays)
val time = Time.fromSecondOfDay(secondOfDay, nanosecondOfDay)
val date = Date.fromDayOfUnixEpoch(localEpochDay)
val time = Time.fromSecondOfDay(secondOfDay, nanosecond)
return DateTime(date, time)
}

/**
* Create a [DateTime] from the millisecond of the Unix epoch at [offset].
*/
fun fromMillisecondOfUnixEpoch(millisecond: Long, offset: UtcOffset): DateTime {
return fromMillisecondsSinceUnixEpoch(millisecond.milliseconds, offset)
}

/**
* Create a [DateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of the
* second.
*/
fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int = 0, offset: UtcOffset): DateTime {
return fromSecondsSinceUnixEpoch(second.seconds, nanosecond.nanoseconds, offset)
}

@Deprecated(
"Use fromMillisecondOfUnixEpoch() instead.",
ReplaceWith("DateTime.fromMillisecondOfUnixEpoch(millisecond, offset)"),
DeprecationLevel.WARNING
)
fun fromUnixEpochMillisecond(millisecond: Long, offset: UtcOffset): DateTime {
return fromMillisecondOfUnixEpoch(millisecond, offset)
}

@Deprecated(
"Use fromSecondOfUnixEpoch() instead.",
ReplaceWith("DateTime.fromSecondOfUnixEpoch(second, nanosecondAdjustment, offset)"),
DeprecationLevel.WARNING
)
fun fromUnixEpochSecond(second: Long, nanosecondAdjustment: Int = 0, offset: UtcOffset): DateTime {
return fromSecondOfUnixEpoch(second, nanosecondAdjustment, offset)
}
}
}

Expand All @@ -630,10 +679,10 @@ fun Date.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): D
}

/**
* Convert an instant into a [DateTime] at a particular offset from UTC.
* Convert to a [DateTime] at a particular offset from UTC.
*/
fun Instant.toDateTimeAt(offset: UtcOffset): DateTime {
return DateTime.fromUnixEpochSecond(unixEpochSecond, unixEpochNanoOfSecond, offset)
return DateTime.fromSecondOfUnixEpoch(secondOfUnixEpoch, nanosecond, offset)
}

/**
Expand Down
Loading

0 comments on commit 42a49d7

Please sign in to comment.