# &cat(4)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

&cat, &lef, &rig, &mid, &len, &slo, &trb - String macro operators

## SYNOPSIS

&cat str1 str2
&lef str len
&right str index
&mid str index len

&len str

&slower str
&supper str

&trboth str
&trleft str
&trright str

## DESCRIPTION

The string operators operate on character strings (% or $ variables), performing general string manipulation, returning a string result.

The operators may all be abbreviated to their three letter abbreviation (i.e. &right may be expressed as &rig). In all cases the first argument is completely evaluated before the second argument.

&cat str1 str2

Concatenate two string str1 with str2 to form a new string. i.e. str1str2

&lef str len

Return len leftmost characters from str. If str length is shorter than len then the string itself is returned. A len of zero returns the empty string. A negative len returns all but the 0-len rightmost characters from str.

&rig str index

Returns the rightmost characters of string str from index index. This function causes some confusion, consider &lef and &rig to be the string equivalents of their integer counterparts &div and &mod; &rig returns the remainder of the equivalent &lef function. Invocation with index set to zero returns str. A negative index returns the 0-index rightmost characters from str.

&mid str index len

Extracts a sub-string from string str, starting at position index of length len. A negative index extracts the string starting from 0-index from the end of str with a length of len.

&len str

Returns the integer length of the string (number of characters).

&slower str

Returns the given string with all upper case characters converted to lower case.

&supper str

Returns the given string with all lower case characters converted to upper case.

&trboth str

Returns the given string trimmed of white spaces (i.e. '`` ', '`\t`', '`\r`', '`\n`', '`\Cl`' and '`\Ck`') from both sides of the string.

&trleft str

Returns the given string trimmed of white spaces from the left side of the string only.

&trright str

Returns the given string trimmed of white spaces from the right side, or end, of the string only.

Evaluation of the strings is left to right, the leftmost argument is fully evaluated before the next argument. The operator ordering is prefix notation (see &add(4) for an example of prefix ordering).

## EXAMPLE

Concatenate two strings `abc` and `def` together:-

    set-variable %result &cat "abc" "def"

To concatenate three strings `abc`, `def` `ghi` together:

    set-variable %result &cat "abc" &cat "def" "ghi"

or, a slightly different ordering:

    set-variable %result &cat &cat "abc" "def" "ghi"

Retrieve the leftmost character of a string variable, modify the variable to contain the remainder.

    set-variable %foo "abcdef"
    set-variable %c   &lef %foo 1
    set-variable %foo &rig %foo 1

Where `%c` = "`a`"; `%foo` = "`bcdef`" following evaluation.

To retrieve the characters `cde` into variable `%result` from the string "`abcdef`" use:

    set-variable %result &mid "abcdef" 2 3

To retrieve the rightmost character from the string:

    set-variable %foo "abcdef"
    ; using negative argument
    set-variable %result &rig %foo -1
    ; using &len
    set-variable %result &rig %foo &sub &len %foo 1
    ; using &mid to do the same thing
    set-variable %result &mid %foo -1 1
    set-variable %result &mid %foo &sub &len %foo 1 1

To get an input string from the user which is free of spaces at the start and end:

    set-variable %result &trb @ml "Enter string"

## NOTES

The original MicroEMACS "&rig str n" function returns the last n characters from the string str this differs from the definition of &rig in this implementation. As most string decomposition is performed left to right, and to make &lef and &rig complement each other, the indexing of the function has been modified.

## SEE ALSO

Variable Functions, &sin(4), &sequal(4), &lget(4), &sprintf(4).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>