1: Iniziare con Carbon

1.1 Introduzione

Un pacchetto golang semplice, semantico e sviluppatore-friendly per la gestione della data e ora.

Vantaggi nell'uso di Carbon per la gestione della data e ora:

  • Sviluppatore-Friendly: Carbon offre un'interfaccia fluida ed espressiva per la gestione della data e ora che è intuitiva per gli sviluppatori.
  • Supporto all'Internazionalizzazione: Supporta l'internazionalizzazione, consentendo di localizzare le rappresentazioni delle date.
  • Immutabilità: Le istanze di Carbon sono immutabili, il che significa che possono essere passate in giro in modo sicuro senza modifiche inaspettate.
  • Gestione del Fuso Orario: Carbon semplifica la complessità della gestione della data e ora attraverso diversi fusi orari.
  • API Estese: Fornisce un insieme completo di funzioni per creare, analizzare e formattare date e ora.

1.2 Guida all'installazione

Installazione per Go versione >= 1.16

Per installare il pacchetto Carbon per Go versione 1.16 o superiore, utilizzare il seguente comando:

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

Successivamente, importare il pacchetto nel file Go:

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

Installazione per Go versione < 1.16

Per le versioni più datate di Go, è comunque possibile installare Carbon utilizzando:

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

E importarlo allo stesso modo:

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

Si noti che la v1 non è più attivamente aggiornata, ma sarà mantenuta per correzioni di bug.

1.3 Configurare il tuo Primo Progetto Carbon

Configurazione di base di Carbon: Una volta installato Carbon, è possibile iniziare ad usarlo semplicemente creando una nuova istanza di Carbon. È possibile personalizzare Carbon impostando il layout globale predefinito, il fuso orario e la lingua per adattarsi alle esigenze del progetto.

Impostare il layout globale predefinito, il fuso orario e la lingua:

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

Se non impostato esplicitamente, Carbon ha impostazioni predefinite per queste — Layout: "2006-01-02 15:04:05", Fuso Orario: Locale, Lingua: "en".

2: Operazioni di Base con Carbon

2.1 Lavorare con l'Ora Attuale

Recupero della Data e Ora Attuali

Ottenere la data e ora attuali è un'operazione fondamentale in molte applicazioni. Con Carbon, è possibile acquisire l'istanza della data e ora corrente chiamando il metodo carbon.Now(). Vediamo come recuperare la data e ora correnti:

// Recupera la data e ora correnti come un'istanza di Carbon.
now := carbon.Now()

fmt.Println("Data e ora correnti:", now)

Visualizzazione di Oggi, Ieri e Domani

Carbon fornisce un modo elegante per lavorare con date relative al giorno corrente. Per ottenere la rappresentazione della data e ora di oggi, ieri, e domani, è possibile utilizzare i metodi carbon.Now(), carbon.Yesterday(), e carbon.Tomorrow() rispettivamente:

// Data e ora di oggi
today := carbon.Now()
fmt.Println("Oggi:", today.ToDateTimeString())

// Data e ora di ieri
yesterday := carbon.Yesterday()
fmt.Println("Ieri:", yesterday.ToDateTimeString())

// Data e ora di domani
tomorrow := carbon.Tomorrow()
fmt.Println("Domani:", tomorrow.ToDateTimeString())

I metodi forniscono un modo conciso per interagire con questi riferimenti di data comunemente utilizzati senza calcoli manuali.

Formattazione e Rappresentazione dell'Ora Attuale

Carbon facilita modi differenti per formattare e visualizzare la data e ora. Che tu abbia bisogno di un formato standard come ISO8601, un formato personalizzato o una versione localizzata, Carbon dispone di metodi per soddisfare queste esigenze.

Ecco come puoi formattare la data e ora correnti in vari modi:

// Rappresentazione standard della data e ora
fmt.Println("RFC3339:", now.ToRFC3339String())
fmt.Println("ISO8601:", now.ToIso8601String())

// Formato personalizzato della data e ora
fmt.Println("Personalizzato:", now.Format("Monday, 02-Jan-06 15:04:05 MST"))

// Utilizzando layout predefiniti
fmt.Println("Formato ANSIC:", now.ToAnsicString())
fmt.Println("Formato UnixDate:", now.ToUnixDateString())
fmt.Println("Formato RubyDate:", now.ToRubyDateString())
fmt.Println("Formato Kitchen:", now.ToKitchenString())

// Per modelli personalizzati, utilizzare il metodo Format
fmt.Println("Modello personalizzato:", now.Format("2006-01-02 15:04 PM"))

Creazione di istanze da timestamp

In Go, è frequente dover gestire i timestamp e Carbon fornisce metodi intuitivi per gestirli. Un timestamp è una sequenza di caratteri o informazioni codificate che identifica quando si è verificato un certo evento, di solito fornendo data e ora del giorno, talvolta precisa fino a una piccola frazione di secondo.

Per creare un'istanza di Carbon da un timestamp Unix, che rappresenta il numero di secondi trascorsi dall'epoca Unix (mezzanotte del 1 gennaio 1970, UTC), è possibile utilizzare vari livelli di precisione:

// Crea un'istanza di Carbon da un timestamp dato con precisione al secondo
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // Output: "202-08-05 13:14:15 +080 CST"

// Per una precisione maggiore (millisecondi), utilizzare `CreateFromTimestampMilli`
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // Output: "202-08-05 13:14:15.999 +080 CST"

// Per microsecondi, utilizzare `CreateFromTimestampMicro`
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // Output: "202-08-05 13:14:15.999999 +080 CST"

// E per i nanosecondi, utilizzare `CreateFromTimestampNano`
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // Output: "202-08-05 13:14:15.999999999 +080 CST"

Creazione di istanze da componenti di data e ora

Se si dispongono dei singoli componenti di una data, come anno, mese e giorno o dei componenti di un'ora come ora, minuto e secondo, Carbon può gestirli.

// Crea un'istanza di Carbon da una data specifica
data := carbon.CreateFromDate(2022, 12, 25)
fmt.Println(data.ToDateString()) // Output: "2022-12-25"

// Crea un'istanza di Carbon da un'ora specifica
ora := carbon.CreateFromTime(23, 59, 59)
fmt.Println(ora.ToTimeString()) // Output: "23:59:59"

// Crea un'istanza di Carbon sia da data che da ora
dataOra := carbon.CreateFromDateTime(2022, 12, 25, 23, 59, 59)
fmt.Println(dataOra.ToDateTimeString()) // Output: "2022-12-25 23:59:59"

2.3 Parsing delle stringhe di tempo

Gestire le rappresentazioni data-ora come stringhe è uno scenario comune. Carbon rende comodo il parsing delle stringhe in istanze di Carbon.

Utilizzo di carbon.Parse per formati di tempo standard:

// Parsa una stringa con data e ora
c := carbon.Parse("202-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
    fmt.Printf("Errore: %v", c.Error)
} else {
    fmt.Println(c.ToDateTimeString()) // Output: "202-08-05 13:14:15"
}

// Parsa una stringa formattata secondo RFC3339
rfc3339 := carbon.Parse("202-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // Output: "202-08-05 13:14:15 +080 CST"

Formati personalizzati con ParseByFormat e ParseByLayout

È anche possibile parsare stringhe con un formato specifico non gestito direttamente da carbon.Parse.

// Parsa una stringa di tempo come istanza di Carbon in base al formato
byFormat := carbon.ParseByFormat("202|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // Output: "202-08-05 13:14:15"

// Parsa una stringa di tempo come istanza di Carbon in base al layout
byLayout := carbon.ParseByLayout("202|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // Output: "202-08-05"

Gestione degli errori

Verificare sempre il campo Error per garantire il successo del parsing:

dataNonValida := carbon.Parse("Questa non è una data", carbon.PRC)
if dataNonValida.IsInvalid() {
    fmt.Println("Errore nel parsing della data:", dataNonValida.Error)
}

Ricorda, un controllo degli errori robusto è una parte critica del lavoro con date e orari per prevenire risultati inaspettati o arresti del sistema.