Edición de «Módulo:Date/doc»

'''Nota:''' Éste módulo es una traducción de {{URL|https://en.wikipedia.org/wiki/Module:Date|Module:Date}} lo que significa que cualquier módulo que dependa de {{URL|https://en.wikipedia.org/wiki/Module:Date|Module:Date}} se puede utilizar con éste módulo sin ningún problema (siempre que el módulo en cuestión se adapte para entender fechas en español si fuese necesario). Es por eso que a pesar de que las fechas que devuelve al utilizar <code>:text()</code> son en español todos los nombres de los métodos internos y los parámetros se han mantenido en el idioma original.
----
Este módulo provee funciones relacionadas con el manejo de fechas para que puedan usarse en otros módulos. El módulo soporta fechas en el [[Calendario Gregoriano]] y en el [[calendario Juliano]], desde el 9999 a. C. al 9999 d. C.. Los calendarios son prolépticos, es decir, se aplican incluso antes de su creación sin irregularidades.

Una fecha , con su hora opcional, se puede especificar en varios formatos diferentes y se puede formatear para su impresión usando otra variedad de formatos, por ejemplo '1 de abril de 2016' o el 'abril 1, 2016'. Las propiedades de la fecha incluyen su [[Fecha juliana]] y los días desde el 1 A.D. así como el día de la semana y el día del año.

También es posible comparar fechas (por ejemplo, <code>fecha1 <= fecha2</code>), y se les pueden aplicar operadores como la suma o la resta (por ejemplo, <code>fecha + '3 meses'</code> o <code>fecha1 - fecha2</code>). Estas operaciones funcionan con fechas de los calendarios Juliano y Gregoriano pero será nil si intentas operar con dos fechas de diferentes calendarios.

El módulo provee los siguientes objetos.

{| class="wikitable"
! Export !! Descripción
|-
| <code>_current</code>       || Tabla con el año, mes, día, hora, minuto y segundo actuales.
|-
| <code>_Date</code>          || Función que devuelve una tabla para una fecha concreta.
|-
| <code>_days_in_month</code> || Función que retorna el número de días en un mes.
|}

En [[Módulo:Date/ejemplos]] se encuentran los ejemplos de uso del módulo y en [[Módulo discusión:Date/ejemplos]] está el resultado de su ejecución.
{{Contenido}}
== Formato de la salida ==

Es posible formatear la representación textual de la fecha.
<syntaxhighlight lang="lua">
local Date = require('Módulo:Date')._Date
local text = Date(2016, 7, 1):text()          -- devolvería '1 de julio de 2016'
local text = Date(2016, 7, 1):text('%-d de %B')  -- devolvería '1 de julio'
local text = Date('1 de julio de 2016'):text('mdy')  -- devolvería 'julio 1, 2016'
</syntaxhighlight>

Los siguientes son los códigos de formato simplificados disponibles.
{| class="wikitable"
! Código !! Resultado
|-
| hm  || horas:minutos, utilizando "am" o "pm" o una variante especificada (14:30 o 2:30&nbsp;pm o lo especificado)
|-
| hms || horas:minutos:segundos (14:30:45)
|-
| ymd || año-mes-día (2016-07-01)
|-
| mdy || mes día, año (julio 1, 2016)
|-
| dmy || día de mes de año (1 de julio de 2016)
|}

También están disponibles los siguientes códigos están disponibles (similar a los utilizados por [[time.h|strftime]]).
{| class="wikitable"
! Código !! Resultado
|-
| %a  || Abreviación del día: Lu, Ma, ...
|-
| %A  || Nombre del día: lunes, martes, ...
|-
| %u  || Día de la semana: de 1 a 7 (Lunes a Domingo)
|-
| %w  || Día de la semana: de 0 a 6 (Domingo a Sábado)
|-
| %d  || Día del mes relleno con ceros: 01 a 31
|-
| %b  || Abreviación del mes: ene a dic
|-
| %B  || Nombre del mes: enero a diciembre
|-
| %m  || Mes relleno con ceros: 01 a 12
|-
| %Y  || Año relleno con ceros: 0012, 0120, 1200
|-
| %H  || Hora (reloj de 24 horas) rellena con ceros: 00 a 23
|-
| %I  || Hora (reloj de 12 horas) rellena con ceros: 01 a 12
|-
| %p  || AM o PM como con las opciones
|-
| %M  || Minutos rellenos con ceros: 00 a 59
|-
| %S  || Segundos rellenos con ceros: 00 a 59
|-
| %j  || Día del año relleno con ceros: 001 a 366
|-
| %-d || Día del mes: 1 a 31
|-
| %-m || Mes: 1 a 12
|-
| %-Y || Año: 12, 120, 1200
|-
| %-H || Hora: 0 a 23
|-
| %-M || Minutos: 0 a 59
|-
| %-S || Segundos: 0 a 59
|-
| %-j || Día del año: 1 a 366
|-
| %-I || Hora: 1 a 12
|-
| %%  || %
|}

Además también se puede utilizar <code>%{''property''}</code> (donde <code>''property''</code> es una de las propiedades de la fecha).

Por ejemplo, una fecha como <code>Date('1 de febrero de 2015 14:30:45 d. C.')</code> tiene las siguientes propiedades.

{| class="wikitable"
! Código !! Resultado
|-
| %{calendar}     || Gregorian
|-
| %{year}         || 2015
|-
| %{month}        || 2
|-
| %{day}          || 1
|-
| %{hour}         || 14
|-
| %{minute}       || 30
|-
| %{second}       || 45
|-
| %{dayabbr}      || do
|-
| %{dayname}      || Domingo
|-
| %{dayofweek}    || 0
|-
| %{dow}          || 0 (igual que 'dayofweek')
|-
| %{dayofweekiso} || 7
|-
| %{dowiso}       || 7 (igual que 'dayofweekiso')
|-
| %{dayofyear}    || 32
|-
| %{era}          || d. C.
|-
| %{gsd}          || 735630 (números de días desde 1 de enero de 1 d. C.; el primero es el 1)
|-
| %{juliandate}   || 2457055.1046875 ([[Fecha juliana]])
|-
| %{jd}           || 2457055.1046875 (igual que 'juliandate')
|-
| %{isleapyear}   || false
|-
| %{monthdays}    || 28
|-
| %{monthabbr}    || feb
|-
| %{monthname}    || febrero
|}

También hay disponibles algunos atajos. Dada <code>fecha = Date('1 feb 2015 14:30')</code>, obtendremos los siguientes resultados.
{| class="wikitable"
! Código           !! Descripción  !! Resultado del ejemplo              !! Formato equivalente
|-
| fecha:text('%c') || fecha y hora || 2:30&nbsp;pm 1 de febrero de 2015  || %-I:%M %p %-d %B %-Y %{era}
|-
| fecha:text('%C') || fecha y hora || 1 de febrero de 2015, 14:30          || %-d de %B de %-Y, %-H:%-M:%-S
|-
| fecha:text('%x') || fecha        || 1 de febrero de 2015               || %-d %B %-Y %{era}
|-
| fecha:text('%X') || hora         || 2:30&nbsp;pm                       || %-I:%M %p
|}

== Fecha Juliana ==

El siguiente código contiene un ejemplo de la conversión de una [[Fecha juliana]] y la posterior obtención de información sobre esa fecha.
<syntaxhighlight lang="lua">
-- Código                                               -- Resultado
Date = require('Módulo:Date')._Date
fecha = Date('juliandate', 320)
número = fecha.gsd                                       -- -1721105
número = fecha.jd                                        -- 320
texto = fecha.dayname                                    -- sábado
texto = fecha:text()                                     -- 9 de octubre de 4713&nbsp;a. C.
texto = fecha:text('%Y-%m-%d')                           -- 4713-10-09
texto = fecha:text('%{era} %Y-%m-%d')                    -- a. C. 4713-10-09
texto = fecha:text('%Y-%m-%d %{era}')                    -- 4713-10-09&nbsp;BC
texto = fecha:text('%Y-%m-%d %{era}', 'era=B.C.E.')      -- 4713-10-09&nbsp;B.C.E.
texto = fecha:text('%Y-%m-%d', 'era=BCNEGATIVE')         -- -4712-10-09
texto = fecha:text('%Y-%m-%d', 'era=BCMINUS')            -- −4712-10-09 (utiliza el símbolo menos de Unicode U+2212)
texto = Date('juliandate',320):text('%{gsd} %{jd}')     -- -1721105 320
texto = Date('oct 9, 4713 B.C.E.'):text('%{gsd} %{jd}') -- -1721105 320
texto = Date(-4712,10,9):text('%{gsd} %{jd}')           -- -1721105 320
</syntaxhighlight>

== Diferencia de fechas ==

La diferencia entre dos fechas se puede determinar utilizando <code>fecha1 - fecha2</code>. El resultado es válido si las dos fechas utilizan el mismo calendario siendo 'nil' en otro caso. Es posible calcular una edad o una duración a partir de la diferencia entre dos fechas.

Por ejemplo:
<syntaxhighlight lang="lua">
-- Código                                    -- Resultado
Date = require('Módulo:Date')._Date
fecha1 = Date('21 mar 2015')
fecha2 = Date('4 dic 1999')
diff = fecha1 - fecha2
d = diff.age_days                            -- 5586
y, m, d = diff.years, diff.months, diff.days -- 15, 3, 17 (15 años + 3 meses + 17 días)
y, m, d = diff:age('ymd')                    -- 15, 3, 17
y, m, w, d = diff:age('ymwd')                -- 15, 3, 2, 3 (15 años + 3 meses + 2 semanas + 3 días)
y, m, w, d = diff:duration('ymwd')           -- 15, 3, 2, 4
d = diff:duration('d')                       -- 5587 (duración en días incluyendo el último día)
</syntaxhighlight>

Una diferencia de fechas mantiene las fechas originales pero están cambiadas de tal forma que <code>diff.date1 >= diff.date2</code> (siendo siempre <code>diff.date1</code> la más reciente). Esto se muestra a continuación.
<syntaxhighlight lang="lua">
fecha1 = Date('21 mar 2015')
fecha2 = Date('4 dic 1999')
diff = fecha1 - fecha2
neg = diff.isnegative                        -- false
text = diff.date1:text()                     -- 21 de marzo de 2015
text = diff.date2:text()                     -- 4 de diciembre de 1999
diff = fecha2 - fecha1
neg = diff.isnegative                        -- true (se han cambiado las fechas de orden)
text = diff.date1:text()                     -- 21 de marzo de 2015
text = diff.date2:text()                     -- 4 de diciembre de 1999
</syntaxhighlight>

Una diferencia de fechas también guarda la diferencia de tiempo:
<syntaxhighlight lang="lua">
fecha1 = Date('8 mar 2016 0:30:45')
fecha2 = Date('19 ene 2014 22:55')
diff = fecha1 - fecha2
y, m, d = diff.years, diff.months, diff.days      -- 2, 1, 17
H, M, S = diff.hours, diff.minutes, diff.seconds  -- 1, 35, 45
</syntaxhighlight>

Una diferencia de fechas también se puede añadir o restar a una fecha.
<syntaxhighlight lang="lua">
fecha1 = Date('8 mar 2016 0:30:45')
fecha2 = Date('19 ene 2014 22:55')
diff = fecha1 - fecha2
fecha3 = fecha2 + diff
fecha4 = fecha1 - diff
texto = date3:text('ymd hms')        -- 2016-03-08 00:30:45
texto = date4:text('ymd hms')        -- 2014-01-19 22:55:00
igualdad = (fecha1 == fecha3)        -- true
igualdad = (fecha2 == fecha4)        -- true
</syntaxhighlight>

Los métodos de edad 'age' y duración 'duration' aceptan un código que identifica los componentes a retornar. En el caso de la duración se incluye un día extra (el último).
{| class="wikitable"
! Código !! Valores retornados
|-
| <code>'ymwd'</code> || años, meses, semanas, días
|-
| <code>'ymd'</code>  || años, meses, días
|-
| <code>'ym'</code>   || años, meses
|-
| <code>'y'</code>    || años
|-
| <code>'m'</code>    || meses
|-
| <code>'wd'</code>   || semanas, días
|-
| <code>'w'</code>    || semanas
|-
| <code>'d'</code>    || días
|}

== Compatibilidad ==
Este módulo implementa las funciones de [[Módulo:Fecha]] y [[Módulo:Fechas]], los tests de ambos módulos se encuentran funcionando contra este en [[Módulo:Date/tests]] y el resultado de su ejecución en [[Módulo discusión:Date/tests]].

<includeonly>
<!-- Coloca las categorías del módulo a continuación y los interwikis en Wikidata -->
[[Categoría:Wikipedia:Módulos]]
</includeonly>