Verdandi/com.github.abraga.verdandi.api.model/VerdandiMoment

VerdandiMoment

@Serializable

data class VerdandiMoment : Comparable<VerdandiMoment>

Represents a specific instant in time with optional timezone context.

A VerdandiMoment wraps a Unix epoch (milliseconds since 1970-01-01T00:00:00Z) and exposes rich operations for adjustment, formatting, comparison, and timezone conversion. Instances are created through the Verdandi entry point.

Timezone awareness

By default a moment uses the device timezone. Use inTimeZone to project the same instant into a different timezone — the epoch stays identical, but component values (hour, day, offset, etc.) reflect the target zone:

val utc = Verdandi.from("2025-06-15T12:00:00Z")
val tokyo = utc inTimeZone VerdandiTimeZone.of("Asia/Tokyo")
tokyo.component.hour  // 21
utc.inMilliseconds == tokyo.inMilliseconds // true

Adjustments

The adjust DSL allows natural-language date arithmetic:

val tomorrow = moment adjust { add one day }
val startOfDay = moment adjust { at startOf day }
val shifted = moment adjust { add three hours }

Formatting

val iso = moment format { iso.date }       // "2025-06-15"
val text = moment format "dd/MM/yyyy HH:mm" // "15/06/2025 14:30"

Equality and comparison

Two moments are equal when they represent the same instant (same epoch), regardless of timezone context. compareTo also uses epoch-only ordering.

Properties

component

val component: VerdandiMomentComponent

Decomposed date/time components (year, month, day, hour, minute, second, millisecond, UTC offset) resolved in this moment's timezone context.

inMilliseconds

val inMilliseconds: Long

The Unix epoch in milliseconds since 1970-01-01T00:00:00Z.

Functions

adjust

infix fun adjust(block: VerdandiAdjustScope.() -> Unit): VerdandiMoment

Adjusts this moment using the Verdandi DSL.

compareTo

open operator override fun compareTo(other: VerdandiMoment): Int

operator fun compareTo(milliseconds: Long): Int

durationUntil

fun durationUntil(other: VerdandiMoment): DateTimeDuration

Computes the calendar-aware duration between this moment and other.

equals

open operator override fun equals(other: Any?): Boolean

format

infix fun format(block: VerdandiFormatScope.() -> VerdandiFormatPattern): String

Formats this moment using the chain-based DSL.

infix fun format(pattern: String): String

Formats this moment using a pattern string.

hashCode

open override fun hashCode(): Int

inTimeZone

infix fun inTimeZone(timeZone: VerdandiTimeZone): VerdandiMoment

Projects this instant into the given timeZone.

isAfter

infix fun isAfter(other: VerdandiMoment): Boolean

Returns true if this moment is strictly after other.

isBefore

infix fun isBefore(other: VerdandiMoment): Boolean

Returns true if this moment is strictly before other.

isBetween

fun isBetween(interval: VerdandiInterval): Boolean

Returns true if this moment falls within interval (start-inclusive, end-exclusive).

fun isBetween(start: VerdandiMoment, end: VerdandiMoment): Boolean

Returns true if this moment falls within [start, end).

isSameDayAs

infix fun isSameDayAs(other: VerdandiMoment): Boolean

Returns true if this moment and other fall on the same calendar day in their respective timezone contexts.

isSameMonthAs

infix fun isSameMonthAs(other: VerdandiMoment): Boolean

Returns true if this moment and other fall in the same calendar month in their respective timezone contexts.

isSameYearAs

infix fun isSameYearAs(other: VerdandiMoment): Boolean

Returns true if this moment and other fall in the same calendar year in their respective timezone contexts.

isToday

fun isToday(): Boolean

Returns true if this moment falls on today's calendar date.

isTomorrow

fun isTomorrow(): Boolean

Returns true if this moment falls on tomorrow's calendar date.

isWeekday

fun isWeekday(): Boolean

Returns true if this moment falls on a weekday (Monday–Friday).

isWeekend

fun isWeekend(): Boolean

Returns true if this moment falls on a Saturday or Sunday.

minus

operator fun minus(dateDuration: DateDuration): VerdandiMoment

operator fun minus(dateTimeDuration: DateTimeDuration): VerdandiMoment

operator fun minus(duration: Duration): VerdandiMoment

plus

operator fun plus(dateDuration: DateDuration): VerdandiMoment

operator fun plus(dateTimeDuration: DateTimeDuration): VerdandiMoment

operator fun plus(duration: Duration): VerdandiMoment

rangeTo

operator fun rangeTo(other: VerdandiMoment): VerdandiInterval

Creates a VerdandiInterval from this moment to other.

relativeTo

fun relativeTo(other: VerdandiMoment, nowThreshold: Duration = 59.seconds): VerdandiRelativeMoment

Computes the relative description of this moment compared to other.

relativeToNow

fun relativeToNow(nowThreshold: Duration = 59.seconds): VerdandiRelativeMoment

Computes the relative description of this moment compared to Verdandi.now.

toInstant

fun VerdandiMoment.toInstant(): Instant

toLocalDate

fun VerdandiMoment.toLocalDate(): LocalDate

toLocalDateTime

fun VerdandiMoment.toLocalDateTime(): LocalDateTime

toLocalTime

fun VerdandiMoment.toLocalTime(): LocalTime

toNSDate

fun VerdandiMoment.toNSDate(): NSDate

toOffsetDateTime

fun VerdandiMoment.toOffsetDateTime(): OffsetDateTime

toString

open override fun toString(): String

toZonedDateTime

fun VerdandiMoment.toZonedDateTime(): ZonedDateTime

wasYesterday

fun wasYesterday(): Boolean

Returns true if this moment falls on yesterday's calendar date.