NCL expressions overview

Expressions are anything that results in a value. Variable references are expressions as well as functions and literal values. Multiple expressions can occur on a single line joined together by operators and the are group by terms and operator precedence.

Algebraic

Algebraic expressions operate on arrays of basic numeric types. There are nine main algebraic operators: multiply, divide, exponent, plus, minus, modulus, less-than selection, greater-than selection, and negative. All of the operators except negative take two operands. Also, in general, both operands should be the same type. If they are not, NCL attempts to coerce them to identical types. If this fails, a type mismatch error is generated. Additionally, either the operands must have the same number of dimensions and dimension sizes, or one operand can be a scalar value. The operators operate on the entire array of data.

The following is a list of the operator characters. The operators are listed in order of precedence: the first one has the highest precedence. The precedence rules can be circumvented by using parentheses '(' ')' around expression that should be computed first.

		-	Negative
		^	Exponent
		*	Multiply
		/	Divide
		%	Modulus
		+	Plus
		-	Minus
		<	Less-than selection
		>	Greater-than selection

Negative -

The negative operator negates the value of its operand. The operand can be any numeric type. If it is an array, each element of the array is negated.

Exponent ^

The left operand is "raised" to the power of the right operand. If the left operand is negative, then the right side must be positive. Currently, NCL doesn't support imaginary numbers; it generates an error in this situation. The result type of this operator is always a floating point number unless double precision values are used.

Multiply *

Multiplies left operand by right operand. No special conditions or restrictions.

Divide /

Divides left operand by right operand. When both operands are integral types, the result is an integer type. Therefore, the decimal remainder is truncated.

Modulus %

The result is the integral remainder of integral division. Both operands must be integral types.

Plus +

Adds left operand to right operand. No special conditions or restrictions.

Minus -

Subtracts right operand from left operand. No special conditions or restrictions.

Less-than selection <

For arrays, the less-than selection operator selects all values in the left operand that are less than the corresponding value in the right operand. If the value of the left side is greater than or equal to the corresponding value of the right side, then the right side value is placed in the result. For a scalar and an array, the same selection rules apply, but the scalar is compared against each value in the array operand.

Greater-than selection >

For arrays, the greater-than selection operator selects all values in the left operand that are greater than the corresponding value in the right operand. If the value of the left side is greater than or equal to the corresponding value of the right side, then the right side value is placed in the result. For a scalar and an array, the same selection rules apply, but the scalar is compared against each value in the array operand.

Logical

Logical expressions are formed by relational operators. There are ten relational operators: less-than-or-equal, greater-than-or-equal, less-than, greater-than, equal, not-equal, and, or, exclusive-or, not. All of these operators yield logical type results. And, or, exclusive-or, and not require logical operands, and the rest accept any type.

All of the logical expressions function similarly with respect to comparisons between arrays and arrays, arrays and scalars, and scalars and scalars. For array operands, each corresponding element is compared and the result is an array of logical values the size of the operands. A single scalar can be compared against each element in an array. The result is an array of logical values the size of the array operand. Finally, when two scalars are compared, the result is a scalar logical value.

The following is a list of the logical operators and their precedence.

		.le. 	Less-than-or-equal
		.lt.	Less-than
		.ge.	Greater-than-or-equal
		.gt.	Greater-than
		.ne.	Not-equal
		.eq.	Equal
		.and.	And
		.xor.	Exclusive-or
		.or.	Or
		.not.	Not

Less-than-or-equal .le.

Returns True if the left operand is less than or equal to the right operand.

Less-than .lt.

Returns True if the left operand is less than the right operand.

Greater-than-or-equal .ge.

Returns True if the left operand is greater than or equal to the right operand.

Greater-than .gt.

Returns True if the left operand is greater than the right operand.

Not-equal .ne.

Returns True if the left operand is not equal to the right operand.

And .and.

Requires both operands to be logical types. Returns True if and only if both operands are True.

Or .or.

Requires both operands to be logical types. Returns True if either operand is True.

Exclusive-or .xor.

Requires both operands to be logical types. Returns True if one of the operands is True and the other is False.

Not .not.

Takes a single operand which must be logical. Returns True if the operand is False; returns False if the operand is True.

Arrays

An array expression combines either scalar values or other arrays into a single array result. An array expression is made up of expressions separated by commas (',') and enclosed in slashes '(/' and '/)'. Arrays can be made up of any of the basic types as well as graphical objects. Currently, arrays of files are not supported. Each element separated by commas must have the same dimensionality as the rest of the elements in the array expression. If the types are not the same, the coercion rules are used to convert all of the array elements to the same type. If this fails, an error message is generated.

The following are examples of array expressions.

	(/ 1, 2, 3, 4, 5 /)
	(/ (/ 1, 2, 3 /)^2, (/ 4, 5, 6 /)^3,(/ 7, 8, 9 /)^4 /)
	(/ a - b, b + c, c / d /)

Functions

Functions are expressions because they return a value. Functions do not necessarily have to always return the same type or size array every time they are called. Functions are called by referencing their name and providing an argument list. Arguments can be any type, including files. They can also be literal values, variables, or subsections of variables. Functions can be defined to restrict parameters to be specific types, to have specific numbers of dimensions, and to have specific dimension sizes. If a parameter must be a certain type, then the coercion rules are applied to it. One very important thing to note is that all parameters are passed by reference in NCL, meaning a change of a value in a variable within the function changes the value of the parameter. If a parameter is coerced before the function is called, changes within the function will not be reflected in the parameter. A warning message is given in this instance. Expression results can also be passed to functions as parameters. However, since expression results are not referenced by a variable, there is no way changes made to the parameter can be passed out from the function, unless it is returned by the function.

Intrinsic functions

An identifier with a list of parameters, the parameters being separated by commas enclosed and in parentheses. Intrinsic functions return values when called. An intrinsic function is not defined by NCL source; it is a C or Fortran routine that has been added to the NCL function set. Intrinsic functions often perform operations that NCL source does not support.

---

Reference Manual Control Panel

NG4 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

---

$Revision: 1.9 $ $Date: 1995/07/26 23:31:19 $