Date Time

🔙 Functions-by-category

Dates, Time and Timestamps functions. Harbour offers an interesting collection about them.
Worth to note that the internal date representation is a 32-bit integer number, that designates the number of days elapsed starting at noon on Monday, January 1, 4713 BC, known as zero (0) Julian day. Therefore, calculations on date variables are simple integer number operations, so we can effectively make use of basic arithmetic operators like: +, -, ++, --, +=, -=, as well as, comparison operators <, <=, >, >=; however, multiplication and division *, / or other algebraic operations cannot carried out and if attempted, a runtime error (RTE) shall occur.

---

• hb_CDay(<nDay>) ➜ cDayName
  returns the name of day specified by <nDay>. Valid range [ 1 ... 7 ]. Returns empty string if <nDay> is out of valid range. RTE occurs if <nDay> is NIL (i.e. not passed).
  Worth noting that the returned value is identical to that of CDoW() but the later accepts a date value as parameter.

• hb_CtoD(<cDate> [, <cDateFormat>]) ➜ dDate
  Harbour extension to the CtoD() function. It converts a string <cDate> representing a date to a DATE type value. Additionally, the date format used in <cDate> can be supplied in <cDateFormat>, otherwise the _SET_DATEFORMAT format will be used.

• hb_CtoT(<cTimeStamp> [, <cDateFormat>, <cTimeFormat>]) ➜ tTimeStamp
  converts a timestamp string to timestamp value (valtype=T). By default it uses the _SET_DATEFORMAT and _SET_TIMEFORMAT format strings to do the conversion, but you can specify other formats using <cDateFormat> and <cTimeFormat>.

• hb_Date([<nYear>, <nMonth>, <nDay>]) ➜ dDate
  Harbour extension to the Date() function that returns a date value from the supplied day, month and year values. If any of them is invalid or missing, an empty date is returned. If none of them is supplied, the current date is returned.

• hb_DateTime([<nYear>, <nMonth>, <nDay>, <nHour>, <nMinute>, <nSecond>, <nFragment>]) ➜ tTimeStamp
  Returns a timestamp value from the supplied day, month, year, hour, minute, second and second-fragment values. If none of them is supplied, the current date and time is returned.

• hb_DtoC(<dDate>|<tTimeStamp> [, <cDateFormat>]) ➜ cDate
  Harbour extension to the DtoC() function. It converts a date value <dDate> (or the date value of <tTimeStamp>) to a string. If no date format is supplied the _SET_DATEFORMAT format will be used.

• hb_DtoT(<dDate> [, <cnTime>]) ➜ tTimeStamp
  returns a timestamp from the date and time values. <dDate> is a date value and <cnTime> is the time part and could be a number (as from Seconds()) or a string (as from Time()), (see time string format).

• hb_Hour(<tTimeStamp>) ➜ nHour
  returns the hour (HH) part or "member" of a TimeStamp.

• hb_Minute(<tTimeStamp>) ➜ nMinute
  returns the minute (mm) part (or "member") of a TimeStamp.

• hb_NToHour( <nTimeDiff> ) ➜ nHours
  (see below)

• hb_NToMin ( <nTimeDiff> ) ➜ nMinutes
  (see below)

• hb_NToSec ( <nTimeDiff> ) ➜ nSeconds
  (see below)

• hb_NToMSec( <nTimeDiff> ) ➜ nMilliseconds

  The above four functions convert the <nTimeDiff> time difference to hours, minutes, seconds and milliseconds respectively.
  The returned value is a floating point number with fractional part representing the rest (decimal remainder) of conversion, except of hb_NToMSec() function which returns milliseconds as an integer value.
  NOTE 1: new functions, available after 2016-12-15 12:51 UTC+0100 commit (they are not available in earlier versions).
  NOTE 2: These functions must not be confused either with somewhat similarly named hb_Hour(), hb_Minutes(), hb_Sec() since the above ones do convert the numeric time difference (timespan) between two timestamps while the other ones just extract specific members of a given timestamp.
  See also: hb_TToHour(), hb_TToMin(), hb_TToSec(), hb_TToMSec() family, further down the page.

          /* usage example */
          t1 := hb_DateTime() - 0.3
          t2 := hb_DateTime() - t1
          ? hb_NToHour( t2 )
          ? hb_NToMin ( t2 )
          ? hb_NToSec ( t2 )   
          ? hb_NToMSec( t2 )

• hb_NtoT(<nValue>) ➜ tTimeStamp
  converts a numeric value nValue (which is evaluated as if being a Unix time value) to a timestamp.

• hb_Sec(<tTimeStamp>) ➜ nSecond
  returns the seconds (ss) "member" of a tTimeStamp. The returned value is a floating point number (ss.mmm) where the integer part is seconds while the decimal (fraction) part of it represents milliseconds.

• hb_SecToT( <nSeconds> ) ➜ tTime
  converts <nSeconds> seconds to tTimestamp value.

• hb_StoD( [ <cDate> ] ) ➜ dDate
  converts a string representing a date with the format YYYYMMDD to a date value. If no <cDate> is supplied, an empty date string will be returned. (counterpart of the standard DtoS() function).

• hb_StoT( <cDateTime> ) ➜ tTimeStamp
  converts a datetime string to timestamp value (T).

• hb_StrToTS( <cTimeStamp> ) ➜ tTimeStamp
  converts a string cTimeStamp to tTimeStamp timestamp value. The <cTimeStamp> must have the format: YYYY-MM-DD [H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM] or YYYY-MM-DDT[H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]. See also the inverse 'hb_TSToStr()' function.

• hb_TSToStr( <tTimeStamp> [, <lPacked>] ) ➜ cTimeStamp
  returns <cTimeStamp> with the format YYYY-MM-DD hh:mm:ss.fff. If <lPacked> is .T. empty elements of the timestamp will be stripped out.

• hb_TSToUTC( [<tLocalTime>] ) ➜ tUtcTime
  converts a local time tTIMESTAMP to UTC time.

• hb_TtoC( <dDate>|<tTimeStamp> [, <cDateFormat>, <cTimeFormat>] ) ➜ cTimeStamp
  converts date or timestamp values to timestamp formatted strings.

• hb_TtoD( <dDate>|<tTimeStamp> [, @<nSeconds>|@<cTime>, @<cTimeFormat>] ) ➜ dDate
  extracts date and time information from a timestamp or date value. It returns the date part as a date value. If <@nSeconds> or @<cTime> parameter is passed by reference then it obtains either the number of seconds in given day specified by timestamp value or the time as time string. If no <cTimeFormat> passed, then _SET_TIMEFORMAT is used.

• hb_TtoN( <dDate>|<tTimeStamp> ) ➜ nValue
  converts a date or timestamp value to numeric value. The integer part of returned <nValue> is the date part represented as a Julian date value, and the decimal part is the time part represented as milliseconds from midnight.
  NOTE: the returned nValue must not be confused with Unix time number, since they're totally different!

• hb_TtoS( <dDate>|<tTimeStamp> ) ➜ cDateTime
  converts a date or timestamp value to string formated as YYYYMMDDHHMMSSFFF.

• hb_TToHour( <tTimeStamp> ) ➜ nHours
  (see below)

• hb_TToMin ( <tTimeStamp> ) ➜ nMinutes
  (see below)

• hb_TToSec ( <tTimeStamp> ) ➜ nSeconds
  (see below)

• hb_TToMSec( <tTimeStamp> ) ➜ nMilliseconds
  The above four functions calculate/convert the <tTimeStamp> timestamp value to hours, minutes, seconds and milliseconds respectively.
  All but hb_TToMSec() functions return a floating point number, where the fractional part represents the rest (decimal remainder) of the conversion. The hb_TToMSec() function returns milliseconds as an integer value.
  NOTE: new functions, available after 2016-12-15 12:51 UTC+0100 commit (they are not available in earlier versions).

• hb_UTCOffset( [<tLocalTime>] ) ➜ nSeconds
  returns the UTC offset as a signed number of seconds.

• hb_Week( <dDate>, [@<nYear>], [@<nDayOfWeek>] ) ➜ nWeek
  Returns the week number of year for the given <dDate> (the returned value is ISO 8601 compliant).
  Can also grab the year and week day number into <nYear> and/or <nDayOfWeek> optional parameters if they are passed by reference.
  Note: new function available after 2017-02-08 19:36 UTC+0100 commit by Przemyslaw Czerpak

---

Date/time functions found in contrib libraries

• Leap year checking:
  we have two functions (in two different libraries!), that check if a given date
  falls into a leap year:

  • IsLeap([<dDate>]) ➜ .T.|.F.
    Checks if the given <dDate> is a leap year date.
    If <dDate> is not given, it defaults to current date.
    Library is hbct (aka, cl*pper tools)

  • IsLeapYear(<dDate>) ➜ .T.|.F.
    Checks if given <dDate> is a leap year date.
    If <dDate> is not given, function returns .F.
    Library is hbmisc

See also:

• hbct date/time functions
• hbmisc date/time functions
• hbnf date/time functions

🔙 Functions-by-category