Duration — ano ito, pagkalkula ng tagal sa Android

Ano ang Duration?

Duration — ay isang klase na nagmomodelo ng dami ng oras sa mga segundo at nanosegundo. Ito ay kumakatawan sa tagal na nakabatay sa oras, ibig sabihin, ang pisikal na bilang ng mga segundo, hindi nakatali sa kalendaryo. Ang Duration ay maaaring ilarawan bilang “125 minuto” o “2 oras 5 minuto” — hindi tulad ng Period, na sasabihing “2 buwan”.

Ang panloob na representasyon ng Duration ay binubuo ng dalawang field: long seconds (segundo) at int nanos (nanosegundo, mula 0 hanggang 999999999). Ang halaga ay maaaring negatibo — ito ay nangangahulugang tagal “pabalik” sa oras. Ang maximum na halaga ay ±31557014167219200 segundo.

Ayon sa Baeldung (2024), ang Duration ay ang pangunahing klase para sa pagkalkula ng tagal ng operasyon, pagtatakda ng mga timeout at pagsukat ng pagganap. Ang Duration ay immutable at thread-safe, na nagpapahintulot sa paggamit nito sa multi-thread na kapaligiran nang walang synchronisation.

Ang klase ay nagpapatupad ng mga interface na Comparable, TemporalAmount at TemporalUnit. Ang TemporalAmount ay nagpapahintulot sa paggamit ng Duration sa mga pamamaraang plus/minus ng mga klase na LocalTime, LocalDateTime, Instant at ZonedDateTime.

Duration vs Period: ano ang pagkakaiba?

Ang pangunahing pagkakaiba — Duration ay sumusukat ng eksaktong bilang ng mga segundo (time-based), habang ang Period ay sumusukat ng mga yunit ng kalendaryo (date-based): taon, buwan, araw. Sinasabi ng Duration: “86400 segundo ang lumipas”. Sinasabi ng Period: “1 araw ang lumipas”. Ang pagkakaiba ay lumilitaw sa paglipat sa daylight saving time — 1 araw sa Period ay palaging katumbas ng 1 araw sa kalendaryo, habang ang 86400 segundo sa Duration ay maaaring tumugma sa 23 o 25 oras sa DST.

Ang Duration ay ginagamit para sa pagsukat ng pisikal na oras: mga timeout ng koneksyon, oras ng pagpapatupad ng kahilingan, agwat sa pagitan ng dalawang Instant. Ang Period ay ginagamit para sa mga kalkulasyon ng kalendaryo: edad ng isang tao (Period.between(petsaNgKapanganakan, ngayon)), panahon ng bisa ng kontrata.

Ang Duration ay gumagana sa mga segundo at nanosegundo, kaya maaari itong hatiin sa mga bahagi (oras, minuto). Ang Period ay gumagana sa mga taon, buwan at araw — hindi mahahati na mga yunit ng kalendaryo. Ayon sa Oracle Java Tutorial (2024), ang pagpili sa pagitan ng Duration at Period ay depende sa uri ng gawain: eksaktong oras vs mga petsa ng kalendaryo.

Paglikha ng Duration

Ang pinakakaraniwang paraan — Duration.between(Temporal start, Temporal end). Ang Temporal ay maaaring Instant, LocalTime, LocalDateTime, ZonedDateTime — anumang uri na nagpapatupad ng Temporal. Ang pamamaraan ay nagbabalik ng Duration na kumakatawan sa pagkakaibang start - end (maaaring negatibo).

Mga static na factory method: Duration.ofSeconds(long), ofMinutes(long), ofHours(long), ofDays(long), ofMillis(long), ofNanos(long). Mayroon ding of(long amount, TemporalUnit unit) para sa mga arbitraryong yunit — ChronoUnit.HOURS, ChronoUnit.MINUTES at iba pa.

Ang pamamaraang parse(CharSequence) ay tumatanggap ng string sa format na ISO-8601: “PT1H30M” (1 oras 30 minuto), “PT45S” (45 segundo), “P2DT3H” (2 araw 3 oras). Ang string ay palaging nagsisimula sa “PT” (Period of Time).

val betweenMoments = Duration.between(
    Instant.parse("2026-07-21T10:00:00Z"),
    Instant.parse("2026-07-21T14:30:00Z")
)

val fromMinutes = Duration.ofMinutes(90)
val fromHours = Duration.ofHours(2)
val parsed = Duration.parse("PT1H30M")

Aritmetika gamit ang Duration

Sinusuportahan ng Duration ang buong hanay ng mga aritmetikong operasyon. Ang mga pamamaraang plus(Duration) at minus(Duration) ay nagdaragdag o nagbabawas ng ibang tagal. Ang mga pamamaraang plusDays(), plusHours(), plusMinutes(), plusSeconds(), plusMillis(), plusNanos() — para sa tumpak na pagdaragdag ng mga yunit.

Para sa pagpaparami at paghahati, ginagamit ang multipliedBy(long) at dividedBy(long). Ang Duration.multipliedBy(2) ay nagdodoble ng tagal. Ang Duration.dividedBy(3) ay naghahati sa tatlong bahagi na may rounding pababa. Ang pamamaraang negated() ay binabaligtad ang sign — ang positive ay nagiging negative at vice versa.

Ang pamamaraang abs() ay nagbabalik ng Duration na may absolute (positive) na halaga. Ang isNegative() at isZero() — mga pagsusuri. Ang toDays(), toHours(), toMinutes(), toSeconds(), toMillis(), toNanos() — conversion sa kaukulang mga yunit.

val oneHour = Duration.ofHours(1)
val twoHours = oneHour.plus(Duration.ofMinutes(60))
val halfHour = oneHour.dividedBy(2)

val minutes = twoHours.toMinutes()
val absDuration = (Duration.ofHours(-1)).abs()

Paghahambing ng Duration

Ang Duration ay nagpapatupad ng interface na Comparable, na nagpapahintulot sa natural na paghahambing ng mga tagal. Ang pamamaraang compareTo() ay nagbabalik ng negatibong numero, zero o positibong numero. Ang mga pamamaraang isNegative() at isZero() — mabilis na pagsusuri. Para sa tahasang paghahambing gamitin ang equals() — dalawang Duration ay pantay kung may parehong segundo at nanosegundo.

Dahil ang Duration ay maaaring negatibo, ang paghahambing na “mas malaki” o “mas maliit” ay gumagana na isinasaalang-alang ang sign. -5 minuto ay mas maliit kaysa 2 minuto. Ang pamamaraang abs() ay kapaki-pakinabang kung kailangan mong ihambing ang “absolute” na mga haba anuman ang direksyon.

Sa Kotlin, sinusuportahan ng Duration ang mga operator ng paghahambing sa pamamagitan ng operator overloading: a < b, a > b, a <= b. Gayundin, ang plus at minus ay magagamit bilang mga operator: a + b, a - b.

val short = Duration.ofMinutes(5)
val long = Duration.ofMinutes(10)

if (short < long) {
    Log.d("Duration", "5 min ay mas mababa sa 10")
}

val negative = Duration.ofMinutes(-3)
Log.d("Duration", "Negatibo: ${negative.isNegative()}")

Duration sa mga totoong gawain sa Android

Unang halimbawa — pag-setup ng pana-panahong synchronisation sa server. Duration ay ginagamit para sa pagkalkula ng agwat sa pagitan ng mga synchronisation at pagsusuri kung ang limitasyon ng oras na walang update ay nalampasan.

data class SyncConfig(
    val interval: Duration = Duration.ofMinutes(15),
    val retryDelay: Duration = Duration.ofSeconds(30)
)

fun calculateNextSync(
    lastSync: Instant,
    config: SyncConfig
): Duration {
    val elapsed = Duration.between(lastSync, Instant.now())
    return config.interval.minus(elapsed)
        .coerceAtLeast(Duration.ZERO)
}

Ikalawang halimbawa — pagsukat ng oras ng pagpapatupad ng operasyon para sa logging ng pagganap.

fun measureExecution(
    tag: String,
    block: () -> Unit
) {
    val start = Instant.now()
    block()
    val duration = Duration.between(start, Instant.now())
    Log.d(tag, "Na-execute sa ${duration.toMillis()} ms")
}

Ikatlong halimbawa — pagkalkula ng natitirang oras ng timer (halimbawa, para sa countdown hanggang sa katapusan ng promo).

class CountdownTimer(
    private val expiresAt: Instant
) {
    fun getRemainingTime(): Duration {
        val remaining = Duration.between(
            Instant.now(), expiresAt
        )
        return remaining.coerceAtLeast(Duration.ZERO)
    }

    fun isExpired(): Boolean = getRemainingTime() == Duration.ZERO
}

Pag-convert ng Duration sa string

Ang pamamaraang toString() ay nagbabalik ng Duration sa ISO-8601 na format: “PT1H30M” (1 oras 30 minuto), “PT45.5S” (45.5 segundo). Ang format na ito ay maginhawa para sa palitan ng makina, ngunit hindi para sa pagpapakita sa gumagamit.

Para sa format na nababasa ng tao, gamitin ang toDays(), toHours(), toMinutes(), toSeconds() na may manu-manong pagbuo ng string. Halimbawa: “${days} a ${hours} o ${minutes} min”. Tandaan na ang toHours() ay nagbabalik ng kabuuang bilang ng mga oras, hindi ang mga oras sa loob ng isang araw.

Para sa paghahati ng Duration sa mga bahagi, ginagamit ang formula: val hours = duration.toHours(); val minutes = duration.toMinutes() % 60; val seconds = duration.seconds % 60. Ayon sa Apache Commons Lang (2024), ang library na DurationFormatUtils ay nagbibigay ng mga karagdagang kakayahan sa pag-format.

fun formatDuration(duration: Duration): String {
    val hours = duration.toHours()
    val minutes = duration.toMinutes() % 60
    val seconds = duration.seconds % 60

    return buildString {
        if (hours > 0) append("${hours} h ")
        if (minutes > 0) append("${minutes} min ")
        append("${seconds} sec")
    }
}

Mga karaniwang pagkakamali

Unang pagkakamali — pagkalito sa pagitan ng Duration at Period kapag nagtatrabaho sa mga petsa. Sinusukat ng Duration ang mga segundo, kaya ang Duration.ofDays(1) ay palaging 24 na oras (86400 segundo), anuman ang paglipat sa daylight saving time. Kung kailangan mo ng araw ng kalendaryo, gamitin ang Period.ofDays(1).

Ikalawang pagkakamali — pagkawala ng mga nanosegundo sa conversion. Ang Duration ay maaaring mag-imbak ng mga nanosegundo, ngunit itinatapon sila ng toMillis() at toSeconds(). Para sa tumpak na kalkulasyon, gamitin ang toNanos() o magtrabaho nang direkta sa Duration, nang walang conversion sa mga primitive na uri.

Ikatlong pagkakamali — pagwawalang-bahala sa negatibong Duration. Ang Duration.between(start, end) ay nagbabalik ng start - end. Kung ang start ay pagkatapos ng end, ang Duration ay magiging negatibo. Ang pamamaraang abs() ay tumutulong upang makuha ang absolute na halaga, at ang isNegative() — upang suriin ang pagkakasunud-sunod ng mga argumento.

Ikaapat na pagkakamali — maling pag-format ng Duration para sa UI. Ang Duration.toString() ay nagbabalik ng ISO-8601, na hindi nababasa. Palaging i-format ang Duration nang manu-mano para sa pagpapakita sa gumagamit, gamit ang toHours(), toMinutes() at toSeconds() na may tamang natitira sa paghahati.