Kotlinautas

Esse conteúdo é oferecido e distribuído pela comunidade Kotlinautas, uma comunidade brasileira que busca oferecer conteúdo gratuito sobre a linguagem Kotlin em um espaço plural.

O quê é kotlinx-datetime?

kotlinx-datetime é uma biblioteca oficial Kotlin para manipular datas. Podendo pegar o horário, dia, mês, ano,etc. atual, incrementar, diminuir e comparar datas.

Materiais

Será necessário ter o IntelliJ instalado na máquina e um conhecimento básico sobre a linguagem Kotlin.

Criando o projeto

Abra seu IntelliJ no menu inicial e clique em New Project:

Depois, selecione a opção Kotlin DSL build script, selecione também a opção Kotlin/JVM, e opicionalmente remova a primeira opção Java. Essa opção não vai mudar em nada, pois ela dá suporte do Gradle á linguagem Java, mas apenas iremos usar Kotlin.

Após isso, clique em Next e escreva o nome do projeto e a localização na sua máquina. Essas duas opção são completamente pessoais, caso não tenha nenhuma ideia, coloque algo como datas-em-kotlin apenas como identificação.

Agora, com o projeto aberto, vá ao aquivo build.gradle.kts e adicione a dependência implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.2.1"), com a seção dependencies ficando assim:

dependencies {
    implementation(kotlin("stdlib"))
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.2.1")
}

Agora, clique no elefante no canto superior direito para carregar as alterações no Gradle.

Após isso, poderemos começar a programar. Você pode criar um arquivo em src/main/kotlin/ chamado main.kt para ser o arquivo principal da aplicação.

Mas com qualquer nome de arquivo, como você irá usar as a kotlinx-datetime, sempre se lembre de importar a biblioteca no começo do arquivo:

import kotlinx.datetime.*

Usando a kotlinx.datetime

Gerando a data atual

Um dos principais usos da kotlinx.datetime é pegar o horário atual e manipular esse horário. Isso pode ser feito da seguinte forma:

fun main() {
    val horaAgora = Clock.System.now()

    println(horaAgora)
}

• Clock é uma classe pertencente á kotlinx.datetime que vamos usar para gerar instâncias de uma data;
• Após criarmos essa instância da data atual, mostramos na tela essa hora;

O resultado desse código será algo parecido com:

2021-08-29T19:19:55.397748Z

Você pode ver que o resultado foi a hora atual, mas em um fuso horário diferente. a kotlinx-datetime automaticamente pega seu horário local, e muda o fuso horário para o UTC (Tempo Universal Coordenado).

Caso você queira transformar esse horário UTC para um outro fuso horário, isso pode ser feito com a classe TimeZone. Dessa maneira:

fun main() {
    val horaAgora = Clock.System.now()

    val fusohorario = TimeZone.of("America/Campo_Grande")

    val horaCampoGrande = horaAgora.toLocalDateTime(fusohorario)

    println(horaCampoGrande)
}

• Criamos um fuso horário usando TimeZone.of que recebe um texto que representa o fuso horário da cidade que queremos usar, no caso, foi usada a cidade de Campo Grande usando o texto America/Campo_Grande como identificação;
• Usamos a função .toLocalDateTime para tranformar a horaAgora, mudando seu fuso horário;
• Mostramos na tela o novo horário;

Com isso, o novo resultado do nosso código será:

2021-08-29T16:36:27.723200

Busque agora mudar esse código, usando a sua cidade ao invés de Campo Grande.

Também é possível de usar o fuso horário padrão dá máquina, isso pode ser feito usando a função .currentSystemDefault(). Dessa maneira:

fun main() {
    val horaAgora = Clock.System.now()

    val fusohorario = TimeZone.currentSystemDefault()

    val horaCampoGrande = horaAgora.toLocalDateTime(fusohorario)

    println(horaCampoGrande)
}

Agora o resultado será a hora exata do seu computador, não importando onde esteja pois o fuso horário que está sendo usado é o fuso horário da máquina.

Gerando uma data específica

Também é possível de escolher uma data, e criar um objeto do kotlinx.datetime que represente essa data. Para fazermos isso, pode ser usada a classe LocalDateTime dessa maneira:

fun main() {
    val data = LocalDateTime(2016, 2, 15, 16, 57, 0, 0)

    println(data)
}

• Informamos á classe LocalDateTime o ano, mês, dia, hora, minuto, segundo e nanosegundo (nessa ordem), e com isso um objeto com essa data foi criado;

Agora, o resultado do seu código será esse:

2016-02-15T16:57

Podemos converter essa data para um fuso horário específico também, usando a função .toInstant dessa maneira:

fun main() {
    val data = LocalDateTime(2016, 2, 15, 16, 57, 0, 0)

    val dataFusoHorario = data.toInstant(TimeZone.of("America/Campo_Grande"))

    println(dataFusoHorario)
}

• Passamos ao .toInstant um fuso horário usando TimeZone.of e uma cidade;
• Após isso, mostramos essa data com um fuso horário aplicado na tela;

Agora, o resultado do seu código será esse:

2016-02-15T19:57:00Z

O resultado mudou pois como mudamos o fuso horário, a hora irá mudar. Busque substituir America/Campo_Grande pela sua cidade;

Cálculos com datas

Podemos fazer contas de subtração e adição com datas para descobrir a diferença entre duas datas. Vamos ver o exemplo abaixo:

fun main() {
    val dataPassada = LocalDateTime(2016, 2, 15, 16, 57, 0, 0).toInstant(TimeZone.currentSystemDefault())
    val dataAgora = Clock.System.now()

    val diferença = dataAgora - dataPassada

    println(diferença)
}

• Criamos uma variável dataPassada que guarda uma data de 2016 (para termos o horário junto é necessário usar o .toInstant para transformar a data normal em um horário);
• Criamos uma variável dataAgora que representa o horário atual;
• Após isso, criamos uma variável diferença que guarda a subtração entre a data atual, e a data passada. Descobrindo quanto tempo se passou desde a data passada;
• Mostramos esse resultado na tela;

Com isso, teremos algo parecido com isso como resultado:

2022d 7h 20m 45.652252s

O resultado sempre vai ser o número de dias que já se passaram desde 021/15/2016 pois fizemos a subtração entre a data atual e essa data passada.

Finalização

Neste artigo, você aprendeu como usar de forma básica a biblioteca kotlinx-datetime para trabalhar com datas e horários. Busque na documentação por mais exemplos e recursos da biblioteca.

Muito obrigada por ler ❤️🏳️‍⚧️ e me segue nas redes, é tudo @lissatransborda 👀