harbour-core/harbour/doc/es/datetime.txt

/*
 * $Id$
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Alejandro de G rate <alex_degarate@hotmail.com>
 * Documentaci¢n en Espa¤ol de:
 *      CDOW(),CMONTH(),DATE(),CTOD(),DAY(),DAYS(), DOW(),DTOS(),
 *      DTOC(),ELAPTIME(),MONTH(),SECONDS(),SECS(),TIME(),YEAR()
 *
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 * Documentation en Ingl‚s de:
 *      CDOW(),CMONTH(),DATE(),CTOD(),DAY(),DAYS(), DOW(),DTOS(),
 *      DTOC(),ELAPTIME(),MONTH(),SECONDS(),SECS(),TIME(),YEAR()
 *
 * Vea doc/license.txt por los t‚rminos de la licencia.
 *
 */


/*  $DOC$
 *  $FUNCNAME$
 *      CDOW()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte una fecha al Nombre del d¡a de la semana
 *  $SYNTAX$
 *      CDOW(<dFecha>)  --> cDia
 *  $ARGUMENTS$
 *      <dFecha>  Cualquier expresi¢n de fecha.
 *  $RETURNS$
 *      <cDia>  El d¡a actual de la semana.
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve una cadena de caracteres con el d¡a de la
 *      semana de una expresi¢n de fecha <dFecha> pasada (DOW=day of week en
 *      ingl‚s). Si una fecha NULL es pasada a la funci¢n, el valor de la
 *      funci¢n ser un byte NULL.
 *  $EXAMPLES$
 *      ? CDOW(DATE())
 *
 *      IF CDOW( DATE() + 10) == "SUNDAY"
 *         ? "Este es un d¡a para el descanso."
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      DAY(),DOW(),DATE(),CMONTH()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      CMONTH()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Retorna una cadena de caracteres con el nombre del mes
 *  $SYNTAX$
 *      CMONTH(<dFecha>)  --> cMes
 *  $ARGUMENTS$
 *      <dFecha>  Cualquier expresi¢n de fecha.
 *  $RETURNS$
 *      <cMes>  el nombre actual del mes
 *  $DESCRIPTION$
 *      Esta funci¢n retorna el nombre del mes (Enero, Febrero, etc.) de una
 *      expresi¢n de fecha <dFecha> pasada a ella.
 *      Si una fecha NULL es pasada a la funci¢n, el valor de la funci¢n ser 
 *      un byte NULL.
 *      Nota: El valor devuelto depende del m¢dulo de lenguaje en uso.
 *  $EXAMPLES$
 *      ? CMONTH( DATE())          // resultado: Noviembre
 *
 *      IF CMONTH( DATE() + 35) =="Diciembre"
 *         ? "Ha hecho compras para las fiestas ?"
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      CDOW(),DATE(),MONTH(),YEAR(),DOW(),DTOC()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DATE()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Retorna la fecha actual del sistema operativo
 *  $SYNTAX$
 *      DATE() --> dFechaActual
 *  $ARGUMENTS$
 *      Ninguno
 *  $RETURNS$
 *      <dFechaActual>, la fecha actual del sistema.
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve la fecha actual del sistema.
 *  $EXAMPLES$
 *      ? DATE()
 *  $TESTS$
 *      ? "Hoy es ",DAY( DATE())," de ",CMONTH( DATE())," de ",YEAR( DATE())
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      CTOD(),DTOS(),DTOC(),DAY(),MONTH(),CMONTH()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      CTOD()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte una cadena de caracteres a una expresi¢n de fecha
 *  $SYNTAX$
 *      CTOD(<cCadenaFecha>)  --> dFecha
 *  $ARGUMENTS$
 *      <cCadenaFecha> Un fecha en el formato 'mm/dd/yy'
 *  $RETURNS$
 *      <dFecha> Una expresi¢n de fecha.
 *  $DESCRIPTION$
 *      Esta funci¢n convierte una fecha que ha sido aportada como una
 *      expresi¢n de caracteres a una expresi¢n de fecha. La expresi¢n de
 *      caracteres sera en la forma MM/DD/YY" (basada en el valor por defecto
 *      en SET DATE) o en el formato apropiado especificado por el comado
 *      SET DATE TO. Si una impropia cadena de caracteres es pasada a la
 *      funci¢n, un valor de fecha vac¡a ser  retornado.
 *  $EXAMPLES$
 *      ? CTOD('12/21/00')
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      SET DATE,DATE(),DTOS()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DAY()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Retorna el n£mero de d¡a del mes en el rango de 0 a 31
 *  $SYNTAX$
 *      DAY(<cFecha>) --> nMes
 *  $ARGUMENTS$
 *      <cFecha> Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *     Retorna <nMes>, el valor num‚rico del d¡a del mes.
 *  $DESCRIPTION$
 *      Esta funci¢n retorna el valor num‚rico del d¡a del mes de una fecha.
 *  $EXAMPLES$
 *      ? DAY( CTOD("06/06/1944") )     // Resultado: 6
 *      ? DAY( DATE() + 6325)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      CTOD(),DTOS(),DTOC(),DATE(),MONTH(),CMONTH()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DAYS()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte los segundos transcurridos a d¡as.
 *  $SYNTAX$
 *      DAYS(<nSegundos> ) --> nDia
 *  $ARGUMENTS$
 *      <nSegundos> el n£mero de segundos.
 *  $RETURNS$
 *      Retorna el n£mero de d¡as transcurridos
 *  $DESCRIPTION$
 *      Esta funci¢n convierte <nSegundos> al n£mero equivalente de d¡as;
 *      86399 segundos representan un d¡a, cero segundos es medianoche.
 *  $EXAMPLES$
 *      ? DAYS( 2434234)
 *      ? "Han transcurrido ", DAYS(63251)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *      Nota: No esta documentada en las NG, ni en el manual en espa¤ol de
 *            CA-Cl*pper
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      SECONDS(),SECS(),ELAPTIME()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DOW()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte una fecha al n£mero del dia de la semana (1-7)
 *  $SYNTAX$
 *      DOW(<dFecha>) --> nDia
 *  $ARGUMENTS$
 *      <dFecha>  Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *      DOW() retorna el dia de la semana en la forma num‚rica <nDay>
 *  $DESCRIPTION$
 *      Esta funci¢n convierte un valor de fecha en un n£mero representando
 *      el dia de la semana. En el rango de 1 al 7, siendo 1 el dia Domingo
 *      y 7 el dia S bado.
 *  $EXAMPLES$
 *      ? DOW( DATE())
 *      ? DOW( DATE() - 6584)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      DTOC(),CDOW(),DATE(),DTOS(),DAY()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DTOC()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte un valor de fecha a una cadena de caracteres
 *  $SYNTAX$
 *      DTOC(<dFecha>)  --> cFecha
 *  $ARGUMENTS$
 *      <dFechaString> Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *      Retorna la cadena de caracteres <cFecha> representando la fecha
 *  $DESCRIPTION$
 *      Esta funci¢n convierte una expresi¢n de fecha (sea un campo ¢ una
 *      variable) expresada como <dFecha> a una expresi¢n de caracteres en el
 *      formato por defecto "MM/DD/YY". El formato de fecha devuelto por esta
 *      funci¢n es controlado por el formato especificado por el comando
 *      SET DATE y es variable a diferencia del devuelto por la funci¢n
 *      DTOS().
 *  $EXAMPLES$
 *      ? DTOC( DATE())
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      SET DATE,DATE(),DTOS()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DTOS()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Convierte un valor de fecha a una cadena en el formato AAAAMMDD
 *  $SYNTAX$
 *      DTOS(<dFecha>)  --> cFecha
 *  $ARGUMENTS$
 *      <dFecha> Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *      DTOS() retorna <cFecha>
 *  $DESCRIPTION$
 *      Esta funci¢n convierte un valor de fecha a una cadena de 8 caracteres
 *      en el formato AAAAMMDD (no contiene separadores). Si el valor de
 *      <dFecha> es una fecha vac¡a, esta funci¢n retorna una cadena de
 *      caracteres de 8 espacios en blanco.
 *  $EXAMPLES$
 *      ? DTOS( DATE())
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      DTOC(),DATE(),DTOS()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      ELAPTIME()
 *  $CATEGORY$
 *      Hora
 *  $ONELINER$
 *      Calcula el tiempo transcurrido.
 *  $SYNTAX$
 *      ELAPTIME(<cHoraInicial>,<cHoraFinal>) --> cTranscurrido
 *  $ARGUMENTS$
 *      <cHoraInicial> Hora de inicio en el formato de cadena HH:MM:SS
 *      <cHoraFinal>   Hora de finalizaci¢n en el formato de cadena HH:MM:SS
 *  $RETURNS$
 *      <cTranscurrido>  Diferencia entre tiempos
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve una cadena que muestra la diferencia entre la
 *      hora inicial representada por <cHoraInicial> y la hora final
 *      representada por <cHoraFinal>. Si la hora de inicio es mayor que la
 *      de finalizaci¢n, la funci¢n asume que la fecha a cambiado una vez.
 *  $EXAMPLES$
 *      // Muestra el tiempo que se uso el programa parecido a como lo
 *      // hac¡a el viejo Norton Utilities
 *      STATIC cHoraIni       // al inicio del programa
 *      cHoraIni := TIME()
 *
 *      // A la salida del programa
 *      ? "Ud. ha usado el programa durante: ", ELAPTIME( cHoraIni, TIME())
 *      QUIT
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      SECS(),SECONDS(),TIME(),DAY()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      MONTH()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Extrae el mes como valor num‚rico de un valor de fecha dado
 *  $SYNTAX$
 *      MONTH(<dFecha>) --> nMes
 *  $ARGUMENTS$
 *      <dFecha> Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *      MONTH() retorna <nMes>, n£mero correspondiente al mes del a¤o, en el
 *      rango de 0 a 12.
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve el valor num‚rico del mes contenido en <dFecha>.
 *      Este valor esta en el formato de cuatro d¡gitos y no es afectado
 *      por el seteo de los comandos SET CENTURY y SET DATE.
 *      Si se pasa una fecha vac¡a CTOD("") a esta funci¢n devuelve el valor
 *      cero.
 *  $EXAMPLES$
 *      ? Month(DATE())
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      CDOW(),DOW(),YEAR(),CMONTH()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      SECONDS()
 *  $CATEGORY$
 *      Hora
 *  $ONELINER$
 *      Retorna el n£mero de segundos transcurridos desde medianoche.
 *  $SYNTAX$
 *      SECONDS() --> nSegundos
 *  $ARGUMENTS$
 *      Ninguno
 *  $RETURNS$
 *      SECONDS() retorna <nSegundos> desde la medianoche.
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve un valor num‚rico representando el n£mero de
 *      segundos transcurridos desde la medianoche del d¡a actual, basado en
 *      la hora actual del sistema operativo.
 *      SECONDS() se inicializa en cero (medianoche) y continua hasta 86399
 *      segundos (23:59:59). El valor que devuelve es expresado como segundos
 *      y cent‚simas de segundo.
 *  $EXAMPLES$
 *      // Muestra el tiempo que estuvo en ejecuci¢n una rutina
 *      nArranque = SECONDS()
 *
 *      // Aca va la llamada a la rutina
 *      //  : :
 *      ? "Tard¢: ", SECONDS()- nArranque  ," segundos"
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      TIME()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      SECS()
 *  $CATEGORY$
 *      Hora
 *  $ONELINER$
 *      Retorna el n£mero de segundos de la hora del sistema.
 *  $SYNTAX$
 *      SECS( <cHora> ) --> nSegundos
 *  $ARGUMENTS$
 *      <cHora> Expresi¢n de caracteres en el formato de tiempo HH:MM:SS
 *  $RETURNS$
 *      SECS() retorna <nsegundos> Numbero de segundos
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve un valor num‚rico que es el n£mero de segundos
 *      transcurridos desde medianoche, basados en una cadena de hora dado
 *      como <cHora>.
 *  $EXAMPLES$
 *      ? SECS( TIME())
 *      ? SECS( TIME() - 10)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *      Nota: No esta documentada en las NG, ni en el manual en espa¤ol de
 *            CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      SECONDS(),ELAPTIME(),TIME()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      TIME()
 *  $CATEGORY$
 *      Hora
 *  $ONELINER$
 *      Retorna la hora del sistema como una cadena de caracteres
 *  $SYNTAX$
 *      TIME() --> cHora
 *  $ARGUMENTS$
 *      Ninguno
 *  $RETURNS$
 *      TIME() retorna la cadena de caracteres <cHora> representando la hora
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve la hora del sistema representada como una
 *      expresi¢n de caracteres en el formato HH:MM:SS, para calculos de
 *      tiempo conviene usar SECONDS().
 *  $EXAMPLES$
 *      ? TIME()   // Resultado: 21:34:12
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      DATE(),SECONDS()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      YEAR()
 *  $CATEGORY$
 *      Fecha
 *  $ONELINER$
 *      Extrae el a¤o como valor num‚rico de un valor de fecha dado
 *  $SYNTAX$
 *      YEAR(<dFecha>) --> nAno
 *  $ARGUMENTS$
 *      <dFecha> Cualquier expresi¢n v lida de fecha.
 *  $RETURNS$
 *      YEAR() retorna <nAno> la porci¢n de a¤o de una fecha.
 *  $DESCRIPTION$
 *      Esta funci¢n devuelve el valor num‚rico del a¤o contenido en <dFecha>
 *      Este valor esta en el formato de cuatro d¡gitos y no es afectado
 *      por el seteo de los comandos SET CENTURY y SET DATE.
 *      Si se pasa una fecha vac¡a CTOD("") a esta funci¢n devuelve el valor
 *      cero.
 *  $EXAMPLES$
 *      ? YEAR( DATE())                // Resultado: 2000
 *      ? YEAR( CTOD("01/31/1982"))    // Resultado: 1982
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta funci¢n es totalmente compatible con CA-Cl*pper.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librer¡a es rtl
 *  $SEEALSO$
 *      DAY(),MONTH()
 *  $END$
 */