Date Time - Petewg/harbour-core GitHub Wiki

πŸ”™ 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

the sunset's small sailing boat Harbour Functions Dictionary   Many of the entries presented in this wiki, have been obtained from various sources (see References); however, a good number of them have been written Β«from scratchΒ» (or rewritten/corrected), particularly those referring to newer Harbour functions. Anyway, it's a 'work in progress', so there might be omissions, oversights and / or errors. That said, any suggestion/correction/comment are more than welcome --many thanks, to those few who already have made contributions!

 * Copyright Β© 2016–present Pete D.
Hits

⚠️ **GitHub.com Fallback** ⚠️