Измерение времени

Создание длительности

Чтобы создать значение Duration, используйте свойства-расширения, доступные для типов Int, Long и Double: nanoseconds, microseconds, milliseconds, seconds, minutes, hours и days.

Например:

import kotlin.time.*
import kotlin.time.Duration.Companion.nanoseconds
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
import kotlin.time.Duration.Companion.minutes
import kotlin.time.Duration.Companion.days

fun main() {
//sampleStart
    val fiveHundredMilliseconds: Duration = 500.milliseconds
    val zeroSeconds: Duration = 0.seconds
    val tenMinutes: Duration = 10.minutes
    val negativeNanosecond: Duration = (-1).nanoseconds
    val infiniteDays: Duration = Double.POSITIVE_INFINITY.days
    val negativeInfiniteDays: Duration = Double.NEGATIVE_INFINITY.days

    println(fiveHundredMilliseconds) // 500ms
    println(zeroSeconds)             // 0s
    println(tenMinutes)              // 10m
    println(negativeNanosecond)      // -1ns
    println(infiniteDays)            // Infinity
    println(negativeInfiniteDays)    // -Infinity
//sampleEnd
}

Также с объектами Duration можно выполнять простые арифметические операции:

import kotlin.time.*
import kotlin.time.Duration.Companion.seconds

fun main() {
//sampleStart
    val fiveSeconds: Duration = 5.seconds
    val thirtySeconds: Duration = 30.seconds

    println(fiveSeconds + thirtySeconds)
    // 35s
    println(thirtySeconds - fiveSeconds)
    // 25s
    println(fiveSeconds * 2)
    // 10s
    println(thirtySeconds / 2)
    // 15s
    println(thirtySeconds / fiveSeconds)
    // 6.0
    println(-thirtySeconds)
    // -30s
    println((-thirtySeconds).absoluteValue)
    // 30s
//sampleEnd
}

Получение строкового представления

Строковое представление значения Duration может пригодиться для вывода, сериализации, передачи или хранения.

Чтобы получить строковое представление, используйте функцию .toString(). По умолчанию время выводится с использованием каждой присутствующей единицы измерения. Например: 1h 0m 45.677s или -(6d 5h 5m 28.284s)

Чтобы настроить вывод, используйте функцию .toString(), передав в качестве параметров нужное значение DurationUnit и количество знаков после запятой:

import kotlin.time.Duration
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.DurationUnit

fun main() {
//sampleStart
    // Print in seconds with 2 decimal places
    println(5887.milliseconds.toString(DurationUnit.SECONDS, 2))
    // 5.89s
//sampleEnd
}

Чтобы получить строку, совместимую с ISO 8601, используйте функцию toIsoString():

import kotlin.time.Duration.Companion.seconds

fun main() {
//sampleStart
    println(86420.seconds.toIsoString()) // PT24H0M20S
//sampleEnd
}

Преобразование длительности

Чтобы преобразовать значение Duration в другую DurationUnit, используйте следующие свойства:

• inWholeNanoseconds

• inWholeMicroseconds

• inWholeSeconds

• inWholeMinutes

• inWholeHours

• inWholeDays

Например:

import kotlin.time.Duration
import kotlin.time.Duration.Companion.minutes

fun main() {
//sampleStart
    val thirtyMinutes: Duration = 30.minutes
    println(thirtyMinutes.inWholeSeconds)
    // 1800
//sampleEnd
}

Кроме того, нужную DurationUnit можно передать в качестве параметра следующим функциям-расширениям:

• .toInt()

• .toDouble()

• .toLong()

Например:

import kotlin.time.Duration.Companion.seconds
import kotlin.time.DurationUnit

fun main() {
//sampleStart
    println(270.seconds.toDouble(DurationUnit.MINUTES))
    // 4.5
//sampleEnd
}

Сравнение длительности

Чтобы проверить, равны ли объекты Duration, используйте оператор равенства (==):

import kotlin.time.Duration
import kotlin.time.Duration.Companion.hours
import kotlin.time.Duration.Companion.minutes

fun main() {
//sampleStart
    val thirtyMinutes: Duration = 30.minutes
    val halfHour: Duration = 0.5.hours
    println(thirtyMinutes == halfHour)
    // true
//sampleEnd
}

Чтобы сравнить объекты Duration, используйте операторы сравнения (<, >):

import kotlin.time.Duration.Companion.microseconds
import kotlin.time.Duration.Companion.nanoseconds

fun main() {
//sampleStart
    println(3000.microseconds < 25000.nanoseconds)
    // false
//sampleEnd
}

Разбиение длительности на компоненты

Чтобы разбить значение Duration на компоненты времени и выполнить дополнительное действие, используйте перегруженную версию функции toComponents(). Передайте нужное действие в качестве параметра функции в виде функции или лямбда-выражения.

Например:

import kotlin.time.Duration
import kotlin.time.Duration.Companion.minutes

fun main() {
//sampleStart
    val thirtyMinutes: Duration = 30.minutes
    println(thirtyMinutes.toComponents { hours, minutes, _, _ -> "${hours}h:${minutes}m" })
    // 0h:30m
//sampleEnd
}

В этом примере лямбда-выражение принимает параметры-функции hours и minutes, а вместо неиспользуемых параметров seconds и nanoseconds указаны символы подчёркивания (_). Выражение возвращает объединённую строку, используя шаблоны строк, чтобы получить нужный формат вывода: hours и minutes.

Измерение времени выполнения кода

Чтобы измерить время выполнения блока кода, используйте встроенную функцию measureTime:

import kotlin.time.measureTime

fun main() {
//sampleStart
    val timeTaken = measureTime {
        Thread.sleep(100)
    }
    println(timeTaken) // e.g. 103 ms
//sampleEnd
}

Чтобы измерить время выполнения блока кода и вернуть его значение, используйте встроенную функцию measureTimedValue.

Например:

import kotlin.time.measureTimedValue

fun main() {
//sampleStart
    val (value, timeTaken) = measureTimedValue {
        Thread.sleep(100)
        42
    }
    println(value)     // 42
    println(timeTaken) // e.g. 103 ms
//sampleEnd
}

По умолчанию обе функции используют монотонный источник времени.

Отметка моментов времени

Чтобы отметить определённый момент времени, используйте интерфейс TimeSource и функцию markNow(), чтобы создать TimeMark:

import kotlin.time.*

fun main() {
   val timeSource = TimeSource.Monotonic
   val mark = timeSource.markNow()
}

Измерение разницы во времени

Чтобы измерить разницу между объектами TimeMark, полученными из одного источника времени, используйте оператор вычитания (-).

Чтобы сравнить объекты TimeMark, полученные из одного источника времени, используйте операторы сравнения (<, >).

Например:

import kotlin.time.*

fun main() {
//sampleStart
   val timeSource = TimeSource.Monotonic
   val mark1 = timeSource.markNow()
   Thread.sleep(500) // Sleep 0.5 seconds.
   val mark2 = timeSource.markNow()

   repeat(4) { n ->
       val mark3 = timeSource.markNow()
       val elapsed1 = mark3 - mark1
       val elapsed2 = mark3 - mark2

       println("Measurement 1.${n + 1}: elapsed1=$elapsed1, elapsed2=$elapsed2, diff=${elapsed1 - elapsed2}")
   }
   
   println(mark2 > mark1) // This is true, as mark2 was captured later than mark1.
   // true
//sampleEnd
}

Чтобы проверить, прошёл ли срок или истёк ли тайм-аут, используйте функции-расширения hasPassedNow() и hasNotPassedNow():

import kotlin.time.*
import kotlin.time.Duration.Companion.seconds

fun main() {
//sampleStart
   val timeSource = TimeSource.Monotonic
   val mark1 = timeSource.markNow()
   val fiveSeconds: Duration = 5.seconds
   val mark2 = mark1 + fiveSeconds

   // It hasn't been 5 seconds yet
   println(mark2.hasPassedNow())
   // false
  
   // Wait six seconds
   Thread.sleep(6000)
   println(mark2.hasPassedNow())
   // true

//sampleEnd
}

Источники времени по умолчанию на разных платформах

В этой таблице указаны источники монотонного времени, используемые по умолчанию на каждой платформе:

Создание источника времени

В некоторых случаях может понадобиться другой источник времени. Например, в Android System.nanoTime() учитывает время только пока устройство активно. При переходе устройства в глубокий спящий режим отсчёт времени прекращается. Чтобы отслеживать время, пока устройство находится в глубоком спящем режиме, можно создать источник времени, использующий SystemClock.elapsedRealtimeNanos():

object RealtimeMonotonicTimeSource : AbstractLongTimeSource(DurationUnit.NANOSECONDS) {
    override fun read(): Long = SystemClock.elapsedRealtimeNanos()
}

Затем можно использовать этот источник времени для измерения времени:

fun main() {
    val elapsed: Duration = RealtimeMonotonicTimeSource.measureTime {
        Thread.sleep(100)
    }
    println(elapsed) // e.g. 103 ms
}

Подробнее о пакете kotlin.time см. в справочнике по API стандартной библиотеки.