The following reference is for the Expression Syntax used by various GTI products. This post will provide an easy to find reference without having to remember which document it is in.
The expression syntax is used by GTViewer's Dynamic Graphics, Feature Tooltips, Custom Attribute Info Tabs, Link Definitions, and Where Am I. GTViewer and GTVx also provide set of methods to directly access the Expression Evaluator: ExpStateReset, ExpStateAddValue, ExpStateGetValue, ExpStateGetValueType, ExpStateGetInfo, ExpStateLoadElementData, ExpStateLoadTabularData, ExpValidate, and ExpEvaluate.
GTWeb also supports the Custom Attribute Tabs and Where Am I functionality.
*** NOTE: Some of the formatting of the Less Than and Greater Than signs didn't come through on this post. I will work on getting that fixed.
GTViewer Expression Syntax
Literals. 3
- Integer
Literals
- Double
Literals
- String
Literals
Arithmetic Operators
- Unary
Operators: + , -
- Binary
Operators: /, *, +, -
Grouping Operators
Comparison Operators
- Equality
Operators: =, ==, <>, !=
- Relational
Operators: <, >, <=, >=
- Special
Comparison Operators: LIKE, IN
Logical Operators
- Logical
AND
- Logical
OR
- Logical
NOT and !
Type Cast Functions
- Integer
Cast Functions: ToInt, CInt
- Double
Cast Functions: ToDouble, CDbl
- String
Cast Functions: ToString, CStr
String Functions
- Trim
Functions: LTrim, RTrim, Trim
- Case
Functions: Upper, Lower
- String
Length Function: Length
- String
Concatenation Function: Concat
- String
Extraction Function: Substr
- String
Replacement Function: Replace
- String
Padding Functions: RPad, LPad
- String
Search Function: Instr
- String
From ASCII Code Function: CHR
- Number
Formatting Function: Format
- String
Formatting Function: Pretty
Miscellaneous Functions
Constants
Variables
. 15
Special Variables. 17
Integer Literals
·
Integer
Literals are 32 bit signed Integer values (-2,147,483,648
through 2,147,483,647).
Double Literals
·
Double
Literals are 64 bit double values (4.94065645841246544E-324
through 1.79769313486231570E+308).
Example
|
0.0
|
123.456
|
3.14159
|
String Literals
·
A String Literal
must be enclosed in single quotes (' ') or double quotes (" ").
Example
|
'a'
|
"a"
|
'abc'
|
"abc"
|
Unary Operators: + , -
·
The unary + operator will make the operand
positive.
Example
|
Evaluates To
|
+1
|
1
|
+1 + 1
|
2
|
+1++1
|
2
|
·
The unary – operator will negate the operand.
Example
|
Evaluates To
|
-2
|
-2
|
1 + -2
|
-1
|
1 - -1
|
2
|
Binary Operators: /, *, +, -
·
The / operator will divide the left operand by
the right operand.
Example
|
Evaluates To
|
6 / 3
|
2.000000
|
3 / 2
|
1.500000
|
5 / 0
|
**Error**
|
·
The * operator will multiply the left operand by
the right operand.
Example
|
Evaluates To
|
6 * 3
|
18
|
3 * 0.5
|
1.500000
|
5 * 0
|
0
|
·
The + operator will add the left and right
operands.
Example
|
Evaluates To
|
6 + 3
|
9
|
3 + 0.5
|
3.500000
|
5 + 0
|
5
|
·
The – operator will subtract the right operand
from the left operand.
Example
|
Evaluates To
|
6 - 3
|
3
|
3 - 0.5
|
2.500000
|
5 - 0
|
5
|
Parentheses
·
The Parentheses operators can be used to group
parts of an expression together so that their order of execution can be
controlled. Grouped parts of an
expression are evaluated inside out.
Example
|
Evaluates To
|
(1)
|
1
|
(1 + 2) * (3 + 4)
|
21
|
(1 < 2) and (4 < 3 or
1>2 or 3>1)
|
1
|
Equality Operators: =, ==, <>, !=
·
Both the =
and == operators can be used for
equality comparisons. They will return
1 (True) if the left and right operands are equal; otherwise, they will return
0 (False).
Example
|
Evaluates To
|
2 = 1+1
|
1
|
3 = 1 + 1
|
0
|
2 == 1 + 1
|
1
|
3 == 1 + 1
|
0
|
'abc' = 'def'
|
0
|
·
Both the <>
and != operators can be used for
inequality comparisons. They will return
0 (False) if the left and right operands are equal; otherwise, they will return
1 (True).
Example
|
Evaluates To
|
2 <> 1+1
|
0
|
3 <> 1 + 1
|
1
|
2 != 1 + 1
|
0
|
3 != 1 + 1
|
1
|
'abc' <> 'def'
|
1
|
Relational Operators: <, >, <=, >=
·
The <
operator will return 1 (True) if the left operand is less than the right
operand; otherwise, it will return 0 (False).
Example
|
Evaluates To
|
123 < 456
|
1
|
456 < 123
|
0
|
123 < 123
|
0
|
'abc' < 'def'
|
1
|
·
The <=
operator will return 1 (True) if the left operand is less than or equal to the
right operand; otherwise, it will return 0 (False).
Example
|
Evaluates To
|
123 <= 456
|
1
|
123 <= 123
|
1
|
·
The >
operator will return 1 (True) if the left operand is greater than the right
operand; otherwise, it will return 0 (False).
Example
|
Evaluates To
|
123 > 456
|
0
|
456 > 123
|
1
|
123 > 123
|
0
|
'abc' > 'def'
|
0
|
·
The >=
operator will return 1 (True) if the left operand is greater than or equal to
the right operand; otherwise, it will return 0 (False).
Example
|
Evaluates To
|
456 >= 123
|
1
|
123 >= 123
|
1
|
Special Comparison Operators: LIKE, IN
·
The LIKE
operator will compare the left String operand to a pattern defined in the right
String operand. The following patterns
are allowed where 'xxx' is a string and the % is the accepted wildcard
character: Begins With ('xxx%'), Ends
With ('%xxx'), and Contains ('%xxx%).
Example
|
Evaluates To
|
'abc' like 'abc'
|
1
|
'abcdef' like 'abc%'
|
1
|
'abcdef' like '%def'
|
1
|
'abcdef' like '%cd%'
|
1
|
'abc' like '%'
|
1
|
'abc' like '%bcd'
|
0
|
'abcdef' like '%defg%'
|
0
|
'abcdef' like '%abc%'
|
1
|
'abcdef' like '%def%'
|
1
|
·
The IN
operator will compare the left operand to the parenthesis enclosed list of
expressions in the right operand. If the
left operand matches an item in the list, 1 (True) is returned; otherwise, 0
(False) is returned. The list of
expressions on the right must evaluate to a type compatible with the left operand’s
type (Numbers to Numbers, Strings to String).
Example
|
Evaluates To
|
123 IN (100,110,120,130)
|
0
|
120 IN (100,120,130,140)
|
1
|
'D' IN ('A', 'B', 'C', 'D',
'E')
|
1
|
Logical AND
·
The AND
operator will return 1 (True) if the left and right operands are both True (evaluate
to a non-zero value). If one or both of
the operands are False (evaluate to 0), then 0 (False) is returned.
Example
|
Evaluates To
|
1 and 1
|
1
|
1 and 0
|
0
|
0 and 1
|
0
|
0 and 0
|
0
|
True and True
|
1
|
True and False
|
0
|
False and True
|
0
|
False and False
|
0
|
Logical OR
·
The OR
operator will return 1 (True) if either the left or the right operand is True (evaluates
to non-zero value). If both operands
are False (evaluate to 0), then 0 (False) is returned.
Example
|
Evaluates To
|
1 or 0
|
1
|
0 or 1
|
1
|
1 or 1
|
1
|
0 or 0
|
0
|
True or False
|
1
|
False or True
|
1
|
True or True
|
1
|
False or False
|
0
|
Logical NOT and !
·
The NOT
and ! operators will return 0 (False)
if the following operand is True (evaluates to a non-zero value) and will
return 1 (True) if the operand is False (evaluates to a 0).
Example
|
Evaluates To
|
Not 1
|
0
|
Not 0
|
1
|
!1
|
0
|
!0
|
1
|
Not True
|
0
|
Not False
|
1
|
!True
|
0
|
!False
|
1
|
The Type Cast Functions are used to convert the type of an
expression to another type. For
example, Integer and Double values can be converted to Strings, and Strings
can be converted to Integer or Double values.
- Type Cast Function syntax:
- ToInt(
) as Integer
- CInt(
) as Integer
- ToDouble(
) as Double
- CDbl(
) as Double
- ToString(
) as String
- CStr(
) as String
Integer Cast Functions: ToInt, CInt
- The ToInt
and CInt functions will cast a
Double or String expression to an Integer Value. If a String cannot be converted, it
will return 0. The Decimal value
for Double values will be truncated.
Example
|
Evaluates To
|
ToInt( '123456')
|
123456
|
CInt( 1234.56 )
|
1234
|
Double Cast Functions: ToDouble, CDbl
- ToDouble
and CDbl will cast an Integer
or String expression to a Double value.
If a String cannot be converted, it will return a 0.0.
Example
|
Evaluates To
|
ToDouble( '123.456' )
|
123.456000
|
CDbl( 123 )
|
123.000000
|
String Cast Functions: ToString, CStr
·
ToString
and CStr will cast a Double or
Integer expression to a String Value.
Example
|
Evaluates To
|
ToString( 1 + 2 + 3 )
|
'6'
|
CStr( 1 + 2 + 3 )
|
'6'
|
Trim Functions: LTrim, RTrim, Trim
·
The LTrim
function returns the String value specified in the first parameter with no
leading spaces.
§ LTrim( str
as String ) as String
Example
|
Evaluates To
|
LTrim(' abc
')
|
'abc '
|
·
The RTrim
function returns the String value specified in the first parameter with no
trailing spaces.
§ RTrim( str
as String ) as String
Example
|
Evaluates To
|
RTrim(' abc
')
|
' abc'
|
·
The Trim
function the String value specified in the first parameter with no leading or
trailing spaces.
§ Trim( str as
String ) as String
Example
|
Evaluates To
|
Trim(' abc
')
|
'abc'
|
Case Functions: Upper, Lower
·
The Upper
function returns the String value specified in the first parameter in all upper
case.
§ Upper( str
as String ) as String
Example
|
Evaluates To
|
Upper('abc')
|
'ABC'
|
·
The Lower
function returns the String value specified in the first parameter in all lower
case.
§ Lower( str
as String ) as String
Example
|
Evaluates To
|
Lower('ABC')
|
'abc'
|
String Length Function: Length
·
The Length
function returns an Integer value specifying the number of characters in the String
value specified in the first parameter.
§ Length( str
as String ) as Integer
Example
|
Evaluates To
|
Length('abc')
|
3
|
Length('')
|
0
|
String Concatenation Function: Concat
·
The Concat
function returns a String value that is the concatenation all String values
specified as parameters. There must be
from 2 to 10 String values provided as parameters.
§ Concat( str1
as String, str2 as String) as String
§ Concat( str1
as String, str2 as String, …, str_N as String ) as String
Example
|
Evaluates To
|
Concat('abc', 'def')
|
'abcdef'
|
Concat('abc', 'def',
'ghi')
|
'abcdefghi'
|
Concat('abc', 'def',
'ghi', 'jkl')
|
'abcdefghijkl'
|
String Extraction Function: Substr
·
The Substr
function returns a String value containing a substring of the String value
provided in the first parameter. The second
parameter is an Integer value specifying the zero based starting position of
the substring. A third, optional Integer
parameter can be used to specify the length of the substring; if no length is
specified, the substring will go from the starting position to the end of the
string.
§ Substr( str
as String, startPos as Integer ) as String
§ SubStr( str
as String, startPos as Integer, length as Integer ) as String
Example
|
Evaluates To
|
Substr('abcdef',3)
|
'def'
|
Substr('abcdef',2,2)
|
'cd'
|
String Replacement Function: Replace
·
The Replace
function returns a new String value created by taking the String value specified
in the first parameter and replacing all of its occurrences of the String
specified in the second parameter with the String value specified in the third
parameter. The third parameter is
optional; omitting it will remove all occurrences of the second parameter from
the first.
§ Replace( str
as String, oldValue as String ) as String
§
Replace ( str as String, oldValue as String,
newValue as String) as String
Example
|
Evaluates To
|
Replace('abcdef','bcde')
|
'af'
|
Replace('abcdef','bcde','*')
|
'a*f'
|
String Padding Functions: RPad, LPad
·
The RPad
function returns a String value where the first parameter String value is padded
on the right side with the number of spaces needed to make the String contain
the number of characters specified by the second parameter. A third, optional parameter can specify the
padding String value.
§ RPad( str as
String, count as Integer ) as String
§ RPad( str as
String, count as Integer, padStr as String ) as String
Example
|
Evaluates To
|
RPad('abc',6)
|
'abc '
|
RPad('abc',6,'~')
|
'abc~~~'
|
·
The LPad
function returns a String value where the first parameter String value is
padded on the left side with the number of spaces need to make the String
contain the number of character specified by the second parameter. A third, optional parameter can specify the
padding String value.
§ LPad( str as
String, count as Integer) as String
§ LPad( str as
String, count as Integer, padStr as String) as String
Example
|
Evaluates To
|
LPad('abc',5)
|
' abc'
|
LPad('abc',5,'*')
|
'**abc'
|
String Search Function: Instr
·
The Instr
function returns the zero-based index position in the first parameter
String value of the second parameter String value. A third, optional parameter can be used to
specify a zero-based search starting position; 0 is used as the starting
position if the third parameter is not specified. If the second parameter String is not found in
the first, the function will return -1.
§ Instr( str
as String, searchStr as String ) as String
§ Instr( str
as String, searchStr as String, startPos as Integer ) as String
Example
|
Evaluates To
|
Instr('abcdefghij','fgh')
|
5
|
Instr('abcdefghij','jkl')
|
-1
|
Instr('abcdabcdabcd','d',8)
|
11
|
Instr('abcdabcdabcd','a',9)
|
-1
|
String From ASCII Code Function: CHR
- The CHR function returns a
String value containing the ASCII character for the specified integer value.
§ CHR( val as INTEGER
) as String
Example
|
Evaluates To
|
CHR(65)
|
'A'
|
CHR(97)
|
'a'
|
CHR(48)
|
'0'
|
Number Formatting Function: Format
·
The Format
function returns a String value of a Double value specified in the first
parameter. The second parameter is an
Integer value specifying the width of the string that will be created. The third, optional parameter can be used to
specify the zero-based number of the digit that will be shown to the right of
the decimal point.
§ Format( value
as Double, width as Integer ) as String
§ Format( value
as Double, width as Integer, prec as Integer ) as String
Example
|
Evaluates To
|
Format(12.452, 6,2)
|
' 12.45'
|
Format(12.456, 6,2)
|
' 12.46'
|
Format(12.456, 6,4)
|
'12.4560'
|
Format(12.456, 6)
|
' 12'
|
String Formatting Function: Pretty
- The Pretty function returns a String value that has been
formatted according to a specify rule.
This first parameter specifies a string to format. The second optional parameter is the
mode and can be 0, 1, or 2. If the
mode is not set, it will default to 0.
The modes are listed below:
·
Mode 0 – Capitalize the first letter of each
word in the string and make the rest of the characters lower case.
·
Mode 1 – Replace all Underscores (_) with
spaces.
·
Mode 2 – Combination of modes 0 and 1.
§ Pretty( value
as String ) as String
§ Pretty( value
as String, mode as Integer ) as String
Example
|
Evaluates To
|
Format('THIS_IS_A_TEST')
|
'This_Is_A_Test'
|
Format('THIS_IS_A_TEST',0)
|
'This_Is_A_Test'
|
Format('THIS_IS_A_TEST',1)
|
'THIS IS A TEST'
|
Format('THIS_IS_A_TEST',2)
|
'This Is A Test'
|
IF Function: IFFUNCT
- The IFFUNCT
function will evaluate the expression specified in the first parameter. If the expression is True (non-zero),
the second parameter expression is evaluated and returned; otherwise, the
third parameter expression is evaluated and returned. The second parameter determines the
return type.
§ IfFunct(
, , ) as
Example
|
Evaluates To
|
IfFunct( 1, 'a','b')
|
'a'
|
IfFunct( 0, 'a','b')
|
'b'
|
IfFunct( 1, 2, 3)
|
2
|
IfFunct( 0, 2, 3)
|
3
|
Constants:
TRUE, FALSE, CRLF
·
The TRUE
constant is an Integer value that will always evaluate to 1.
·
The FALSE
constant is an Integer value that will always evaluate to 0.
·
The CRLF constant is a String value that will
always evaluate to a Carriage Return-Linefeed character (\n).
Example
|
Evaluates To
|
True
|
1
|
False
|
0
|
CRLF
|
'\n'
|
Variables:
, []
o
Variables can be of the INTEGER, DOUBLE, or
STRING type.
o
Variable Name
can be any Alphabetical character followed by zero or more Alphanumeric
characters, or an Under Score (_).
o
For variable names that don’t meet the above
criteria, Complex Name can be used. They can contain any Letter, Number, or
Symbol except square brackets ( [ , ] ), single quotes ( ' ), or double quotes
( " ). The Complex Name must be
enclosed in square brackets.
Example
|
[a]
|
[Pole.Material]
|
[Pole Material]
|
There are currently two special variables that can be used
with the Dynamic Graphics’ Criteria Expression and Label Expression. These values are driven by the feature’s
geometry.
·
[GTI_GTI.Length]
will be set to the linear length of Linear and Shape features. Its value will be returned as a String type,
so it must be cast as a Double (with ToDouble) to be used as a numeric
value. The units will always be master
units.
·
[GTI_DG.Area]
will be set to a Shape features area.
Its value will be returned as a String type, so it must be cast as a
Double (with ToDouble) to be used as a numeric value. The units will always be square master units.
