/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      CDoW()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Converts a date to the day of week
   $SYNTAX$
      CDoW( <dDate> ) --> cDay
   $ARGUMENTS$
      <dDate>  Any date expression.
   $RETURNS$
      <cDay>  The current day of week.
   $DESCRIPTION$
      This function returns a character string of the day of the week,
      from a date expression <dDate> passed to it.
      If a NULL date is passed to the function, the value of the function
      will be a NULL byte.
   $EXAMPLES$
      ? CDoW( Date() )
      IF CDoW( Date() + 10 ) == "Sunday"
         ? "This is a sunny day."
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Day(), DoW(), Date(), CMonth()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      CMonth()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Return the name of the month.
   $SYNTAX$
      CMonth( <dDate> ) --> cMonth
   $ARGUMENTS$
      <dDate>  Any date expression.
   $RETURNS$
      <cMonth>  The current month name
   $DESCRIPTION$
      This function returns the name of the month (January, February, etc.)
      from a date expression <dDate> passed to it.
      If a NULL date is passed to the function, the value of the function
      will be a NULL byte.
   $EXAMPLES$
      ? CMonth( Date() )
      IF CMonth( Date() + 10 ) == "March"
         ? "Have you done your system backup?"
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      CDoW(), Date(), Month(), Year(), DoW(), DToC()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Date()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Return the Current OS Date
   $SYNTAX$
      Date() --> dCurDate
   $ARGUMENTS$
      None
   $RETURNS$
      <dCurDate>  Current system date.
   $DESCRIPTION$
      This function returns the current system date.
   $EXAMPLES$
      ? Date()
      ? "Today is", hb_ntos( Day( Date() ) ), "of", CMonth( Date() ), "of", StrZero( Year( Date() ), 4 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      CToD(), DToS(), DToC(), Day(), Month(), CMonth()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      CToD()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Converts a character string to a date expression
   $SYNTAX$
      CToD( <cDateString> ) --> dDate
   $ARGUMENTS$
      <cDateString> A character date in format "mm/dd/yy"
   $RETURNS$
      <dDate> A date expression
   $DESCRIPTION$
      This function converts a date that has been entered as a character
      expression to a date expression. The character expression will be in
      the form `MM/DD/YY` (based on the default value in `SET DATE`) or in
      the appropriate format specified by the `SET DATE TO` command. If an
      improper character string is passed to the function, an empty date
      value will be returned.
   $EXAMPLES$
      Set( _SET_DATEFORMAT, "yyyy-mm-dd" )
      ? CToD( "2000-12-21" )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      SET DATE, Date(), DToS()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Day()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Return the numeric day of the month.
   $SYNTAX$
      Day( <cDate> ) --> nMonth
   $ARGUMENTS$
      <cDate> Any valid date expression.
   $RETURNS$
      <nMonth> Numeric value of the day of month.
   $DESCRIPTION$
      This function returns the numeric value of the day of month from a
      date.
   $EXAMPLES$
      ? Day( Date() )
      ? Day( Date() + 6325 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      CToD(), DToS(), DToC(), Date(), Month(), CMonth()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Days()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Convert elapsed seconds into days
   $SYNTAX$
      Days( <nSecs> ) --> nDay
   $ARGUMENTS$
      <nSecs> The number of seconds
   $RETURNS$
      <nDay>  The number of days
   $DESCRIPTION$
      This function converts <nSecs> seconds to the equivalent number
      of days; 86399 seconds represents one day, 0 seconds being midnight.
   $EXAMPLES$
      ? Days( 2434234 )
      ? Days( 63251 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Seconds(), Secs(), ElapTime()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      DoW()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Value for the day of week.
   $SYNTAX$
      DoW( <dDate> ) --> nDay
   $ARGUMENTS$
      <dDate>  Any valid date expression
   $RETURNS$
      <nDay>  The current day number
   $DESCRIPTION$
      This function returns the number representing the day of the week
      for the date expressed as <dDate>.
      Returned value range is from 1 (Sunday) to 7 (Saturday).
   $EXAMPLES$
      ? DoW( Date() )
      ? DoW( Date() - 6584 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      DToC(), CDoW(), Date(), DToS(), Day()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      DToC()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Date to character conversion
   $SYNTAX$
      DToC( <dDateString> ) --> cDate
   $ARGUMENTS$
      <dDateString> Any date
   $RETURNS$
      <dDate> Character representation of date
   $DESCRIPTION$
      This function converts any date expression (a field or variable)
      expressed as <dDateString> to a character expression in the default
      format `MM/DD/YY`. The date format expressed by this function is
      controlled in part by the date format specified in the `SET DATE`
      command
   $EXAMPLES$
      ? DToC( Date() )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      SET DATE, Date(), DToS()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      DToS()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Date to string conversion
   $SYNTAX$
      DToS( <dDateString> ) --> cDate
   $ARGUMENTS$
      <dDateString> Any date
   $RETURNS$
      <dDate> String notation of the date
   $DESCRIPTION$
      This function returns the value of <dDateString> as a character
      string in the format of `YYYYMMDD`. If the value of <dDateString> is
      an empty date, this function will return eight blank spaces.
   $EXAMPLES$
      ? DToS( Date() )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      DToC(), Date(), DToS()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      ElapTime()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Calculates elapsed time.
   $SYNTAX$
      ElapTime( <cStartTime>, <cEndTime> ) --> cDifference
   $ARGUMENTS$
      <cStartTime> Start in time as a string format
      <cEndTime>   End time as a string format
   $RETURNS$
      <cDifference>  Difference between the times
   $DESCRIPTION$
      This function returns a string that shows the difference between
      the starting time represented as <cStartTime> and the ending time
      as <cEndTime>. If the stating time is greater then the ending
      time, the function will assume that the date changed once.
   $EXAMPLES$
      STATIC s_cStartTime
      INIT PROCEDURE Startup()
         s_cStartTime := Time()
         RETURN
      EXIT PROCEDURE StartExit()
         ? "You used this program by", ElapTime( s_cStartTime, Time() )
         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Secs(), Seconds(), Time(), Day()
   $END$
 */

/* $DOC$
   $AUTHOR$
      2017 Pete D. <pete_westg@yahoo.gr>
   $TEMPLATE$
      Function
   $NAME$
      hb_Week()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Returns the week number of year.
   $SYNTAX$
      hb_Week( <dDate>, [@<nYear>], [@<nDayOfWeek>] ) --> nWeekNumber
   $ARGUMENTS$
      <dDate> Any valid date expression.

      <nYear> Optional parameter to hold the year of the given date.

      <nDayOfWeek> Optional parameter to hold the day number of week.
   $RETURNS$
      <nWeekNumber> The ordinal week number of the year into which falls
                    the given <dDate>.
   $DESCRIPTION$
      This function returns the week number of year for the given <dDate>.
      The returned value is an ISO 8601 compliant week number.
      Optionally, can also be obtained the year and/or the day number of
      the week of the given <dDate>, if the <nYear> and/or <nDayOfWeek>
      parameters have been passed by reference.
      If <dDate> is an empty date expression, the function returns zero(s).
      Note: new function available after 2017-02-08 19:36 UTC+0100 commit,
            not found in earlier versions.
   $EXAMPLES$
      LOCAL nYear, nDayOfWeek
      ? hb_Week( 0d20170215, @nYear, @nDayOfWeek ), nYear, nDayOfWeek  // --> 7, 2017, 3
      ? hb_Week( 0d00000000, @nYear, @nDayOfWeek ), nYear, nDayOfWeek  // --> 0, 0, 0
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Year(), Month(), Day()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Month()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Converts a date expression to a month value
   $SYNTAX$
      Month( <dDate> ) --> nMonth
   $ARGUMENTS$
      <dDate> Any valid date expression
   $RETURNS$
      <nMonth> Corresponding number of the month in the year, ranging from
       0 to 12
   $DESCRIPTION$
      This function returns a number that represents the month of a given
      date expression <dDate>. If a NULL date (`hb_SToD()`) is passed to the
      function, the value of the function will be 0.
   $EXAMPLES$
      ? Month( Date() )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      CDoW(), DoW(), Year(), CMonth()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Seconds()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Returns the number of elapsed seconds past midnight.
   $SYNTAX$
      Seconds() --> nSeconds
   $ARGUMENTS$
      None
   $RETURNS$
      <nSeconds> Number of seconds since midnight
   $DESCRIPTION$
      This function returns a numeric value representing the number of
      elapsed seconds based on the current system time.
      The system time is considered to start at 0 (midnight); it continues
      up to 86399 seconds. The value of the return expression is displayed
      in both seconds and hundredths of seconds.
   $EXAMPLES$
      ? Seconds()
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Time()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Secs()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Return the number of seconds from the system date.
   $SYNTAX$
      Secs( <cTime> ) --> nSeconds
   $ARGUMENTS$
      <cTime> Character expression in a time string format
   $RETURNS$
      <nSeconds> Number of seconds
   $DESCRIPTION$
      This function returns a numeric value that is a number of elapsed
      seconds from midnight based on a time string given as <cTime>.
   $EXAMPLES$
      ? Secs( Time() )
      ? Secs( Time() - 10 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Seconds(), ElapTime(), Time()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Time()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Returns the system time as a string
   $SYNTAX$
      Time() --> cTime
   $ARGUMENTS$
      None
   $RETURNS$
      <cTime> Character string representing time
   $DESCRIPTION$
      This function returns the system time represented as a character
      expression in the format of `HH:MM:SS`
   $EXAMPLES$
      ? Time()
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Date(), Seconds()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Function
   $NAME$
      Year()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Extracts the year designator of a given date as a numeric value
   $SYNTAX$
      Year( <dDate> ) --> nYear
   $ARGUMENTS$
      <dDate> Any valid date expression
   $RETURNS$
      <nYear> The year portion of the date.
   $DESCRIPTION$
      This function returns the numeric value for the year in <dDate>.
      The returned value is not affected by the `SET CENTURY` and `SET DATE`
      settings and will always be a four-digit year number, unless the <dDate>
      is an empty date expression, in which case it will be zero.
   $EXAMPLES$
      ? Year( Date() )
      ? Year( 0d32510125 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Day(), Month()
   $END$
 */

/* $DOC$
   $AUTHOR$

   $TEMPLATE$
      Function
   $NAME$
      hb_DToT()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Date/Time
   $ONELINER$
      Create a <tDateTime> value from a <dDate> parameter
   $SYNTAX$
      hb_DToT( <dDate> [, <cTime|nSeconds>] ) --> <tDateTime>
   $ARGUMENTS$
      <dDate> Any valid date expression.

      Optional: <cTime|nSeconds> representing a time of the day value.
      <cTime> is a string in a valid time format: "hh:mm:ss.nnn".
      <nSeconds> is a numeric value in seconds in the range from
      0 to 86399.999~ ( 60 secs * 60 mins * 24 hours - 1 millisecond )
   $RETURNS$
      <tDateTime> a dateTime value
   $DESCRIPTION$
      This function returns a <tDateTime> value from a <dDate> value.
      Optionally, a second parameter with the time of the day value
      can be provided which can be represented by either of a string
      time value or a numeric value in seconds.
   $EXAMPLES$
      ? hb_DToT( Date() )  // a dateTime with a empty time part
      ? hb_DToT( Date(), "14:30:00.500" )  // a dateTime with time part 14:30pm with 500 milliseconds
      ? hb_DToT( Date(), 3600 )  // a dateTime with time part 1:00am (one hour)
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Date()
   $END$
 */
