Maîtriser Carbon pour la gestion des dates et heures en Golang

1: Démarrage avec Carbon

1.1 Introduction

Un package simple, sémantique et convivial pour les développeurs en Golang pour la gestion des dates et heures.

Avantages de l'utilisation de Carbon pour la gestion des dates et heures :

Convivial pour les développeurs : Carbon propose une interface fluide et expressive pour la manipulation des dates et heures, intuitive pour les développeurs.
Prise en charge de l'internationalisation : Prend en charge l'internationalisation, vous permettant de localiser vos représentations de date.
Immuabilité : Les instances de Carbon sont immuables, ce qui signifie qu'elles peuvent être transmises en toute sécurité sans modifications inattendues.
Gestion des fuseaux horaires : Carbon simplifie la complexité de la gestion des dates et heures à travers différents fuseaux horaires.
API étendue : Fournit un ensemble complet de fonctions pour la création, la recherche et le formatage des dates et heures.

1.2 Guide d'installation

Installation pour la version de Go >= 1.16

Pour installer le package Carbon pour la version de Go 1.16 ou supérieure, utilisez la commande suivante :

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

Ensuite, importez le package dans votre fichier Go :

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

Installation pour la version de Go < 1.16

Pour les anciennes versions de Go, vous pouvez toujours installer Carbon en utilisant :

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

Et l'importer de la même manière :

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

Notez que la version v1 n'est plus activement mise à jour, mais elle sera maintenue pour les correctifs.

1.3 Configuration de votre premier projet Carbon

Configuration de base de Carbon : Une fois Carbon installé, vous pouvez commencer à l'utiliser en créant simplement une nouvelle instance de Carbon. Vous pouvez personnaliser Carbon en définissant la mise en page globale par défaut, le fuseau horaire et la localisation pour répondre aux besoins de votre projet.

Définition de la mise en page globale par défaut, du fuseau horaire et de la localisation :

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

Si ce n'est pas défini explicitement, Carbon a des paramètres par défaut pour ceux-ci : Layout: "2006-01-02 15:04:05", Timezone: Local, Locale: "en".

2: Opérations de base avec Carbon

2.1 Travailler avec l'heure actuelle

Récupérer la date et l'heure actuelles

Récupérer la date et l'heure actuelles est une opération fondamentale dans de nombreuses applications. Avec Carbon, vous pouvez obtenir l'instance de date et d'heure actuelles en appelant la méthode carbon.Now(). Voyons comment récupérer la date et l'heure actuelles :

// Récupère la date et l'heure actuelles en tant qu'instance de Carbon.
maintenant := carbon.Now()

fmt.Println("Date et heure actuelles :", maintenant)

Affichage de Aujourd'hui, Hier et Demain

Carbon offre une manière élégante de travailler avec les dates par rapport au jour actuel. Pour obtenir la représentation de la date pour aujourd'hui, hier et demain, vous pouvez utiliser les méthodes carbon.Now(), carbon.Yesterday() et carbon.Tomorrow() respectivement :

// Date et heure d'aujourd'hui
aujourd'hui := carbon.Now()
fmt.Println("Aujourd'hui :", aujourd'hui.ToDateTimeString())

// Date et heure d'hier
hier := carbon.Yesterday()
fmt.Println("Hier :", hier.ToDateTimeString())

// Date et heure de demain
demain := carbon.Tomorrow()
fmt.Println("Demain :", demain.ToDateTimeString())

Les méthodes fournissent une manière concise d'interagir avec ces références de date couramment utilisées sans calculs manuels.

Formatage et représentation de l'heure actuelle

Carbon facilite différentes manières de formater et d'afficher la date et l'heure. Que vous ayez besoin d'un format standard tel qu'ISO8601, d'un format personnalisé ou d'une version localisée, Carbon propose des méthodes pour répondre à ces besoins.

Voici comment vous pouvez formater la date et l'heure actuelles de différentes manières :

// Représentation standard de la date et de l'heure
fmt.Println("RFC3339 :", maintenant.ToRFC3339String())
fmt.Println("ISO8601 :", maintenant.ToIso8601String())

// Format personnalisé de la date et de l'heure
fmt.Println("Personnalisé :", maintenant.Format("Monday, 02-Jan-06 15:04:05 MST"))

// Utilisation de mises en pages prédéfinies
fmt.Println("Format ANSIC :", maintenant.ToAnsicString())
fmt.Println("Format Date Unix :", maintenant.ToUnixDateString())
fmt.Println("Format Date Ruby :", maintenant.ToRubyDateString())
fmt.Println("Format Kitchen :", maintenant.ToKitchenString())

// Pour des modèles personnalisés, utilisez la méthode Format
fmt.Println("Modèle personnalisé :", maintenant.Format("2006-01-02 15:04:05"))

2.2 Création d'instances Carbon

Création d'instances à partir de horodateurs

En Go, la manipulation des horodateurs est fréquente, et Carbon offre des méthodes intuitives pour les gérer. Un horodateur est une séquence de caractères ou d'informations encodées identifiant quand un événement particulier s'est produit, donnant généralement la date et l'heure du jour, parfois précis à une petite fraction de seconde.

Pour créer une instance Carbon à partir d'un horodateur Unix, qui représente le nombre de secondes écoulées depuis l'époque Unix (minuit le 1er janvier 1970, UTC), vous pouvez utiliser divers niveaux de précision :

// Créer une instance Carbon à partir d'un horodateur donné avec une précision à la seconde
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // Résultat : "202-08-05 13:14:15 +080 CST"

// Pour une précision plus élevée (millisecondes), utilisez `CreateFromTimestampMilli`
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // Résultat : "202-08-05 13:14:15.999 +080 CST"

// Pour les microsecondes, utilisez `CreateFromTimestampMicro`
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // Résultat : "202-08-05 13:14:15.999999 +080 CST"

// Et pour les nanosecondes, utilisez `CreateFromTimestampNano`
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // Résultat : "202-08-05 13:14:15.999999999 +080 CST"

Création d'instances à partir des composants de date et d'heure

Si vous avez les composants individuels d'une date, tels que l'année, le mois et le jour, ou les composants d'une heure comme l'heure, la minute et la seconde, Carbon peut également les gérer.

// Créer une instance Carbon à partir d'une date donnée uniquement
date := carbon.CreateFromDate(2022, 12, 25)
fmt.Println(date.ToDateString()) // Résultat : "2022-12-25"

// Créer une instance Carbon à partir d'une heure donnée uniquement
time := carbon.CreateFromTime(23, 59, 59)
fmt.Println(time.ToTimeString()) // Résultat : "23:59:59"

// Créer une instance Carbon à partir à la fois de la date et de l'heure
dateTime := carbon.CreateFromDateTime(2022, 12, 25, 23, 59, 59)
fmt.Println(dateTime.ToDateTimeString()) // Résultat : "2022-12-25 23:59:59"

2.3 Analyse des chaînes de caractères temporelles

La manipulation des représentations date-heure sous forme de chaînes de caractères est un scénario courant. Carbon facilite la conversion des chaînes en instances Carbon.

Utilisation de `carbon.Parse` pour les formats temporels standard :

// Analyser une chaîne avec une date et une heure
c := carbon.Parse("202-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
    fmt.Printf("Erreur : %v", c.Error)
} else {
    fmt.Println(c.ToDateTimeString()) // Résultat : "202-08-05 13:14:15"
}

// Analyser une chaîne formatée selon RFC3339
rfc3339 := carbon.Parse("202-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // Résultat : "202-08-05 13:14:15 +080 CST"

Formats personnalisés avec `ParseByFormat` et `ParseByLayout`

Vous pouvez également analyser des chaînes dans un format spécifique qui n'est pas directement géré par carbon.Parse.

// Analyser une chaîne temporelle en tant qu'instance Carbon selon un format
byFormat := carbon.ParseByFormat("202|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // Résultat : "202-08-05 13:14:15"

// Analyser une chaîne temporelle en tant qu'instance Carbon selon une disposition
byLayout := carbon.ParseByLayout("202|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // Résultat : "202-08-05"

Gestion des erreurs

Vérifiez toujours le champ Error pour s'assurer que l'analyse a été réussie :

invalidDate := carbon.Parse("Ce n'est pas une date", carbon.PRC)
if invalidDate.IsInvalid() {
    fmt.Println("Erreur lors de l'analyse de la date :", invalidDate.Error)
}

N'oubliez pas, une vérification robuste des erreurs est une partie essentielle de la manipulation des dates et heures pour éviter des résultats inattendus ou des plantages système.