Numeric (Real) Functions

Synopsis

ABS ( number1 )

-> number

Description

Returns the absolute value of a real.

Side Effects

None.

Example

ABS ( -3.2 ) -> 3.2

Errors

None.

Synopsis

ASIN ( number1 )

-> number

ACOS ( number1 )

-> number

ATAN ( number1 )

-> number

ATANT ( number1, number2 )

-> number

Description

Return the arc-cosine, arc-sine or arc-tangent of a number, in degrees.

ATANT returns the arc-tangent of number1/number2 with the appropriate sign. ATANT is useful where the second value is near or equal to zero.

For example, (6 0 ATANT) will give the correct result of 90 degrees, but (6 0 D ATAN) will indicate an error when trying to divide by zero.

Side Effects

None.

Example

ACOS ( 0.8660254 ) -> 30degrees

Errors

Argument of ACOS or ASIN out of range [-1.0,+1.0]

ATANT (0.0,0.0) is undefined.

Synopsis

ALOG ( number1 )

-> number

Description

Return the exponential function (natural anti-log) of a number.

Side Effects

Numeric underflow causes the result to be set to zero.

Example

ALOG( -0.7 ) -> 0.4965853

Errors

Floating point overflow.

Synopsis

ARRAY(pos or dir or ori)

-> number

Description

Converts a position, direction or orientation value or attribute into three numbers.

Side Effects

None

Example

ARRAY(e100 ) -> 100 0 0

Errors

None.

Synopsis

ARRAYSize ( variable-name )

-> number

Description

Give the size of an array variable.

Side Effects

If the array variable does not exist, the result is undefined.

Example

ARRAYSIZE(!array) -> 2.0

Errors

The variable is a scalar variable and not an array variable.

The variable is an array variable element and not an array variable.

Synopsis

ARRAYWIDTH ( variable-name )

-> number

Description

Give the largest display with of any string in array variable_name.

Side Effects

None.

Example

If an array contains the following values:

!ARRAY[1] ’Bread’

!ARRAY[2] ’is’

!ARRAY[3] ’for’

!ARRAY[4] ’life,’

!ARRAY[5] ’not’

!ARRAY[6] ’just’

!ARRAY[7] ’for’

!ARRAY[8] ’breakfast’

Then

ARRAYWIDTH(!ARRAY -> 9

defines the length of ’breakfast’.

Errors

The variable is a scalar variable and not an array variable.

The variable is an array variable element and not an array variable.

Synopsis

COMPonent dir1 OF pos2

-> text

Description

Returns the magnitude of a vector drawn from E0 N0 U0 to pos2, projected in the direction dir1.

Side Effects

None.

Example

COMP E 45 N of N 0 E 100 U 50 -> 70.710

Errors

None.

Synopsis

DISTConvert ( number )

-> number

Description

Returns a distance value cast from the input number.

The input value is converted to its database units (if it is a physical quantity) and then cast to database units of distance (that is, mm) and presented in current units of distance.

Side Effects

None.

Example

When current distance units are mm

distc(1000)

distc(10metre)

distc( 5pascal)

distc (5atm)

-> 1000mm

-> 10000mm

-> 5mm

-> 506625mm

When current distance units are inch

distc(1000)

distc(10metre)

distc( 5pascal)

distc (5atm)

-> 39.4in

-> 393.7in

-> 0.2in

-> 19945.9in

Errors

None.

Synopsis

SINe ( number1 )

-> number

COSine ( number1 )

-> number

TANgent ( number1 )

-> number

Description

Return the sine, cosine or tangent value of a number (considered to be in degrees).

Side Effects

None.

Example

COS ( 0.0 ) returns 1.0

TAN ( 45.0 degrees ) returns 1.0

TAN (0.785 radians) ) returns 0.9992

Errors

Division by zero for TAN if the sine is (nearly) equal to zero.

Synopsis

INT ( number1 )

-> number

Description

Return the truncated integer value of a number.

Side Effects

None.

Example

INT ( 1.6 ) -> 1.0

INT ( -23.7 ) -> -23.0

Errors

Integer overflow.

Synopsis

LENgth ( text1 )

-> number

Description

Return the length of text1.

Side Effects

None.

Example

LENGTH ( ’abcdef’ ) -> 6.0

LENGTH ( ’’ ) -> 0.0

Errors

None.

Synopsis

LOG ( number1 )

-> number

Description

Return the natural logarithm of a number.

Side Effects

None.

Example

LOG( 3 ) -> 1 0986123

Errors

Negative arguments.

Synopsis

MATch ( text1 , text2)

-> number

Description

Return the position of the beginning of the leftmost occurrence of text2 in text1. If text2 does not occur in text1, 0 is returned.

Side Effects

None.

Example

MATCH ( ’abcdef’ , ’cd’ ) -> 3.0

MATCH ( ’abcdef’ , ’x’ ) -> 0.0

MATCH ( ’abcdef’ , ’’ ) -> 1.0

Errors

None.

Synopsis

MAX ( number1 , number2 [ , number3 [ ... ] ] )

-> number

MIN ( number1 , number2 [ , number3 [ ... ] ] )

-> number

Description

Return the maximum or minimum value of the arguments.

Side Effects

Values being evaluated are assumed to of a common physical quantity.

If no unit qualifiers are supplied they are simply numbers.

If a physical quantity is defined the result will be in current units of that quantity.

If unqualified numbers are mixed with unit values they are assumed to be in the current units of that physical quantity.

If quantities are in mixed units they are all compared in comparison to a standard unit.

If quantities are of different types of physical quantities a warning is issued and the numeric result compares the values in their database units.

Min and Max return a value with the same dimension as that of their arguments.

Example

MAX ( 1 , 3.4 ) -> 3.4

MIN ( 7.6 , -12.33 , 2.3 ) -> -12.33

MIN (7.6ft, 12.33inch, 1000mm ) -> 12.3 in (current distance units are inch)

MAX (7.6ft, 12.33inch, 1000 ) -> 1000in (current distance units are inch)

MAX (7.6ft, 12.33inch, 1kg ) -> 2316.5 (database mm equivalent of 7.6ft)

Errors

None.

Synopsis

NEGate ( number1 )

-> number

Description

Multiply a real by -1.0.

Side Effects

None.

Example

NEG ( 1 ) -> -1.0

Errors

None.

Synopsis

NINT ( number1 )

-> number

Description

Return the nearest integer to a real. NINT(N+0.5) is equal to N+1 if N is positive or equal to zero, to N if N is negative.

Side Effects

None.

Example

NINT ( 1.1 ) -> 1.0

NINT ( -23.7 ) -> -24.0

NINT ( 1.5 ) -> 2.0

NINT ( -11.5 ) -> -12.0

Errors

Integer overflow.

Synopsis

OCCUR(text1, text2)

-> integer

Description

Counts the number of times string text2 occurs in string text1

Side Effects

None.

Example

OCCUR (’ABBACCBBBBBAB’, ’BB’) -> 3

OCCUR(’ZZZZZZZZZZZ’, ’A’) -> 0

Errors

None.

Synopsis

REAL ( text1 )

-> number

Description

Try to read a real number at the beginning of text1.

Note that if text is in the form of an exponent, (-12E-1 in the third example), there must be no spaces in it.

Note: this function was formerly called NUMBER.

Side Effects

Numeric underflow causes the result to be set to zero.

If the text string contains units they are ignored and the value only is returned.

If the test string contains text that is NOT a valid unit it will generate an error.

If the text string is space separated from the number it is completely ignored.

Example

REAL ( ’12.34’) -> 12.34

REAL ( ’ 7.23 E 3 meters’ ) -> 7.23

REAL ( ’ -12E-1 meters ’ ) -> -1.2

REAL (' 1200 fred ' ) -> 1200

REAL (' 1200fred ' ) -> returns an error

This will return the value of the number in the string IGNORING any unit qualifier. The unit qualifier must still be a valid unit qualifier. This is done so that output from $! And VAR ! commands can still be accepted by the REAL function.

Note: The extension of these functions are NOT supported in DARS as they require PML functionality.

Errors

Unable to convert the text into a real number.

Synopsis

POWer ( number1 , number2 )

-> real

Description

Return the value of number1 raised to the power number2.

Side Effects

If the value being raised to a power is that of a physical quantity the result is also of a physical quantity.(in relevant current units).

If the resultant quantity is non physical (for example, by raising to a fractional power, or an extreme power, a warning is given and only the value of quantity is raised to the power.

If the power is a physical quantity this also gives a warning.

Example

POWER ( -2 , 3 ) -> -8

POWER ( -2inch , 2 ) -> 4in2

POWER ( 2inch, 3.5 ) -> returns 11.314 with an error (that is, 2**3.5)

Errors

Floating point overflow.

Zero first argument and non-positive second argument (effectively divide by zero).

Negative first argument and non-integer second argument.

Synopsis

SQrt ( number1 )

-> number

Description

Return the square root of a real.

Side Effects

Units are consolidated across SQRT. The resultant value will be in current units of that quantity.

If the resultant quantity has no recognized physical dimension a warning is given and the value return will be a number relating to the input value in database units.

Example

SQRT ( 4 ) -> 2.0

SQRT ( 4inch2 ) -> 2.0inch

sqrt ( 4inch3 ) -> a warning and 256.02 which is sqrt (4*25.4mm)

Errors

Negative argument.

Synopsis

VVALue( variable_name )

-> number

VVALue( variable_name , number )

-> number

Description

With one argument, returns value of the scalar variable or value of the array variable element as a number.

With two arguments, returns value of the element corresponding to the index number as a number.

The value of the variable will be returned, irrespective of its units.

This will return the value of the number in the string IGNORING any unit qualifier. The unit qualifier must still be a valid unit qualifier. This is done so that output from $! And VAR ! commands can still be accepted by the VVAL function.

Note: The extension of these functions are NOT supported in DARS as they require PML functionality.

Side Effects

If the scalar variable, the array variable or the array variable element does not exist, the result is undefined.

Example

VVAL ( !array[1] ) -> 1.0

VVAL ( !array , 2 ) -> 0.0

Errors

Scalar variable may not be indexed. For example, VTEXT (!var[1]) ) will return an error.

Array variable must have an index. For example, VTEXT ( !array ) ) will return an error.

The string can not be converted to a number.