Modulo:Data/man: differenze tra le versioni

Versione delle 11:06, 19 mag 2015

Versione attuale delle 14:37, 18 mar 2016

(13 versioni intermedie di uno stesso utente non sono mostrate)

Riga 4:

== Funzioni ==

=== diff ===

Questa funzione ritorna la differenza tra le date inserite tramite i parametri "frominizio" e "tofine" 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. Se "from" è omesso viene utilizzata la data corrente. Il formato per le date è quello accettato dalla funzione parser [[Aiuto:Funzioni_parser#time|#time]].

; Uso

* <code><nowiki>{{#invoke:Data|diff|frominizio=data1|tofine=data2}}</nowiki></code>

; Parametri

: ''frominizio'': data di partenza, se non inserita viene utilizzata la data corrente

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

:''to'': data di arrivo

: ''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

* <code><nowiki>{{#invoke:Data|diff|frominizio=2016/01/01|tofine=2016/02/10}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff|frominizio=2016/01/01|tofine=2016/02/10}}

* <code><nowiki>{{#invoke:Data|diff|frominizio=2016/01/01|tofine=2016/02/10|magnitudine=mesi}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff|frominizio=2016/01/01|tofine=2016/02/10|magnitudine=mesi}}

* <code><nowiki>{{#invoke:Data|diff|frominizio=2016/01/01|tofine=2014/07/01}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff|frominizio=2016/01/01|tofine=2014/07/01}}

* <code><nowiki>{{#invoke:Data|diff|frominizio=2016/01/01|tofine=2014/07/01|magnitudine=anni}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff|frominizio=2016/01/01|tofine=2014/07/01|magnitudine=anni}}

Gli stessi esempi con dir=sì:

* <code><nowiki>{{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20152016/0102/0110|dir=sì}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20152016/0102/0110|dir=sì}}

* <code><nowiki>{{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20172016/0302/0410|magnitudine=mesi|dir=sì}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20172016/0302/0410|magnitudine=mesi|dir=sì}}

* <code><nowiki>{{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20122014/1207/3101|dir=sì}}</nowiki></code> ritornerà:→ {{#invoke:Data|diff_ymddiff|frominizio=2016/01/01|tofine=20122014/1207/3101|dir=sì}}

* <code><nowiki>{{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni|dir=sì}}</nowiki></code> → {{#invoke:Data|diff|inizio=2016/01/01|fine=2014/07/01|magnitudine=anni|dir=sì}}

=== diff_ymd ===

Questa funzione ritorna la differenza in anni, mesi e giorni tra le date inserite tramite i parametri "frominizio" e "tofine". Se "from" è omesso viene utilizzata la data corrente. Il formato per le date è quello accettato dalla funzione parser [[Aiuto:Funzioni_parser#time|#time]].

; Uso

* <code><nowiki>{{#invoke:Data|diff_ymd|frominizio=data1|tofine=data2}}</nowiki></code>

; Parametri

: ''toinizio'': data di arrivopartenza

: ''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

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01}}

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04}}

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31}}

Gli stessi esempi con dir=sì:

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01|dir=sì}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2015/01/01|dir=sì}}

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04|dir=sì}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2017/03/04|dir=sì}}

* <code><nowiki>{{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31|dir=sì}}</nowiki></code> → {{#invoke:Data|diff_ymd|inizio=2016/01/01|fine=2012/12/31|dir=sì}}

=== 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 [[Aiuto:Funzioni_parser#time|#time]].

; Uso

* <code><nowiki>{{#invoke:Data|compare|data1=prima data|data2=seconda data}}</nowiki></code>

; Parametri

: ''data1'': la prima data

: ''data2'': la seconda data

; Esempi

* <code><nowiki>{{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/01}}</nowiki></code> → {{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/01}}

* <code><nowiki>{{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/10}}</nowiki></code> → {{#invoke:Data|compare|data1=2016/01/01|data2=2016/01/10}}

* <code><nowiki>{{#invoke:Data|compare|data1=2016/01/10|data2=2016/01/01}}</nowiki></code> → {{#invoke:Data|compare|data1=2016/01/10|data2=2016/01/01}}

== 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:

<syntaxhighlight lang="lua">local Date = require('Modulo:Data').Date</syntaxhighlight>

; Esempio

<syntaxhighlight lang="lua">

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

;Uso

text1 = inizio:getDateString()

*<code><nowiki>{{#invoke:Data|diff_ymd|from=data1|to=data2}}</nowiki></code>

text2 = fine:getDateString()

-- confronto

;Parametri

anteriore = inizio < fine

:''from'': data di partenza, se non inserita viene utilizzata la data corrente

:''to'': data di arrivo.

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

;Esempi

</syntaxhighlight>

*<code><nowiki>{{#invoke:Data|diff_ymd|from=2016/01/01|to=2015/01/01}}</nowiki></code> ritornerà: {{#invoke:Data|diff_ymd|from=2016/01/01|to=2015/01/01}}

*<code><nowiki>{{#invoke:Data|diff_ymd|from=2016/01/01|to=2017/03/04}}</nowiki></code> ritornerà: {{#invoke:Data|diff_ymd|from=2016/01/01|to=2017/03/04}}

*<code><nowiki>{{#invoke:Data|diff_ymd|from=2016/01/01|to=2012/12/31}}</nowiki></code> ritornerà: {{#invoke:Data|diff_ymd|from=2016/01/01|to=2012/12/31}}

== Unit test ==

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

<includeonly><!--{{protetta}}-->[[Categoria:Moduli]]</includeonly>

<noinclude>[[Categoria:Manuali dei moduli]]</noinclude>