Modulo:Data/man

Modulo per eseguire operazioni sulle date.

Funzioni

diff

Questa funzione ritorna la differenza tra le date inserite tramite i parametri "inizio" e "fine" in una sola unità tra "anni", "mesi", "settimane", "giorni", "ore", "minuti" e "secondi". L'unità può essere specificata tramite il parametro "magnitudine", se non inserito viene utilizzata automaticamente l'unità più adatta. Il formato per le date è quello accettato dalla funzione parser #time.

Uso

• {{#invoke:Data|diff|inizio=data1|fine=data2}}

Parametri

inizio: data di partenza

fine: data di arrivo, può essere successiva o anteriore a inizio, se anteriore verrà anteposto il segno "-" (meno) al risultato.

magnitudine: l'unità da ritornare nel risultato, tra "anni", "mesi", "settimane", "giorni", "ore", "minuti" e "secondi". Se non inserita è utilizzata automaticamente la più adatta.

magnitudine min: quando non è utilizzata magnitudine e il modulo utilizza automaticamente l'unità più adatta, serve per configurare l'unità minima da usare. Se per esempio "magnitudine min" viene impostata a "mesi" allora non verranno usate le unità minori (giorni, minuti e secondi) anche se queste fossero le più adatte. È utile quando il modulo è usato in un template: pur non conoscendo a priori le date che verranno utilizzate si può così stabilire una unità minima che verrà visualizzata.

dir: se impostato a qualunque valore, esempio "dir=sì", nel risultato invece del segno verrà utilizzato il prefisso "tra" se positivo (esempio: "tra 1 mese") o verrà appeso "fa" se negativo (esempio "un mese fa").

Esempi

• {{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10}} → 40 giorni
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|magnitudine=mesi}} → 1 mese
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01}} → -18 mesi
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni}} → -1 anno

Gli stessi esempi con dir=sì:

• {{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|dir=sì}} → tra 40 giorni
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2016/02/10|magnitudine=mesi|dir=sì}} → tra 1 mese
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|dir=sì}} → 18 mesi fa
• {{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni|dir=sì}} → 1 anno fa

diff_ymd

Questa funzione ritorna la differenza in anni, mesi e giorni tra le date inserite tramite i parametri "inizio" e "fine". Il formato per le date è quello accettato dalla funzione parser #time.

Uso

• {{#invoke:Data|diff_ymd|inizio=data1|fine=data2}}

Parametri

inizio: data di partenza

fine: data di arrivo, può essere successiva o anteriore a inizio, se anteriore verrà anteposto il segno "-" (meno) al risultato.

dir: se impostato a qualunque valore, esempio "dir=sì", nel risultato invece del segno verrà utilizzato il prefisso "tra" se positivo (esempio: "tra 1 mese e 1 giorno") o verrà appeso "fa" se negativo (esempio "un mese e un giorno fa").

Esempi

• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01}} → -1 anno
• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04}} → 1 anno, 2 mesi e 3 giorni
• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31}} → -3 anni e 1 giorno

Gli stessi esempi con dir=sì:

• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01|dir=sì}} → 1 anno fa
• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04|dir=sì}} → tra 1 anno, 2 mesi e 3 giorni
• {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31|dir=sì}} → 3 anni e 1 giorno fa

compare

Questa funzione confronta due date e restituisce 0 se le date sono uguali, -1 se la prima è anteriore alla seconda, altrimenti 1. Il formato per le date è quello accettato dalla funzione parser #time.

Uso

• {{#invoke:Data|compare|data1=prima data|data2=seconda data}}

Parametri

data1: la prima data

data2: la seconda data

Esempi

• {{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/01}} → 0
• {{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/10}} → -1
• {{#invoke:Data|compare|data1=2016/01/10|data2=2016/01/01}} → 1

Utilizzo da un altro modulo

Oltre che attraverso #invoke, il modulo può essere utilizzato tramite "require" da un altro modulo. Le stesse funzioni sono disponibili tramite la classe Date:

local Date = require('Modulo:Data').Date

Esempio

local Date = require('Modulo:Data').Date
local p = {}

function p.main(frame)
	local inizio, fine, diff1, diff2, text1, text2, anteriore

	inizio = Date:new('2016/01/01')
	fine = Date:new('2017/03/04')

	-- utilizzo della funzione diff
	diff1 = inizio:diff(fine, 'mesi')

	-- utilizzo della funzione diff_ymd
	diff2 = inizio:diffYMD(fine)

	-- data per esteso
	text1 = inizio:getDateString()
	text2 = fine:getDateString()

	-- confronto
	anteriore = inizio < fine
	
	return string.format('La differenza tra il %s e il %s è di %s, più precisamente di %s. ' ..
						 'La prima data è anteriore alla seconda: %s.',
						 text1, text2, diff1, diff2, tostring(anteriore))
end

return p

Unit test

Unit test per questo modulo sono disponibili a Modulo:Data/test, per la loro esecuzione visitare Discussioni_modulo:Data/test.