Language Elements and Reference:xpplrm

Operations using date values Foundation

Values of the "date" data type represent calendar dates. Date calculations can be performed with date values using the plus and minus operators. As with numeric values, the two unary operators can increment and decrement date values. The precedence of the increment and decrement operators depends on whether prefix or postfix notation is used (see the chapter "Operators"). A complete list of all operators available for use with date values is shown in the following table:

Operators for date values
Operator Description
++ Increment (unary)
-- Decrement (unary)
+ Add numeric value (number of calendar days) to date value
- Subtract date value
== Comparison: equal
!= <> # Comparison: not equal
> Comparison: greater than
>= Comparison: greater than or equal
= Comparison: equal
<= Comparison: less than or equal
< Comparison: less than
= Assignment
:= Inline assignment
+= Inline addition
-= Inline subtraction

There are no literals for date values. Date values must be created from character strings using the function CtoD() or by calling the function Date() which returns the current system date as a date value. An empty date is created by the expression CtoD("") which passes a null string to the function CtoD().

When using the plus and minus operators, both operands must generally be of the same data type. An exception is date calculations which allow one operand to be of numeric data type. These calculations can occur using two different data types. In the case of date subtraction the result is a numeric value giving the difference between the two date values as the number of days. The other mathematical operations with date values have a date value as the result.

? dDate := Date()                // result: 12/24/94 
? dDate ++                       // result: 12/25/94 
? dDate --                       // result: 12/24/94 

? dDate := dDate + 6             // result: 12/30/94 
? dDate - Date()                 // result: 6 
? dDate -= 2                     // result: 12/28/94 
? dDate += 4                     // result: 01/01/95 

As with the comparison of numeric values, the setting SET EXACT does not affect the comparison of date values. There are three settings that affect date values: SET DATE, SET CENTURY and SET EPOCH . The first two settings affect the display format for date values. SET DATE changes the default display format defined by the country specific Xbase++ version. SET CENTURY turns the display of the century on or off. SET EPOCH determines which century a date value belongs to if it is created from a character string that does not specify the century (see the various SET commands in the reference documentation).

The functions that perform operations with date values mainly provide transformation of date values into character strings or numeric values. The following table lists all of the functions for date values:

Functions for date values
Function Description
CDow() Determines name of week day as a character string
CMonth() Determines name of month as a character string
Day() Determines calendar day as numeric value
Descend() Converts date value for descending sorting
DoW() Determines day of week as numeric value
DtoC() Converts date value to character string (display format)
DtoS() Converts date value to character string (sort format)
Empty() Tests whether date is empty
FieldPut() Assigns date value to field variable
FieldGet() Reads date value from field variable
Month() Determines calendar month as numeric value
Transform() Converts date value to formatted character string
Type() Determines data type via macro operator
Valtype() Determines data type
Year() Determines calendar year as a numeric value

There are two functions for converting dates into character strings: DtoC() (date to character) and DtoS() (date to string). The function DtoC() provides a character string which can be displayed in standard date format. DtoS() is needed to correctly sort field variables of the "date" data type and assures the correct chronological order when sorted. The return value of this function is a character string in the format "YYYYMMDD".

The two functions CDow() and CMonth() return the name of the day of the week and the calendar month respectively. The return value of these functions depends on the country specific delivery version of Xbase++.

A short overview of the most important date functions is shown below.

Conversion to character values

? dDate := Date()               // result: 12/24/94 
? CDow(dDate)                   // result: Saturday 
? CMonth(dDate)                 // result: December 
? DtoC(dDate)                   // result: 1/24/94 
? DtoS(dDate)                   // result: 19941224 

Conversion to numeric values

? Day(dDate)                    // result: 24 
? DoW(dDate)                    // result:  7 
? Month(dDate)                  // result: 12 
? Year(dDate)                   // result: 1994 

Other functions for date values

? Empty(dDate)                  // result: .F. 
? Transform(dDate, "@D")        // result: 12/24/94 
? Type("12/24/94")              // result: D 
? Valtype(dDate)                // result: D 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.