Skip to content

2.6 Date and time manipulation

Jump to bottom
Juan Luis Gamero edited this page Mar 12, 2014 · 1 revision

2.6 Date and time manipulation

In addition to the DATE (D) data type Harbour has the new TIMESTAMP (T) data type, wich defines in an unique value the date and the time information. Aside from several Harbour extended functions to manipulate date values, there are a set of new functions to manage this new data type.

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_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_StoD( [ <cDate> ] ) -> <dDate>
Harbour extension, counterpart of the standard DtoS() function, that converts a string representing a date with the format YYYYMMDD to a date value. If no <cDate> is supplied, and empty date string will be returned.
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_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_TtoD( <dDate> | <tTimeStamp> [ , @<nSeconds>|@<cTime>, @<cTimeFormat> ] ) -> <dDate>

Extract date and time information from a timestamp or date value. It returns the date part as a date value. If <nSeconds> parameter is supplied by reference then it stores in it the number of seconds in given day specified by timestamp value. If 3-rd parameter <cTimeFormat> is supplied, then this function stores time part in 2-nd parameter <cTime> as a string. If empty <cTimeFormat> is passed, then _SET_TIMEFORMAT is used.

Examples:

HB_TtoD( HB_DateTime(), @nSeconds )            /* nSeconds = 757.99 */
HB_TtoD( HB_DateTime(), @cTime, "hh:mm:ss" )   /* cTime = "06:18:15" */
HB_TtoD( HB_DateTime(), @cTime, "" )           /* cTime = "06:18:15.805" <- _SET_TIMEFORMAT used */
? HB_TtoD( Date() )                            /* 2014-03-31 <- _SET_DATEFORMAT used */

HB_NtoT( <nValue> ) -> <tTimeStamp>

HB_TtoN( <dDate> | <tTimeStamp> ) -> <nValue>
Converts between a numeric value <nValue> and a timestamp <tTimeStamp>. The integer part of <nValue> is the date part represented as a julian date value, and the decimal part of <nValue> is the time part represented as milliseconds from midnight.

HB_TtoC( <dDate> | <tTimeStamp> [ , <cDateFormat>, <cTimeFormat> ] ) -> <cTimeStamp>

HB_CtoT( <cTimeStamp> [ , <cDateFormat>, <cTimeFormat> ] ) -> <tTimeStamp>
Converts between timestamp values and timestamp string representations. 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_TtoS( <dDate> | <tTimeStamp> ) -> <cDateTime>

HB_StoT( <cDateTime> ) -> <tTimeStamp>

Converts between timestamp values and plain datetime string representations. HB_TtoS() allways return <cDateTime> with the format YYYYMMDDHHMMSSFFF. When <cDateTime> is passed to HB_StoT() it should be as one of the formats bellow:

  • YYYYMMDDHHMMSSFFF
  • YYYYMMDDHHMMSSFF
  • YYYYMMDDHHMMSSF
  • YYYYMMDDHHMMSS
  • YYYYMMDDHHMM
  • YYYYMMDDHH
  • YYYYMMDD
  • HHMMSSFFF
  • HHMMSSF
  • HHMMSS
  • HHMM
  • HH

where:

  • Y are year digits.
  • M are month digits.
  • D are day digits.
  • H are hour digits.
  • M are minute digits.
  • S are second digits.
  • F are fraction (milliseconds) digits.

HB_TStoStr( <tTimeStamp> [ , <lPacked> ] ) -> <cTimeStamp>

HB_StrToTS( <cTimeStamp> ) -> <tTimeStamp>

Converts between timestamp values and timestamp string representation. HB_TStoStr() always 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. <cTimeStamp> value passed to HB_StrToTS() should be as in the formats below:

  • YYYY-MM-DD [H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]
  • YYYY-MM-DDT[H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]

The following characters can be used as date delimiters: (-), (/), (.). T is literal "T" and it's for XML timestamp format. If PM or AM is used then HH is in range < 1 : 12 > otherwise is in range < 0 : 23 >.

HB_Hour( <tTimeStamp> ) -> <nHour>

HB_Minute( <tTimeStamp> ) -> <nMinute>

HB_Sec( <tTimeStamp> ) -> <nSeconds>
This group of functions returns the hour, minutes and seconds (with milliseconds) of a timestamp value.
HB_UtcOffset( [ <tLocalTime> ] ) -> <nSeconds>
Returns the UTC offset as a signed number of seconds.
HB_TStoUtc( [ <tLocalTime> ] ) -> <tUtcTime>
Converts a TIMESTAMP in local time to UTC time.
Clone this wiki locally