Dominando o Carbon para Manipulação de Data e Hora em Golang

1: Introdução ao Carbon

1.1 Introdução

Um pacote golang simples, semântico e amigável para desenvolvedores para lidar com datas e horas.

Benefícios de usar o Carbon para manipulação de datas e horas:

Amigável para Desenvolvedores: Carbon oferece uma interface fluente e expressiva para lidar com datas e horas, que é intuitiva para os desenvolvedores.
Suporte à Internacionalização: Suporta internacionalização, permitindo que você localize suas representações de datas.
Imutabilidade: As instâncias do Carbon são imutáveis, o que significa que podem ser passadas com segurança sem modificações inesperadas.
Manipulação de Fuso Horário: O Carbon simplifica a complexidade de gerenciar datas e horas em diferentes fusos horários.
API Extensiva: Fornece um conjunto abrangente de funções para criar, analisar e formatar datas e horas.

1.2 Guia de Instalação

Instalação para Go versão >= 1.16

Para instalar o pacote Carbon para o Go versão 1.16 ou superior, utilize o seguinte comando:

go get -u github.com/golang-module/carbon/v2

Em seguida, importe o pacote no seu arquivo Go:

import "github.com/golang-module/carbon/v2"

Instalação para Go versão < 1.16

Para versões mais antigas do Go, você ainda pode instalar o Carbon usando:

go get -u github.com/golang-module/carbon

E importá-lo da mesma forma:

import "github.com/golang-module/carbon"

Observe que a v1 não está mais sendo atualizada ativamente, mas será mantida para correções de bugs.

1.3 Configurando Seu Primeiro Projeto Carbon

Configuração básica do Carbon: Uma vez que o Carbon está instalado, você pode começar a usá-lo simplesmente criando uma nova instância do Carbon. Você pode personalizar o Carbon definindo o layout global padrão, fuso horário e localidade para atender às necessidades do seu projeto.

Definindo o layout global padrão, fuso horário e localidade:

carbon.SetDefault(carbon.Default{
  Layout: carbon.RFC3339Layout,
  Timezone: carbon.PRC,
  Locale: "en",
})

Se não definido explicitamente, o Carbon possui configurações padrão para estes valores — Layout: "2006-01-02 15:04:05", Timezone: Local, Locale: "en".

2: Operações Básicas do Carbon

2.1 Trabalhando com a Hora Atual

Obtendo a Data e Hora Atuais

Obter a data e hora atuais é uma operação fundamental em muitas aplicações. Com o Carbon, você pode adquirir a instância de data e hora atual chamando o método carbon.Now(). Vamos ver como buscar a data e hora atuais:

// Obtém a data e hora atuais como uma instância do Carbon.
agora := carbon.Now()

fmt.Println("Data e hora atuais:", agora)

Exibindo Hoje, Ontem e Amanhã

O Carbon oferece uma maneira elegante de trabalhar com datas em relação ao dia atual. Para obter a representação da data e hora de hoje, ontem e amanhã, você pode usar os métodos carbon.Now(), carbon.Yesterday() e carbon.Tomorrow() respectivamente:

// Data e hora de hoje
hoje := carbon.Now()
fmt.Println("Hoje:", hoje.ToDateTimeString())

// Data e hora de ontem
ontem := carbon.Yesterday()
fmt.Println("Ontem:", ontem.ToDateTimeString())

// Data e hora de amanhã
amanhã := carbon.Tomorrow()
fmt.Println("Amanhã:", amanhã.ToDateTimeString())

Os métodos fornecem uma maneira sucinta de interagir com essas referências de data comumente usadas sem cálculos manuais.

Formatação e Representação da Hora Atual

O Carbon facilita diferentes maneiras de formatar e exibir a data e hora. Se você precisa de um formato padrão como ISO8601, um formato personalizado ou uma versão localizada, o Carbon possui métodos para atender a esses requisitos.

Aqui está como você pode formatar a data e hora atuais de várias maneiras:

// Representação padrão da data e hora
fmt.Println("RFC3339:", agora.ToRFC3339String())
fmt.Println("ISO8601:", agora.ToIso8601String())

// Formato personalizado de data e hora
fmt.Println("Personalizado:", agora.Format("Monday, 02-Jan-06 15:04:05 MST"))

// Usando layouts predefinidos
fmt.Println("Formato ANSIC:", agora.ToAnsicString())
fmt.Println("Formato UnixDate:", agora.ToUnixDateString())
fmt.Println("Formato RubyDate:", agora.ToRubyDateString())
fmt.Println("Formato Kitchen:", agora.ToKitchenString())

// Para padrões personalizados, use o método Format
fmt.Println("Padrão personalizado:", agora.Format("2006-01-02 15:04:05"))

Criação de instâncias a partir de timestamps

Em Go, lidar com timestamps é comum, e o Carbon fornece métodos intuitivos para lidar com eles. Um timestamp é uma sequência de caracteres ou informações codificadas identificando quando um determinado evento ocorreu, geralmente fornecendo a data e horário, às vezes precisa até uma pequena fração de segundo.

Para criar uma instância do Carbon a partir de um timestamp Unix, que representa o número de segundos que se passaram desde o início do Unix (meia-noite de 1 de janeiro de 1970, UTC), você pode usar vários níveis de precisão:

// Criar uma instância do Carbon a partir de um timestamp com precisão de segundo
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // Saída: "202-08-05 13:14:15 +080 CST"

// Para maior precisão (milissegundos), use `CreateFromTimestampMilli`
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // Saída: "202-08-05 13:14:15.999 +080 CST"

// Para microssegundos, use `CreateFromTimestampMicro`
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // Saída: "202-08-05 13:14:15.999999 +080 CST"

// E para nanossegundos, use `CreateFromTimestampNano`
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // Saída: "202-08-05 13:14:15.999999999 +080 CST"

Criação de instâncias a partir de componentes de data e hora

Se você tiver os componentes individuais de uma data, como ano, mês e dia, ou os componentes de um horário, como hora, minuto e segundo, o Carbon também pode lidar com eles.

// Criar uma instância do Carbon a partir de uma data específica
date := carbon.CreateFromDate(2022, 12, 25)
fmt.Println(date.ToDateString()) // Saída: "2022-12-25"

// Criar uma instância do Carbon a partir de um horário específico
time := carbon.CreateFromTime(23, 59, 59)
fmt.Println(time.ToTimeString()) // Saída: "23:59:59"

// Criar uma instância do Carbon a partir de uma data e horário
dateTime := carbon.CreateFromDateTime(2022, 12, 25, 23, 59, 59)
fmt.Println(dateTime.ToDateTimeString()) // Saída: "2022-12-25 23:59:59"

2.3 Análise de Strings de Tempo

Trabalhar com representações de data e hora como strings é um cenário comum. O Carbon facilita a conversão de strings em instâncias do Carbon.

Utilizando `carbon.Parse` para formatos de tempo padrão:

// Analisar uma string com data e hora
c := carbon.Parse("202-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
    fmt.Printf("Erro: %v", c.Error)
} else {
    fmt.Println(c.ToDateTimeString()) // Saída: "202-08-05 13:14:15"
}

// Analisar uma string formatada em RFC3339
rfc3339 := carbon.Parse("202-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // Saída: "202-08-05 13:14:15 +080 CST"

Formatos personalizados com `ParseByFormat` e `ParseByLayout`

Também é possível analisar strings em um formato específico que não é diretamente manipulado pelo carbon.Parse.

// Analisar uma string de tempo como uma instância do Carbon por formato
byFormat := carbon.ParseByFormat("202|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // Saída: "202-08-05 13:14:15"

// Analisar uma string de tempo como uma instância do Carbon por layout
byLayout := carbon.ParseByLayout("202|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // Saída: "202-08-05"

Lidando com erros

Sempre verifique o campo Error para garantir que a análise tenha sido bem-sucedida:

dataInvalida := carbon.Parse("Isso não é uma data", carbon.PRC)
if dataInvalida.IsInvalid() {
    fmt.Println("Erro ao analisar a data:", dataInvalida.Error)
}

Lembre-se, uma verificação robusta de erro é uma parte crítica ao trabalhar com datas e horas para evitar resultados inesperados ou falhas no sistema.