Operators

Operators are used to combine values to create expressions. The OScript language contains many of the standard programming operators with which you are probably familiar, and also includes several additional operators created to manipulate Livelink-specific data types. OScript includes the following types of operators:

• Assignment
• Arithmetic
• Relational and Logical
• Bitwise
• Index
• Range
• Dot
• Conditional

Also included in this chapter is a table listing Operator precedence.

Assignment

The assignment operator is used to store values in variables or other types of expressions. The assignment operator is the single equals sign (=). It assigns the value of the expression on the right of the operator to the operand on the left. For example:

		myName = "Arnold Wilson"
		theFile = File.Open( "C:\DATA.TXT" )
		area = length * width
		myObject.nameFeature = 'newNode'
		myRecArray[ 5 ] = copied Record
		$globalDBName = "OracleDocs"

Declared variables that have a type other than Dynamic can only hold values of that variable's declared type. However, a value of any type can hold an Error or Undefined.

The arithmetic ( +, -, *, /, % ) and bitwise ( &, |, and ^ ) operators can be added before the assignment operator to perform an operation and an assignment in one step. Doing so performs the operation and then assigns the result of the operation to the operand.

	
		counter += 1

In this example, 1 is added to the current value of counter and then assigned to counter. It is equivalent to the following:

	
		counter = counter + 1

Although these types of assignments are most commonly made using += and -= to increment and decrement an operand, any of the operators listed above can be used.

The += syntax can also be used to make a concatenation assignment to a String.

		myString += nextWord

In this example, the current contents of nextWord are concatenated to myString and the resulting value is stored in myString.

Arithmetic

The arithmetic operators are used to perform mathematical operations upon Integer and Real values. OScript supports the following binary arithmetic operators:

• +addition
• -subtraction
• *multiplication
• /division
• %modulus

And the following unary arithmetic operators:

• +unary plus
• -unary minus

Any of these operators, except the modulus operator, can be used on Integers and Reals; the modulus operator can only be used on Integers. The addition and subtraction operators can also be used with Strings.

The type of value resulting from an arithmetic operation depends on the data types of the values operated on. The following table summarizes the resulting value type:

* if the divisor is not zero; Error otherwise.

The result of Integer division is an Integer, where any decimal portion that might result from a division operation on equivalent Reals is truncated, not rounded.

The result of the unary operator is the same as the data type to which it is applied.

Relational and Logical

The relational and logical operators are used to create expressions containing various data types that evaluate to a Boolean value -- TRUE or FALSE.

OScript includes the following relational operators:

• >(or GT)greater than
• >= (or GE)greater than or equal to
• < (or LT)less than
• <= (or LE)less than or equal to
• == (or EQ)equivalence
• != (or NE)non-equivalence

And the following binary logical operators:

• &&(or AND)logical AND
• ||(or OR)logical OR
• ^^(or XOR)logical exclusive OR

And the following unary logical operator:

!(or NOT)negation

Any of these operators can be used to join two or more Boolean values to form an expression that evaluates to another Boolean -- TRUE or FALSE. Expressions containing these operators are evaluated from left to right, and evaluation stops as soon as the truth or falsehood of the expression can be determined. For example:

		myValue <= maxValue
		enteredValue != ""
		Length( theList ) >= 1
		( theValue > 100 ) || ( theIdentifier == "new" )
		userType == "admin" ) && ( fileName != "" ) && ( space >= 10000 )

In the above example, the expressions ( fileName != "" ) and ( space >= 10000 ) are not evaluated if ( userType == "admin") evaluates to FALSE.

Bitwise

The bitwise operators are used to perform bit manipulation on Integers, resulting in an Integer value.

OScript includes the following bitwise operators:

• &bitwise AND
• |bitwise OR
• ^bitwise exclusive OR
• <<shift left
• >>shift right
• ~one's complement

The bitwise operators &, |, and ^ should not be confused with their logical counterparts &&, ||, and ^^.

The << and >> operators perform left or right shifts on the value to the left of the operator by the number of bit positions specified by the value to the right of the operator.

		Integer x = 1
		x = x << 2

In this example, the result 4 is stored in x.

The ~ operator performs a bitwise complement on the specified value by converting each 1-bit to a 0-bit, and vice versa.

Index Operator

The index operator ( [ ] ) can be used with Strings, Lists, RecArrays, and Records to access a particular data item within the specified value. The index operator must be used with an Integer specifying a valid data item index. A valid data item index is defined as a positive or negative Integer less than or equal to the number of items in the value, where positive values instruct the compiler to index from left to right, and negative values instruct the compiler to index from right to left. Indexes in OScript are 1-based, which means that the first element is [1]. Note that [0] returns Undefined.

		String myString = "the quick brown fox"
		String oneCharacter = myString[ 5 ]

In the example above, the index operator is used to obtain the fifth letter of myString (the letter q) and store it in oneCharacter.

		List nameList = { "arnold", "amy", "naomi", "otto" }
		String myName = nameList[ -3 ]

In the example above, the index operator is used to obtain the third from right name (amy) listed in the List nameList.

		RecArray myRecArray = RecArray.Create( { "fld1", 
		"fld2", "fld3" } )
		RecArray.AddRecord( myRecArray, { 11, 22, 33 } )
		Record firstRecord = myRecArray[ 1 ]
		Integer thirdField = firstRecord [ 3 ]

In the example above, firstRecord contains the entire first Record of values in myRecArray, and thirdField contains the value in the third field of firstRecord.

You can use the Index operator on the left side of the assignment operator. For example:

		List myFruit = { "Apple", "Celery", 
		"Bean", "Beet" }
		myFruit[ 2 ] = "Pear"
		Echo( myFruit )// displays { 'Apple', 'Pear', 'Bean', 'Beet' }
		myFruit[ 3 ] = "Cherry"
		Echo( myFruit )//displays { 'Apple', 'Pear', 'Cherry'}

Specifying an invalid index returns an empty value of the appropriate type.

The type of value resulting from a valid index operation depends upon the type of the indexed value and the form of the indexing expression. The following table summarizes:

Range Operator

The range operator ( : ) can be used with Strings, Lists, and Records to access a particular range of data items within the specified value. The range operator must be used with two Integers specifying a valid data item index range. A range is valid if:

• It includes only positive or negative Integers
• The absolute value of each Integer is less than or equal to the number of items in the value
• The first Integer specified is smaller than or equal to the second Integer, once translated (the compiler first translates any negative Integers to their positive counterparts, for example, in a six-item List, -4 is first translated to 2)

The defined range is inclusive -- the range [ 1:7 ] includes value 1, value 7, and all the values in between.

		String myString = 'the quick brown fox'
		String subString = myString[ 5:9 ] 

In the example above, subString contains quick -- the characters in positions five through nine of the String myString.

		List nameList = { 'arnold', 'amy', 'naomi', 'otto' }
		List femaleNames = nameList[ 2:3 ]

In the example above, femaleNames contains amy> and naomi -- the List values two and three in List nameList.

		RecArray myRecArray = RecArray.Create( {'fld1', 'fld2', 'fld3', \'fld4', 'fld5', 'fld6' } )
		RecArray.AddRecord ( myRecArray { 11, 22, 33, 44, 55, 66 } )
		Record firstRecord = myRecArray[ 1 ]
		List someFields = firstRecord[ 3:6 ]

In the example above, someFields contains the values stored in the third through sixth fields of the Record firstRecord.

Specifying an invalid range returns an empty value of the appropriate type. The type of value resulting from a valid range operation depends upon the type of the input value. The following table summarizes:

Dot

The dot operator ( . ) references a feature of a Record, Assoc, Object, or File by name. It can be used to reference a data member or property of the specified value.

The type of value resulting from a dot operation depends upon the operands.

The dot operator must be followed by a valid feature name.

		String theName = myRecord.name

In the above example, the dot operator is used to retrieve the String stored in the name field of the Record myRecord.

		Assoc ages
		ages.Joe = 35

In the above example, the dot operator is used to set the value associated with the key Joe.

		String theName = $NodeObject.getName()

In the above example, the dot operator is used to reference the getName method which is a feature of the NodeObject object.

Function ListGetFileProperties( File c )
         ListfileProps
         Dynamicval
         val = c.pName
         fileProps = { @fileProps, val }
         val = c.pSize
         fileProps = { @fileProps, val }
         return( fileProps )
end

In the above example, the dot operator is used to retrieve various properties of a File and store them in a List.

A String expression can be used to specify a field reference when placed inside parentheses. This can be useful in looping constructs.

		String a
		List fields = RecArray.FieldNames( b )
		Record myRecord = b[ 1 ]
		for a in fields
		    Echo( a, " is: ", myRecord.( a ) )
		end

Conditional

The conditional operator (? :) returns one of two different values depending on the value of a condition. This operator performs a function similar to an if-else statement, but is much more compact. Conditional operators use the following syntax:

		conditional_expression ? expression1 : expression2

In the following example, expression1 resolves when y is True, and expression2 resolves when y is False.

		string x
		boolean y = True
		string expression1 = "Red"
		string expression2 = "Blue"
		x = y ? expression1 : expression2
		echo( x )

Conditonal operators can also be used inside an expression, and can be recursive. For example:

		boolean defined = False
		boolean alsoDefined = True
		string myString = "The user name is " + \
		(defined ? "defined" : (alsoDefined ? "not known" : "undefined"))

Operator Precedence

Operator precedence describes the default hierarchy of evaluation of expressions containing multiple operators. The table below summarizes the rules of precedence and states the order of evaluation for all OScript operators. Operators on the same line have the same precedence, and the lines are listed in order of decreasing precedence.

Parentheses ( ) can be used to alter this precedence when needed. Although it is necessary to know the operators' precedence rules, in general, it is bad programming practice to rely solely on this order of evaluation when writing scripts. The careful use of parentheses can help ensure that expressions are evaluated as you intend and makes your script easier to read.