6.9.2 Oggetti di tipo timedelta

6.9.2 Oggetti di tipo `timedelta`

Un oggetto di tipo timedelta rappresenta una durata, la differenza tra due date o tempi.

class timedelta( [days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])

Tutti gli argomenti sono facoltativi ed il loro valore predefinito è 0. Gli argomenti possono essere interi, long, o numeri in virgola mobile, e possono essere sia positivi che negativi.

Solo days, seconds e microseconds vengono memorizzati internamente. Gli altri argomenti del costruttore vengono convertiti in queste unità:

Un millisecondo viene convertito in 1000 microsecondi.
Un minuto viene convertito in 60 secondi.
Un'ora viene convertita in 3600 secondi.
Una settimana viene convertita in 7 giorni.

e giorni, secondi e millisecondi vengono quindi normalizzati in modo tale che la rappresentazione della durata sia unica e con queste caratteristiche:

0 <= microseconds < 1000000
0 <= seconds < 3600*24 (il numero di secondi in un giorno)
-999999999 <= days <= 999999999

Se uno degli argomenti è un numero in virgola mobile e vi sono frazioni di microsecondo, le frazioni avute come resto nella conversione di ogni argomento vengono sommate tra di loro e la somma viene arrotondata al microsecondo più vicino. Se nessun argomento è un numero in virgola mobile, la conversione e la normalizzazione sono esatte (non si perde alcuna informazione).

Se il valore normalizzato del numero di giorni è al di fuori dell'intervallo indicato, viene sollevata l'eccezione OverflowError.

Notate che la normalizzazione di valori negativi può essere soprendente di primo acchito. Per esempio:

>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Gli attributi di classe sono:

min: L'oggetto di tipo timedelta con il massimo valore negativo timedelta(-999999999).

max: L'oggetto di tipo timedelta con il massimo valore positivo timedelta(giorni=999999999, ore=23, minuti=59, secondi=59, microsecondi=999999).

resolution: La più piccola differenza possibile tra oggetti di tipo timedelta considerati non uguali, cioè timedelta(microseconds=1).

Notate che, a causa della normalizzazione, si verifica che timedelta.max >-timedelta.min. Il valore -timedelta.max non è rappresentabile come un oggetto di tipo timedelta.

Attributi delle istanze (in sola lettura):

Attributo Valore

days Compreso tra -999999999 e 999999999, limiti inclusi
seconds Compreso tra 0 e 86399, limiti inclusi
microseconds Compreso tra 0 e 999999 limiti inclusi

Attributo	Valore
`days`	Compreso tra -999999999 e 999999999, limiti inclusi
`seconds`	Compreso tra 0 e 86399, limiti inclusi
`microseconds`	Compreso tra 0 e 999999 limiti inclusi

Operazioni supportate:

Operazione Risultato

t1 = t2 + t3 Somma di t2 e t3. Dopo l'operazione sono vere le espressioni t1-t2 == t3 e t1-t3 == t2. (1)
t1 = t2 - t3 Differenza fra t2 e t3. Dopo l'operazione sono vere le espressioni t1 == t2 - t3 e t2 == t1 + t3. (1)
t1 = t2 * i o t1 = i * t2 Delta moltiplicato per un intero o un intero long. Dopo l'operazione è vera l'espressione t1 // i == t2, ammesso che i != 0.
In generale, l'espressione t1 * i == t1 * (i-1) + t1 è vera. (1)
t1 = t2 // i Viene calcolato il valore approssimato per difetto ed il resto (se esiste) viene scartato. (3)
+t1 Restituisce un oggetto timedelta con lo stesso valore di t1. (2)
-t1 Equivalente a timedelta(-t1.days, -t1.seconds, -t1.microseconds), come pure a t1* -1. (1)(4)
abs(t) Equivalente a +t quando t.days >= 0, oppure equivalente a -t quando t.days < 0. (2)

Note:

Operazione	Risultato
`t1 = t2 + t3`	Somma di `t2` e `t3`. Dopo l'operazione sono vere le espressioni `t1`-`t2` == `t3` e `t1`-`t3` == `t2`. (1)
`t1 = t2 - t3`	Differenza fra `t2` e `t3`. Dopo l'operazione sono vere le espressioni `t1` == `t2` - `t3` e `t2` == `t1` + `t3`. (1)
`t1 = t2 * i o t1 = i * t2`	Delta moltiplicato per un intero o un intero long. Dopo l'operazione è vera l'espressione `t1` // i == `t2`, ammesso che `i != 0`.
	In generale, l'espressione `t1` * i == `t1` * (i-1) + `t1` è vera. (1)
`t1 = t2 // i`	Viene calcolato il valore approssimato per difetto ed il resto (se esiste) viene scartato. (3)
`+t1`	Restituisce un oggetto `timedelta` con lo stesso valore di `t1`. (2)
`-t1`	Equivalente a `timedelta`(-`t1.days`, -`t1.seconds`, -`t1.microseconds`), come pure a `t1`* -1. (1)(4)
`abs(t)`	Equivalente a +`t` quando `t.days >= 0`, oppure equivalente a -`t` quando `t.days < 0`. (2)

(1): L'espressione è esatta, ma può causare un overflow.
(2): L'espressione è esatta e non può causare un overflow.
(3): Una divisione per zero solleva l'eccezione ZeroDivisionError.
(4): -timedelta.max non è rappresentabile come oggetto di tipo timedelta.

In aggiunta alle operazioni elencate sopra, gli oggetti di tipo timedelta supportano alcune addizioni o sottrazioni con oggetti di tipo date o datetime (vedete più avanti).

Confronti tra oggetti di tipo timedelta vengono supportati utilizzando l'oggetto di tipo timedelta rappresentante la più piccola durata, che viene considerato come il più piccolo oggetto di tipo timedelta. Allo scopo di evitare che venga usato il metodo predefinito di confronto tra gli indirizzi degli oggetti in caso di confronto tra tipi diversi, quando un oggetto di tipo timedelta viene confrontato con un oggetto di un tipo differente, viene sollevata l'eccezione TypeError, a meno che il confronto non sia == o !=, nei quali casi il vengono restituiti rispettivamente False o True.

Gli oggetti di tipo timedelta possono venire usati come chiavi dei dizionari (sono cioè ``ashable''), supportano la serializzazione (``pickling'') in modo efficiente e, in contesti booleani, un oggetto di tipo timedelta viene considerato vero se e solo se non è uguale a timedelta(0).

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.