Text Functions

Synopsis

AFTER ( text1 , text2 )

-> text

Description

Return the substring of text1 which is after the leftmost occurrence of text2 in text1.

If text2 does not occur in text1, the null string is returned.

Side Effects

None.

Example

AFTER ( ’abcdef’ , ’cd’ ) ->’ef’
AFTER ( ’abcdef’ , ’x’ ) -> ’’
AFTER ( ’abcdef’ , ’’ ) -> ’abcdef’

Errors

None.

Synopsis

BEFORE ( text1 , text2 )

-> text

Description

Return the substring of text1 which is before the leftmost occurrence of text2 in text1. If text2 does not occur in text1, text1 is returned.

Side Effects

None.

Example

BEFORE ( ’abcdef’ , ’cd’ ) -> ’ab’
BEFORE ( ’abcdef’ , ’x’ ) -> ’’
BEFORE ( ’abcdef’ , ’’ ) -> ‘’

Errors

None.

Synopsis

DISTance ( number1 )

DISTance( number1, logical1, logical2, logical3, number2, logical4)

-> text

-> text

Description

For the one-argument form, if the current distance units are FINCH, text is the conversion of the decimal inches value number1 into the format 'aa'bb.cc/dd'.

Otherwise, text is the STRING conversion of number1.

The six-argument form is more complex. The format is:

DIST/ANCE (distance, feet, usformat, fraction, denom_or_dp, zeros)

Where:

• distance is the numeric distance in inches that is to be formatted.

• feet is a logical flag set to true if output is to be in feet and inches and to false if output is to be in inches.

• usformat is a logical set to true if US format is to be used, or false if AVEVA E3D Design format is to be used.

• fraction is a logical set to true if the fractional component is to be output as a fraction, or false if to be output as a decimal denom_or_dp is a number representing the largest denominator if fraction is TRUE, or representing the number of decimal places if it is FALSE.

• zeros is a logical set to true if zeros are to be shown when that component of the output has no value.

AVEVA E3D Design

For both US and AVEVA E3D Design formats, the following rules are observed:

• If distance is negative, the first symbol is a minus sign.

• If feet is true and the distance is at least a foot, then the number of feet is output next, followed by a single quote ('). Only if zeros is true will the number of feet be output as 0 for distances less than a foot. Otherwise, the feet will be omitted.

• If feet have been output, the inches will be at least two characters wide. Numbers less than ten will be preceded by a space if US format is being used or a zero if AVEVA E3D Design format is used. A zero will be output if there are no whole inches.

• If no feet have been output and the distance is at least an inch, then the number of inches is displayed but without any preceding spaces. Only if zeros is true will a 0 be output for distances of less than an inch.

• If inches have been output and fraction is true, these will be followed by a decimal point (.).

• If fraction is TRUE and the number has a fractional component, then the numerator and the denominator are shown separated by a slash (/). This is then blank padded up to the width that the largest numerator and denominator would take.

• If fraction is FALSE and the number of decimal places is greater than zero, then the decimal point (.) is displayed followed by the remainder up to the appropriate number of decimal places. If the number of decimal places is 0 then the decimal point is not shown either.

If US format has been selected then the following additional rules are observed on output:

• The (') after the number of feet is followed by a dash (-).

• The decimal point separating the inches from the fraction is replaced by a space.

• The inches and fraction of inches are followed by a double quote (").

Side Effects

None.

Example

If the current distance units are FINCH:

DISTANCE ( 17.5 ) -> ’1’5.1/2’

Some examples, where the current distance units are feet and inches:

DIST(34.5,TRUE,TRUE,TRUE,100,TRUE) -> 2’-10.1/2.

DIST(34.5,FALSE,TRUE,FALSE,1,TRUE) -> 34.5"

DIST(34.5,FALSE,TRUE,TRUE,4,FALSE) -> 34 1/2"

DIST(128.5,TRUE,FALSE,TRUE,2,TRUE) -> 10’08.1/2"

The following table shows sets of options that could have been chosen and the format of the output produced for different numbers. Blanks output by the system are represented by underscores (_).

Errors

The value is too big to be converted.

Synopsis

UPCase ( text1 )

-> text

LOWCase ( text1 )

-> text

Description

Return an upper or lower case version of text1.

Side Effects

None.

Example

UPCASE ( ’False’) -> ’FALSE’

LOWCASE ( ’False’) -> ’false’

Errors

None.

Synopsis

PART(text1, number1)

-> text

PART(text1, number1
, text2)

-> text

Description

With two arguments, returns the number1 component of text1 assuming that text1 is split on any whitespace characters. If number1 is negative, counting of components starts from the right.

With three arguments, as above, but use text2 as the separator on which splitting takes place.

If you gives a part number higher than the number of components in the string, the function returns an empty string.

Side Effects

None.

Example

PART (’x-y-z’, 1, ’-’ -> ’x’
PART (’a b c d e’, 4-> ’d’
PART (’/PIPE45/B9’, -1, ’/’) -> ’B9’
PART(’aa bb cc’, 2) -> ’bb’
PART(’aa-bb-cc’,3,’-’) -> ’cc’

Errors

None.

Synopsis

REPLace (text1,text2,text3)

REPLace(text1,text2,text3,int1)

REPLace(text1,text2,text2,int1,int2)

-> text

-> text

-> text

Description

Replace search string text2 in input string text1 with replacement string text3.

If int1 is given this specifies the first occurrence of text2 at which to start replacement.

If int2 is given this specifies the number of replacements to make. int1 and/or int2 may be negative to indicate that the direction is backwards.

Side Effects

None.

Example

Three arguments:

REPLACE (’cat dog cat cat dog ’, ’cat’, ’dog’ ) -> ’dog dog dog dog dog’

All occurrences of 'cat' are replaced with 'dog'.

Four arguments: start occurrence given:

REPLACE (’cat dog cat cat cat dog’, ’cat’, ’dog’, 2) -> ’cat dog dog dog dog dog

All occurrence of 'cat' from the second occurrence onwards are replaced with 'dog':

REPLACE(’cat dog cat cat dog’ ,’cat’, dog’, -2 -> ’dog dog dog cat dog’

All occurrences starting at the second occurrence from the end of the string and moving backwards are replaced.

Note:
A negative fourth argument without a fifth argument implies backwards mode.

Five arguments: start occurrence and number of replacements given. Replace two occurrences of 'cat' starting at second occurrence:

REPLACE (’cat dog cat cat cat, ’cat’,’dog’, 2,2) -> ’cat dog dog dog cat’

Replace two occurrences in backwards direction starting at the second occurrence:

REPLACE (’cat dog cat cat cat’, ,’cat’, ’dog’, 2, -2) -> ’dog dog dog cat cat ’

Replace two occurrences in forwards direction starting at second occurrence from the end of the string:

REPLACE (’cat cat cat cat dog’, ’cat’, ’dog’,-2,2) -> ’cat cat dog dog dog’

Replace two occurrences in backwards direction starting at second occurrence from the end of the string.

REPLACE (’cat cat cat cat dog’,’cat’, ’dog’, -2, -2) -> ’cat dog dog cat dog’

The following examples all give the same result:

REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, 4, 2)

REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, 5, -2)

REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’,-6, -2)

REPLACE(’cat1 cat2 cat3 cat4 cat5 cat6 cat7 cat8 cat9 cat10’, ’cat’, ’dog’, -7, 2)

In each case, the output string is:

’cat1 cat2 cat3 dog4 dog5 cat6 cat7 cat8 cat9 cat10’

If the replacement string text3 is a null string, the required number of occurrences of the search string text2 are removed. For example:

REPLACE (’AAABBABZ’, ’B’, ’’) -> ’AAAAZ’

REPLACE (’AAABBABZ’, ’B’, ’’, -1, -1) -> ’AAABBAZ’

Errors

If the input string text1 is a null string or an unset text attribute, the input string text1 is returned unchanged. For example:

REPLACE (’’, ’A’,’B’) -> ’’

If the search string text2 is longer than the input string text1, the input string text1 is returned unchanged. For example:

REPLACE(’AA’, ’AAAAA’ , ’B’) -> ’AA’

If no occurrence of the search string text2 is found, the input string text1 is returned unchanged. For example:

REPLACE( ’AAAAAA’,’B’,’C’) -> ’AAAAAA

If required occurrence int1 is not found the input string text1 is returned unchanged. For example:

REPLACE(’AAAAAA’, ’A’, ’B’, 10 ) -> ’AAAAAA’

If the number of replacements required int2 is greater than the actual number of occurrence from the specified start occurrence, replacements are made up to the end of the string ( or beginning in backwards mode). For example:

REPLACE(’AAAAAA’, ’A’, ’B’, 2, 8) -> ’ABBBBB’

REPLACE (’AAAAAA’, ’A’, ’B’, -3, 8) -> ’BBBBAA’

Synopsis

STRing ( any scalar type )

-> text

STRing ( number , text1 )

-> text

STRing ( pos , text1 )

-> text

Description

Turns a value into a text string.

With a single argument the STRING function can be applied to the following scalar data types:

• Numeric

• Logical

• Id

• Position

• Direction

• Orientation

With only one argument, decimal places are output to give a maximum of six significant figures. Trailing zeros are always removed in this case.

With two arguments the data type may be either numeric (scalar) or position or direction. With two arguments, convert a number or position into a text string using the format described by text1, which may take any of the values between 'D0' and 'D6' (or 'd0' and 'd6'), where the number indicates the number of decimal places.

For numbers, STRING always outputs values as millimetres. If unit conversion is needed then the DIST function should be used. For positions, the current distance units are used.

Side Effects

None.

Example

STRING ( 1 ) -> ’1’

STRING ( 1 , ’D3’ ) -> ’1.000’

STRING ( 1.23456789 ) -> ’1.23457’

STRING(1.1230000) ->’1.123’

STRING ( 1.23456789 , ’D3’ ) -> ’1.235’

STRING (9*9 LT 100) -> ’TRUE’

STRING (OWN OF CE) -> ’/PIPE1’

STRING(POS) -> ’W1000 N20000 U18000’

STRING(POS, ’D4’ ) -> ’W10000.1234 N20000.1234 U18000.1234’

STRING(HDIR OF /PIPE1-1) -> ’D’

STRING(E 22.0125 N, ’D2’) -> ’E 22.01 N’

STRING (ORI OF NEXT) -> ’Y IS D AND Z IS U’

Errors

Synopsis

)SUBString ( text1 , number1 )

-> text

SUBString ( text1 , number1 , number2 )

-> text

Description

With two arguments, return the substring of text1 beginning at the position number1 to the end of text1.

With three arguments, return the substring of text1 beginning at the position number1 and of length number2.

If number1 is negative, then counting of characters starts from the RHS of the input string. If number2 is negative, then characters up to and including the start position are returned.

Side Effects

None.

Example

SUBSTRING ( ’abcdef’ , 3 ) -> ’cdef’

SUBSTRING ( ’abcdef’ ,-3 ) -> ’abcd’

SUBSTRING ( ’abcdef’ , 3 , 2 ) -> ’cd’

SUBSTRING ( ’abcdef’ , -3, 2 ) -> ’de’

SUBSTRING ( ’abcdef’ , 3 , -2 ) -> ’bc’

SUBSTRING ( ’abcdef’ , 10 ) -> ’’

SUBSTRING ( ’abcdef’ , -10 , 2 ) -> ’ab’

Errors

None.

Synopsis

TRIM ( text1 )

-> text

TRIM ( text1, text2 )

-> text

TRIM ( text1, text2, text3 )

-> text

Description

When only one argument is supplied, TRIM removes all spaces to the left (leading) and right (trailing) of text1 and returns the answer in text.

When two arguments are supplied, text2 specifies where the spaces should be removed from: either 'L' or 'l' for left, 'R' or 'r' for right, and 'M' or 'm' for multiple (where multiple occurrences of blanks are squeezed to a single spaces) or any combination of the three key letters. So the default is 'LR' when this field is omitted.

When the third argument text3 is also supplied, this should only be a single character which overrides the space character as the character being trimmed.

Side Effects

None.

Example

TRIM ( ’ How now, brown cow ’, ’LRM’ ) -> ’How now, brown cow’

TRIM ( ’10.3000’, ’R’, ’0’ ) -> ’10.3’

Errors

None.

Synopsis

VTEXT ( variable-name )

-> text

VTEXT ( variable-name , number )

-> text

Description

With one argument, it gets the value of the scalar variable or the value of the array variable element.

With two arguments, it gets the value of the element corresponding to the index number.

The value is returned as a text string.

See also VLOGICAL used for late evaluation when a logical result is required, and VVALUE used for late evaluation when a numeric result is required.

Side Effects

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

Example

VTEXT ( !var ) -> ’hello’

VTEXT ( !array[1] ) -> ’1.00’

VTEXT ( !array , 2 ) -> ’0.00’

Errors

Errors Scalar variable may not be indexed (for example, VTEXT (!var[1])).

Array variable must have an index (for example, VTEXT ( !array )).