The functions on strings represent the core of Proteus, as you can guess by the large number of functions included in this category.

Keep in mind that indexes in Proteus go from 1 to the length of the string (in C, indexes go from 0 to length - 1). The values returned by these functions are:

• 0 or empty string: general error;
• -1: incorrect handle.

To narrow your search, the functions in this category has been divided in the following sub-categories:

• substring extraction: these functions return a specified substring (usually of known length) of a given string;
• string formatting: these functions change a string by inserting, substituting or removing characters;
• logical tests: these functions return true or false by evaluating a specified property (equality, regular expression match, characteristics of the alphabet);
• string comparison: these functions compare two strings and determine their relative order;
• search position: these functions determine where in a string a specified property begins (occurrence of a word, of a class of characters, position of the first character not belonging to a specified alphabet);
• lengths and repetitions: length of a string; number of repetitions of a string within another; maximum length of a segment featuring the specified characteristics;
• dynamic tokenizers: a token is a sequence of characters in a string delimited by one or more characters belonging to a specified alphabet; these functions return tokens, their positions within a string, their number;
• static tokenizers: functions similar to those in the previous sub-category, but using handles;
• other: functions on strings not belonging to the previous sub-categories.

Remember that all logical tests on strings have the common prefix STR (STREQ, STRNEQ, ..); this is useful to distinguish these functions from those operating on numbers (EQ, NEQ, ..). A common mistake is using one for another, as in this case:

S1 = "PROTEUS"
S2 = "TEXT"
.. 
IF EQ(S1, S2)
  ; Wrong! S1 and S2 are different, but this test would be
  ; positive because both strings have 0 as numeric interpretation
  ; (being both non-numbers)
  ..
FI

Substring extraction:

STRDUP(c)

returns a copy of c, evaluated as a string

SUBSTR([@]c, nStart[, nLength])

returns a substring of c, beginning from nStart, of nLength characters (or the rest of the string, if not specified); if nLength exceeds the number of available characters, it returns the whole string from the specified point; if nStart is out of range, it returns an empty string

RESTFROM([@]c, nStart)

returns the substring of c going from nStart to the end of c; returns an empty string if nStart is out of range

LEFT([@]c, n)

returns a copy of the first n characters from the left of c; if n is negative, it returns LEFT(c, ADD(STRLEN(c), n)); if n is greater than the length of c, it returns a copy of c

RIGHT([@]c, n)

returns a copy of the last n characters of c; if n is negative, it returns RIGHT(c, ADD(STRLEN(c), n)); if n is greater than the length of c, it returns a copy of c

CHOP([@]c)

returns the last character of c; if c is passed by reference, it is shortened by one character upon return

STRTRAVERSE(c, udffunction)

calls udffunction for each character in string c (from left to right); the UDF must accept only two parameters (character, position in c) and return 0 (continue with the next character) or 1 (stop traversing string); STRTRAVERSE returns -1 if c is empty, 0 if it was fully traversed, 1 if the UDF has requested termination.

String formatting:

STRIPQUOTES([@]c)

returns a copy of c where double quotes (") at the beginning and at the end are removed

CENTER([@]c, nLength)

centers the string c in a new string, nLength characters long; it returns c if nLength is lesser than the length of c

JUSTIFY([@]c, nLength)

justifies c in nLength characters; it returns c if nLength is lesser than the length of c

PACKCHAR([@]c, cPackChar)

substitutes repetitions in c of the first character from cPackChar with a single character; it returns c if cPackChar is an empty string

DETAB([@]c, nTabInterval)

expands tabs to spaces in c; nTabInterval is the tab interval (= number of columns; if <= 0, tabs are removed)

ENTAB([@]c, nTabInterval)

substitutes spaces with tabs in c; the current alignment is kept if a tab is present every nTabInterval columns; it returns c if nTabInterval <= 1

PADL([@]c, nLength, cPadChar)

returns the string c prefixed by the first character in cPadChar, repeated a number of times so that the resulting string becomes nLength characters long; if c is longer than nLength, it is truncated to nLength characters; if nLength is negative, it returns an empty string

PADR([@]c, nLength, cPadChar)

returns the string c followed by the first character in cPadChar, repeated a number of times so that the resulting string becomes nLength characters long; if c is longer than nLength, it is truncated to nLength characters; if nLength is negative, it returns an empty string

STRCAT([@]c1, [@]c2[, c3..])

returns a new string obtained by chaining together all the strings specified; most often, this function is omitted: STRCAT(c1, c2) can also be written as c1 c2

LTRIM([@]c, cTrimChars)

returns a copy of c where all characters belonging to cTrimChars are removed from the beginning (left part) of the string

RTRIM([@]c, cTrimChars)

returns a copy of c where all characters belonging to cTrimChars are removed from the end (right part) of the string

ALLTRIM([@]c, cTrimChars)

returns a copy of c where all characters belonging to cTrimChars are removed from the beginning and the end of the string

UPPER([@]c)

returns a copy of c where all the alphabetic characters are converted to uppercase

LOWER([@]c)

returns a copy of c where all the alphabetic characters are converted to lowercase

CAPITALIZE([@]c)

returns a copy of c where the first letter of each word (if alphabetic) is converted to uppercase, while all the other characters are converted to lowercase; this procedure recognizes the character <'> as a word separator, but does not convert to uppercase the single characters following it (e.g. John's House) and keep uppercase the ordinal numbers (e.g. II, III, IV)

CTRAN([@]c)

returns a new string by interpreting all C-like constants inside c

CINVTRAN([@]c)

returns a new string calculated from c by replacing special characters with escape sequences (if necessary) and by substituting non-printable characters with hexadecimal constants

STRTRAN([@]c, cSearch, cReplace)

returns a copy of c where each occurrence of cSearch is replaced by cReplace

REXSTRTRAN([@]c, xExpSearch, cReplace)

returns a copy of c where each part matching the extended regular expression xExpSearch is replaced by cReplace

REXISTRTRAN([@]c, xExpSearch, cReplace)

returns a copy of c where each part matching the extended regular expression xExpSearch is replaced by cReplace; comparison is case-unsensitive (A = a and viceversa)

REXFSTRTRAN([@]c, xExpSearch, funcreplace)

returns a copy of c where each part matching the extended regular expression xExpSearch is substituted with the value returned by the UDF funcreplace, which takes a single parameter corresponding to the string matched by xExpSearch

REXIFSTRTRAN([@]c, xExpSearch, funcreplace)

returns a copy of c where each part matching the extended regular expression xExpSearch is substituted with the value returned by the UDF funcreplace, which takes a single parameter corresponding to the string matched by xExpSearch; comparison is case-unsensitive (A = a and viceversa)

INSERT([@]c, nStart, cInsert)

returns a copy of c where cInsert is inserted from character nStart; if nStart is greater than the length of c, cInsert is appended to c

DELETE([@]c, nStart, nLength)

returns a copy of c in which nLength characters are removed from nStart

STUFF([@]c, nStart, nLength, cInsert)

combine INSERT and DELETE: beginning from nStart, nLength characters are deleted from c and cInsert takes their place

MAPNEW(cFrom, cTo)

create a new mapping from each character in cFrom to every corresponding character in cTo; if cFrom is longer than cTo, every character without its matching counterpart is left unchanged; if cFrom is shorter than cTo, additional characters from cTo are ignored; it returns the handle of the new mapping

MAPFREE(mHandle)

frees memory allocated for the mapping corresponding to the specified handle; returns -1 if mHandle is wrong, 0 otherwise

MAP(mHandle, [@]c)

returns the string c converted according to the mapping mHandle; if mHandle is invalid, returns an empty string

Logical tests:

ISEMPTY(c)

returns a logical value that says if c is an empty string (all blanks and tabs, or no character at all)

ISNOTEMPTY(c)

returns a logical value that says if c is not empty

ISALPHA(c)

returns a logical value that says if c includes only alphabetic characters

ISDIGIT(c)

returns a logical value that says if c includes only digits (0-9)

STREQ(c1, c2)

returns a logical value that says if c1 and c2 are identical

STRIEQ(c1, c2)

returns a logical value that says if c1 and c2 are identical (case-insensitive compare)

STRNEQ(c1, c2)

returns a logical value that says if the strings c1 and c2 are different

STRINEQ(c1, c2)

returns a logical value that says if the strings c1 and c2 are different (case-insensitive compare)

MATCH(c, rExp)

returns a logical value that says if c matches rExp (simple regular expression)

IMATCH(c, rExp)

returns a logical value that says if c matches rExp (simple regular expression); the comparison is case-insensitive (A = a and viceversa)

REXMATCH(c, xExp)

returns a logical value that says if c matches xExp (extended regular expression); REXMATCH changes the values of two predefined variables: R_START and R_LENGTH; when there is a match, R_START is set to the start of the corresponding part and R_LENGTH is set to its length; if REXMATCH fails, both variables are set to 0

REXIMATCH(c, xExp)

returns a logical value that says if c matches xExp (extended regular expression); the comparison is case-insensitive (A = a and viceversa); REXIMATCH changes the values of two predefined variables: R_START and R_LENGTH; when there is a match, R_START is set to the start of the corresponding part and R_LENGTH is set to its length; if REXIMATCH fails, both variables are set to 0

IN(cFrom, cTo)

returns a logical value that says if cFrom appears inside cTo

OF(c, cAlphabet)

returns a logical value that says if c contains only characters taken from cAlphabet

String comparison:

STRCMP(c1, c2)

compares the strings; this function returns:
0 if c1 == c2
< 0 if c1 < c2
> 0 if c1 > c2

STRICMP(c1, c2)

case-insensitive comparison between the two strings; this function returns:
0 if c1 == c2
< 0 if c1 < c2
> 0 if c1 > c2

Search position:

STRPBRK(c, cAlphabet)

returns the first occurrence in c of one of the characters in cAlphabet (0 if no character from cAlphabet appears in c)

STRCPBRK(c, cAlphabet)

returns the first occurrence in c of one of the characters not in cAlphabet (0 if all the characters in c appears in cAlphabet)

STRSTR(c, cSearch)

returns the position of the first occurrence of cSearch in c

STRISTR(c, cSearch)

returns the position of the first occurrence of cSearch in c; case-insensitive comparison

STRRSTR(c, cSearch)

returns the position of the first occurrence of cSearch in c (starting from the end of c)

STRIRSTR(c, cSearch)

returns the position of the first occurrence of cSearch in c (starting from the end of c); case-insensitive comparison

POSDIFF(c1, c2)

returns the position where c1 differs from c2; this function returns 0 if the strings are identical

POSIDIFF(c1, c2)

returns the position where c1 differs from c2; this function returns 0 if the strings are identical; case-insensitive comparison

Lengths and repetitions:

STRLEN(c)

number of characters in c

COUNTSTR(c, cSearch)

number of times cSearch appears in c

COUNTISTR(c, cSearch)

number of times cSearch appears in c; case-insensitive comparison

STRSPN(c, cAlphabet)

maximum prefix in c whose characters appear in cAlphabet

STRCSPN(c, cAlphabet)

maximum prefix in c whose characters do not appear in cAlphabet

Dynamic tokenizers:

TOKEN([@]c, nToken, cSeparators)

returns the token nToken from c; cSeparators is a string containing all the allowed separators; if the specified token does not exist, returns an empty string

NUMTOKEN(c, cSeparators)

number of tokens in c, determined using cSeparators

POSTOKEN(c, nToken, cSeparators)

position in c of the token nToken, determined using cSeparators; if the specified token does not exist, returns 0

REXTOKEN([@]c, nToken, xExp)

returns the token nToken from c; xExp is the extended regular expression satisfied by the separators allowed; if the specified token does not exist, returns an empty string

REXITOKEN([@]c, nToken, xExp)

returns the token nToken from c; xExp is the extended regular expression satisfied by the separators allowed; if the specified token does not exist, returns an empty string; case-insensitive comparison

REXPOSTOKEN(c, nToken, xExp)

position in c of the token nToken, determined using the separators satisfying xExp; if the specified token does not exist, returns 0

REXIPOSTOKEN(c, nToken, xExp)

position in c of the token nToken, determined using the separators satisfying xExp; if the specified token does not exist, returns 0; case-insensitive comparison

REXNUMTOKEN(c, xExp)

number of tokens in c, determined using the separators satisfying xExp

REXINUMTOKEN(c, xExp)

number of tokens in c, determined using the separators satisfying xExp; case-insensitive comparison

Static tokenizers:

static tokenizers, as opposed to dynamic tokenizers, are faster because they create in memory a copy of all the tokens, which are later accessed without the need of recalculating them.
The functions in this category are:

TOKNEW(c, cSeparators)

calculates the tokens in c using the separators in cSeparators; this function returns a handle (integer number), which can be used to retrieve information about tokens and their positions; TOKFREE should be invoked as soon as the information is no longer useful - this is necessary to avoid memory overflow

REXTOKNEW(c, xExp)

calculates the tokens in c using the separators that satisfy xExp and returns a handle, like TOKNEW; TOKFREE should be invoked as soon as the information is no longer useful

REXITOKNEW(c, xExp)

calculates the tokens in c using the separators that satisfy xExp (case-insensitive comparison) and returns a handle, like TOKNEW; TOKFREE should be invoked as soon as the information is no longer useful

TOKNUM(kHandle)

number of tokens determined by the tokenization corresponding to kHandle; if the handle is wrong, returns -1

TOKGET(kHandle, nToken)

returns the token nToken resulting from the tokenization corresponding to kHandle; if the handle or nToken are invalid, returns an empty string

TOKPOS(kHandle, nToken)

returns the position of the token nToken from the tokenization corresponding to kHandle; if the handle or nToken are invalid, returns an empty string

TOKFREE(kHandle)

frees memory reserved by the tokenization corresponding to kHandle; returns 0 if the operation is successfull, -1 if the handle is invalid

Other:

CHR(n)

returns a string with the single character having ASCII code n

ASC(c)

returns the ASCII code of the first character in c

STRRANDOM(cAlphabet, nLength, nSeed)

returns a pseudo-random string nLength characters long; the characters are taken from cAlphabet, which is a string of any length that can include even repeated characters; the integer number nSeed is used to inizialize the random sequence; the same values of nSeed and cAlphabet produce the same random strings; to create completely random strings, use RANDOM(-1) for nSeed

CRC32(c, [@]n)

returns the 32-bit Cyclic Redundancy Test on the string, calculated according to Ansi X3.66; to calculate the CRC on a file, set n to 0xFFFFFFFF and, at the end of the file, complement the result. The example crc32.prt shows how to use this function.

REVERSE([@]c)

returns a copy of the string c read from right to left ("ABC" becomes "CBA")

REPLICATE([@]c, nTimes)

returns c replicated for nTimes; if nTimes <= 0, returns an empty string

STRXOR([@]c1, [@]c2[, c3..])

exclusive OR, character by character, between the specified strings; if c2, c3.. are shorter than c1, they are duplicated a number of times so that they cover c1; the resulting string has the length of c1

CRYPT([@]c, cKey1[, cKey2..])

encrypts the string c with the keys cKey1, cKey2..; at least one key is needed; to decrypt the string, use DECRYPT with the same keys in the same order; the keys are case-sensitive; it is possible to encrypt many times the same string, even though this does not significantly increase the security. The example encrypt.prt shows the usage of this function. Note: if an empty key is passed to CRYPT, it is used a key of a single character, corresponding to CHR(255)

DECRYPT([@]c, cKey1[, cKey2..])

decrypts the string c with the keys cKey1, cKey2..; at least one key is needed; to encrypt the string, use CRYPT with the same keys in the same order; keys are case-sensitive. The example decrypt.prt shows the usage of this function.

PFORMAT(cMask, [@]exp)

returns exp formatted according to cMask, whose syntax is the same as printf (the standard C function), without the character '%'.
It is not allowed the usage of '*' or '%' and the transformation must have sense; otherwise, an empty string is returned.
cMask has the following structure:

[flag][width][.precision][h|l|L][type] 

flag =

• blank = if the value is not negative, the resulting string begins with a blank; if it is negative, begins with '-';
• '-' = the result is left-justified, by adding blanks to the right; if it is not specified, the result is right-justified by adding 0s or blanks;
• '+' = the result always begins with '+' or '-'.

width = minimum length of the result; it can be:

• n = at least n characters (if shorter, add spaces to the left or to the right; if longer, it is left unchanged);
• 0n = like n, but if the result is shorter add '0' to the left;

.precision = maximum number of characters (or minimum number of integer digits) to be printed; it can be:

• nothing = default precision:
  • = 1 for types: d, i, o, u, x, X
  • = 6 for types: e, E, f
  • = all meaningful digits for types g and G
  • = prints up to the first NULL for type s
  • = no effect on type c
• .0 = set default precision for types d, i, o, u, x; cut decimals for types e, E, f
• .n = print n characters o n decimal digits (rounding, if needed)

[h|l|L] = modify the interpretation of the following type:

• h = integer (d i o u x X)
• l = long integer (d i o u x X)
• L = quadruple-precision floating point (e E f g G)

type = interpretation of exp:

• d|i = decimal integer with sign
• o = octal integer with sign
• u = decimal integer without sign
• x = hexadecimal integer without sign (using a, b, c, d, e, f)
• X = hexadecimal integer without sign (using A, B, C, D, E, F)
• f = floating point with sign in the form [-]dddd.dddd.
• e = floating point with sign in the form [-]d.dddd e[+/-]ddd
• g = floating point with sign in the form e or f, according to the the value and the precision. Zeros at the beginning and the decimal point are printed only when necessary (this is the default used by Proteus for displaying floating point numbers)
• E = like e, but using E in the format
• G = like g, but using F for exponent (if in format e)
• c = single character
• s = string

The length of the resulting string must be no greater than 511 characters.

MIME64([@]c, @nStatus, vB64par, nEndFlag)
DEMIME64([@]c, @nStatus, vB64par)

these two functions allow to encode/decode a string in the MIME Base 64 format; this encoding is widely used for exchanging binary files through electronic mail; the function MIME64 takes four parameters:

c	string to encode; if passed by reference, the result is stored into the variable
nStatus	integer number, to be passed by reference (it is necessary to specify the character '@' before the name of the identifier); at the end, it gets one of these values: 0 = successfull -1 = vB64par is not a handle of an array of size 3 1, 2 = if nEndFlag is 1, it is the number of remaining characters (see below)
vB64par	handle of an array of size 3, whose items should be set to 0 before the first call
nEndFlag	it must be set to 1 if c ends the data to be encoded, to 0 otherwise

The array vB64par is necessary to maintain accumulator and shift registers between successive calls to MIME64; to settle the last line (if the length of the data to be encoded is not a multiple of 3), the function adds 1 or 2 characters to the expected length of the encoded string, which is usually MUL(DIV(STRLEN(c), 3), 4); in this case, nStatus is set to the number of added characters; a Base 64 text block is usually introduced by a MIME header; the example mime64.prt shows a simple encoder using MIME64.

The function DEMIME64 takes the following parameters:

c	string to decode; if passed by reference, the result is stored into the variable
nStatus	integer number, to be passed by reference (it is necessary to specify the character '@' before the name of the identifier); at the end, it gets one of these values: 1 = data remaining 0 = end of Base 64 stream -1 = error (vB64par is not a handle, error in data)
vB64par	handle to an array of size 3, whose items should be set to 0 before the first call

The example demime64.prt shows a basic decoder for files including a single MIME Base 64 block.

UUENCODE([@]c)
UUDECODE([@]c)

these two functions allows to encode/decode a string in the format UU-encoding; this format is widely used for exchanging binary files through electronic mail; if the number of bytes on the line is not divisible by 3, one or two additional bytes (CHR(0)) are used. The length of the resulting string (if divisible by 3) is (1 + |c| / 3 * 4), where |c| is the length of c. The example uuencode.prt shows a simple encoder using UUENCODE; uudecode.prt decodes files with a single UUencoded section.

URLENCODE([@]c1[, c2..])

this function URL encodes in a single string the parameters c1, c2, ..; every parameter must be of the type "label=value"; this function can be used to pass parameters to other CGI scripts

URLDECODE(c)
ENVURLDECODE(c)

these functions allow to URL-decode a string previously encoded; URLDECODE returns a handle to an AVL tree with all the values in c, or -1 if c is empty; ENVURLDECODE returns always 0 (or -1, if c is empty) and sets the environment variables corresponding to the names of the fields in c to their values