Zeos Component Library :

Expression reference guide.

Reference guide for Zeos filter-expressions.

Document version 0.1
November 2009

Guy Fink
Chapter 1

Expressions
The expression parser in Zeos follows the normal Pascal syntax for expressions with some
limitations due to the purpose of the expression and the fact that it is interpreted.

1 Data types
The following data types are available and map to the indicated internal data types:
Boolean : 0 is interpreted as FALSE any other value as TRUE
Integer : 64-bit integer
Float : 10-byte floating point aka EXTENDED
String : standard ANSI-String
UnicodeString : standard WIDE-String
DateTime : TDateTime
Pointer : Pointer
Interface : IZInterface
Internally the expression-parser uses a ligthweight variant type for any variable. Type conversions
are done if they make sense.

2 Operators
The expression parser knows the following operators :
2.1 Arithmetic operators
Arithmetic operators can be used with the following types :
+ Additon Integer, Float, String, DateTime
- Subtraction Integer, Float
* Multiplication Integer, Float
/ Divison Integer, Float
% Modulo Integer
^ Power Integer, Float
2.2 Boolean/Integer operators
The following operators can only be used with boolean or integer types.
AND Logical AND
OR Logical OR
XOR Logical XOR
NOT Logical NOT
For integer types, a bitwise operation is performed.
2.3 Comparison operators
The comparison operators return a boolean value:
= equal
<>, != not equal
> greater than
< less than
>= greater than or equal
<= less than or equal
IS test if a variable is NULL
The IS-Operator can only be used with the special constant NULL as rigth-side operand. NOT
may be used as modificator.
Example :
x IS NULL // returns TRUE if variable x is unassigned
x IS NOT NULL // returns TRUE if variable x is assigned

2.4 String operators

+ Concatenates strings
LIKE special comparison operator for strings

The LIKE-Operator is a special string comparison operator. It takes a regular expression as rigth-
side operand. NOT may be used as modificator.
The LIKE-Operator calls the pattern matching function IsMatch.
Examples from the source file :
IsMatch allows unix grep-like pattern comparisons, for instance:

? Matches any single characer

* Matches any contiguous characters
[abc] Matches a or b or c at that position
[^abc] Matches anything but a or b or c at that position
[!abc] Ditto
[a-e] Matches a through e at that position

'ma?ch.*' -Would match match.exe, mavch.dat, march.on, etc

'this [e-n]s a [!zy]est' - Would match 'this is a test',
but would not match 'this as a yest'
3 Variables
The expression object keeps a list of varibales (property DefaultVariables) witch can be used in
the expression. The usable functions of this list are the following.
procedure Add(const Name: string; const Value: TZVariant);
procedure Remove(const Name: string);
function FindByName(const Name: string): Integer;

procedure ClearValues;
procedure Clear;

property Count: Integer; // read-only

property Names[Index: Integer]: string; // read-only
property Values[Index: Integer]: TZVariant; // read-write
property NamedValues[const Index: string]: TZVariant; // read-write

For the filterexpression object this list is filled with the fields of the corresponding dataset.
To create Variants you can use the following functions from ZVariant.
function EncodeNull : TZVariant;
function EncodeBoolean(const Value: Boolean): TZVariant;
function EncodeInteger(const Value: Int64): TZVariant;
function EncodeFloat(const Value: Extended): TZVariant;
function EncodeString(const Value: String): TZVariant;
function EncodeUnicodeString(const Value: WideString): TZVariant;
function EncodeDateTime(const Value: TDateTime): TZVariant;
function EncodePointer(const Value: Pointer): TZVariant;
function EncodeInterface(const Value: IZInterface): TZVariant;
To convert a Variant back to a Pascal-type use one of the Variantmanagers.
Variables are used in an expression just as they are in Pascal. Keep in mind that there is no
assignement operator.

4 The Variantmanager
The Variantmanager is used to convert the type of variants. 2 different versions are implemented
in ZVariant. DefVariantManager with strict conversion rules, and SoftVariantManager with very
soft conversion rules.
TExpression holds an own VariantManager (property VariantManager) which by default uses the
soft conversion rules.
5 Functions
As a first overview the functions are described by their Pascal-like declaration. They behave like
their Pascal-counterparts, exceptions are documented.
Some of the longname functions have short (rather cryptographic) aliases.

5.1 Math functions

The math functions :

FUNCTION E(): FLOAT; // > EXP(1)

FUNCTION PI(): FLOAT; // > 3.14159.....
FUNCTION RND():FLOAT; // Returns a random float number

FUNCTION ABS(x : FLOAT):FLOAT;

FUNCTION ABS(x : INTEGER):INTEGER;

FUNCTION EXP(x : FLOAT):FLOAT;

FUNCTION LOG(x : FLOAT):FLOAT; // > LN(x)
FUNCTION LOG10(x : FLOAT):FLOAT;

// Trigonometric functions
FUNCTION COS(x : FLOAT):FLOAT;
FUNCTION SIN(x : FLOAT):FLOAT;
FUNCTION TAN(x : FLOAT):FLOAT;
FUNCTION COT(x : FLOAT):FLOAT;

// The parameter range for the inverse trigonometric functions is -1..1

FUNCTION ACOS(x : FLOAT):FLOAT;
FUNCTION ASIN(x : FLOAT):FLOAT;
FUNCTION ATAN(x : FLOAT):FLOAT;

// Rounding functions
FUNCTION CEIL(x : FLOAT):INTEGER; // rounds toward positive infinity
FUNCTION FLOOR(x : FLOAT):INTEGER; // rounds toward negative infinity
FUNCTION ROUND(x : FLOAT):INTEGER;
FUNCTION TRUNC(x : FLOAT):INTEGER;

FUNCTION INT(x : FLOAT):FLOAT;

FUNCTION FRAC(x : FLOAT):FLOAT;

FUNCTION SQR(x : FLOAT):FLOAT; // returns the Squareroot of x

alias
FUNCTION SQRT(x : FLOAT):FLOAT;

5.2 String functions

// Concatenates the strings.
// Concat may be called with a variable number of parameters.
// Alternatly you may use S1+S2..+SN
FUNCTION CONCAT(S1, S2..SN : STRING): STRING;

FUNCTION LENGTH(S : STRING): INTEGER;

FUNCTION SUBSTR(S : STRING; START, LEN : INTEGER) : STRING;

FUNCTION LEFT(S : STRING; LEN : INTEGER) : STRING;
FUNCTION RIGHT(S : STRING; LEN : INTEGER) : STRING;
// Returns the starting position of S1 inside S2
FUNCTION STRPOS(S1, S2 : STRING) : INTEGER;

FUNCTION LOWER(S : STRING) : STRING; //convert all chars in s to lowercase

FUNCTION UPPER(S : STRING) : STRING; //convert all chars in s to uppercase

// Capitalize uppercases the first char of every word in the string. A word
// always starts after one of the chars in DELIM.
// The DELIM parameter is optional and defaults to the shown string.
FUNCTION CAPITALIZE(S : STRING; DELIM : STRING = #0..#32+',.;/\:''"`') : STRING;
alias
FUNCTION CAP(S : STRING; DELIM : STRING = #0..#32+',.;/\:''"`') : STRING;

FUNCTION TRIM(S : STRING) : STRING; //remove all leading and trailing blanks
FUNCTION LTRIM(S : STRING) : STRING; //remove all leading blanks
FUNCTION RTRIM(S : STRING) : STRING; //remove all trailing blanks

// Soundex calculates the soundex key for a given string. This key can be
// used for phonetic comparison. Soundex works only well for english names.
// The LEN-parameter is optional.
FUNCTION SOUNDEX(S : STRING; LEN : INTEGER = 4) : STRING;

// The LevenshteinDistance caculates the number of operations necessary

// to transform S1 to S2. It is therefore an indication of the similarity of
// these strings.
// A LevenshteinDistance of 0 means strings are identical.
// A LevenshteinDistance of 1 means 1 character operation (add, delete or replace)
// is necessary to make the strings identical.
// The optinal parameter DOUPCASE does exactly what it says, it upcases the
// strings before calculating the distance.
// In conjunction with SOUNDEX it can be used to refine phonetic comparisons.
FUNCTION LEVENSHTEINDISTANCE(S1, S2 : STRING; DOUPCASE:BOOLEAN = TRUE) : INTEGER;
alias
FUNCTION LEVDIST(S1, S2 : STRING; DOUPCASE:BOOLEAN = TRUE) : INTEGER;
5.3 Datetime functions

FUNCTION DATE() : DATETIME; //returns the actual date, the time part is 0
FUNCTION TIME() : DATETIME; //returns the actual time, the date part is 0
FUNCTION NOW() : DATETIME; //returns the actual date and time

// Encode a Date
FUNCTION ENCODEDATE( YEAR : INTEGER=0;
MONTH : INTEGER=1;
DAY : INTEGER=1) : DATETIME; // alias ENCD(..)
// The same for the Timepart
FUNCTION ENCODETIME( HOUR : INTEGER=0;
MIN : INTEGER=0;
SEC : INTEGER=0;
MSEC : INTEGER=0) : DATETIME; // alias ENCT(..)

// Combines the Datepart of DATE with the Timepart of TIME

FUNCTION COMPOSEDATETIME( DATE : DATETIME;
TIME : DATETIME) : DATETIME;// alias COMPDT(..)

// Increment a Date. Parameters may also be negative

FUNCTION INCDATE( DATE : DATETIME;
YEAR : INTEGER;
MONTH : INTEGER=0;
WEEK : INTEGER=0;
DAY : INTEGER=0) : DATETIME; // alias INCD(..)

// Increment a Time. Parameters may also be negative.

FUNCTION INCTIME( DT : DATETIME;
HOUR : INTEGER;
MINUTE : INTEGER=0;
SECOND : INTEGER=0;
MSEC : INTEGER=0) : DATETIME; // alias INCT(..)

//true if the year is a leapyear

FUNCTION ISLEAPYEAR(YEAR:INTEGER):BOOLEAN; // alias LEAPY(..)

//returns the date, the time part is set to 0h 0m 0s 0msec

FUNCTION DATEOF(DATE : DATETIME) : DATETIME;
//returns the time, the date part is set to 0
FUNCTION TIMEOF(TIME : DATETIME) : DATETIME;

// The decomposing functions return the named part of a DATETIME

FUNCTION YEAROF(DATE : DATETIME) : INTEGER;
FUNCTION MONTHOF(DATE : DATETIME) : INTEGER;
FUNCTION DAYOF(DATE : DATETIME) : INTEGER;

FUNCTION HOUROF(TIME : DATETIME) : INTEGER;

FUNCTION MINUTEOF(TIME : DATETIME) : INTEGER; // alias MINOF(..)
FUNCTION SECONDOF(TIME : DATETIME) : INTEGER; // alias SECOF(..)
FUNCTION MILLISECONDOF(TIME : DATETIME) : INTEGER; // alias MSECOF(..)

FUNCTION WEEKOFTHEYEAR(DATE : DATETIME) : INTEGER; // alias WOFY(..)

FUNCTION DAYOFTHEYEAR(DATE : DATETIME) : INTEGER; // alias DOFY(..)

FUNCTION HOUROFTHEYEAR(DT : DATETIME) : INTEGER; // alias HOFY(..)

FUNCTION MINUTEOFTHEYEAR(DT : DATETIME) : INTEGER; // alias MINOFY(..)
FUNCTION SECONDOFTHEYEAR(DT : DATETIME) : INTEGER; // alias SECOFY(..)
FUNCTION MILLISECONDOFTHEYEAR(DT : DATETIME) : INTEGER; // alias MSECOFY(..)

FUNCTION WEEKOFTHEMONTH(DATE : DATETIME) : INTEGER; // alias WOFM(..)

FUNCTION HOUROFTHEMONTH(DT : DATETIME) : INTEGER; // alias HOFM(..)
FUNCTION MINUTEOFTHEMONTH(DT : DATETIME) : INTEGER; // alias MINOFM(..)
FUNCTION SECONDOFTHEMONTH(DT : DATETIME) : INTEGER; // alias SECOFM(..)
FUNCTION MILLISECONDOFTHEMONTH(DT : DATETIME) : INTEGER; // alias MSECOFM(..)
 FUNCTION DAYOFTHEWEEK(DATE : DATETIME) : INTEGER; // alias DOFW(..)
FUNCTION HOUROFTHEWEEK(DT : DATETIME) : INTEGER; // alias HOFW(..)
FUNCTION MINUTEOFTHEWEEK(DT : DATETIME) : INTEGER; // alias MINOFW(..)
FUNCTION SECONDOFTHEWEEK(DT : DATETIME) : INTEGER; // alias SECOFW(..)
FUNCTION MILLISECONDOFTHEWEEK(DT : DATETIME) : INTEGER; // alias MSECOFW(..)

FUNCTION MINUTEOFTHEDAY(TIME : DATETIME) : INTEGER; // alias MINOFD(..)

FUNCTION SECONDOFTHEDAY(TIME : DATETIME) : INTEGER; // alias SECOFD(..)
FUNCTION MILLISECONDOFTHEDAY(TIME : DATETIME) : INTEGER; // alias MSECOFD(..)

FUNCTION SECONDOFTHEHOUR(TIME : DATETIME) : INTEGER; // alias SECOFH(..)

FUNCTION MILLISECONDOFTHEHOUR(TIME : DATETIME) : INTEGER; // alias MSECOFH(..)

FUNCTION MILLISECONDOFTHEMINUTE(TIME : DATETIME) : INTEGER;// alias MSECOFMIN(..)

// With the following functions the difference between 2 DATETIME's

// is calculated in the given unit.
FUNCTION YEARSBETWEEN(DATE1, DATE2 : DATETIME) : INTEGER; // alias YBTW(..)
FUNCTION MONTHSBETWEEN(DATE1, DATE2 : DATETIME) : INTEGER; // alias MBTW(..)
FUNCTION WEEKSBETWEEN(DATE1, DATE2 : DATETIME) : INTEGER; // alias WBTW(..)
FUNCTION DAYSBETWEEN(DATE1, DATE2 : DATETIME) : INTEGER; // alias DBTW(..)

FUNCTION HOURSBETWEEN(DT1, DT2 : DATETIME) : INTEGER; // alias HBTW(..)

FUNCTION MINUTSBETWEEN(DT1, DT2 : DATETIME) : INTEGER; // alias MINBTW(..)
FUNCTION SECONDSBETWEEN(DT1, DT2 : DATETIME) : INTEGER; // alias SECBTW(..)
FUNCTION MILLISECONDSBETWEEN(DT1, DT2 : DATETIME) : INTEGER;// alias MSECBTW(..)

5.4 Convert functions

// Tries to convert S to a FLOAT, returns 0 if it fails
FUNCTION VAL(S : STRING) : FLOAT;

// Converts DATE to a string with format 'yyyymmdd'

FUNCTION DTOS(DATE : DATETIME) : STRING;
// Does the invert to DTOS, returns 0 if it fails
FUNCTION CTOD(S : STRING) : DATETIME;

5.5 Misc functions

FUNCTION EMPTY(V) : BOOLEAN; // Tests if a variable is empty

// Returns the MIN or the MAX of a list of variables.

// Takes a variable number of parameters, 2 are required
FUNCTION MIN(V1;V2...VN) : VARIANT;
FUNCTION MAX(V1;V2...VN) : VARIANT;

// Returns the SUM of a list of variables.

// Takes a variable number of parameters, 2 are required
FUNCTION SUM(V1;V2...VN) : VARIANT;

// THE IIF function returns VTRUE if B is TRUE and VFALSE if B is FALSE

FUNCTION IIF(B : BOOLEAN; VTRUE; VFALSE):VARIANT;

// THE CASEF function returns the paramater corresponding to the value of I

FUNCTION CASEF(I : INTEGER;
V0; // I=0
V1; // I=1
....
VN // I=N-1
):VARIANT;