Xelagot action script

String variables and operations

This page contains operations and conditional statements involving strings and string variables.

See also Program paths and path\file operations and, for xelagot 3.6 or higher, SQL string statements.

$a = $b
$a = "a sting literal"
$a = #<number from 0 to 255>
$a = %b
$a = @b
$a = &b
$a = ~b simple assignement of the value of $b to $a. Variable $b can also be substituted by a string literal, in the form of "this is my text". See Variables for a fuller explanation. It is also valid to assign an integer numeric variable %b to a string variable $a, or the string representation for location in location variable @b, a person variable &b or an object variable ~b. To assigng a one-byte character, for example ASCII 183, this notation may be used: $a = #183

Concat $a list of elements
concatenates the elements in a space separated list and assigns the resulting string to $a. For this purpose, the list may contain the following elements:

string literals: " and then "
string variables: $c
one-byte character, #<number between 0 and 255>: #13
location, person and object variables (treated as location): @p, &p and ~p
numeric variables (integer value): %b
For example:

GetPosition @p GetWorld $w Concat $a "I am at " @p " on " $w Say $a

would have the bot saying something like:
I am at 31.043n 50.980w 10.00a 90.0° on Mars

Concat $b "This is a line break" #13 #10 Concat $b $b "so this starts at a new line"

To concatenate a float (real), you must first change it to string, then you can concatenate the string. For example %r:

StringFromReal $a %r Concat $b "This is a float: " $a StringFromReal $a %r 2 Concat $b "This is a float with 2 decimals: " $a

Length %a $b stores in the numeric variable %a the length of string $b.

Pos %u $b $c [%i] stores in the numeric variable %u the position of substring $b in string $c (case insensitive). The optional parameter %i indicates the position in string $c where the search starts, defaults to 1. If search fails, then %u is 0. Example:
Pos %u "hel" "say Hello, help!"
will put %u equal to 5, and
Pos %u "hel" "say Hello, help!" 6
will make %u equal to 12

PosExact %u $b $c [%i] stores in the numeric variable %u the position of substring $b in string $c (case sensitive). The optional parameter %i indicates the position in string $c where the search starts, defaults to 1. If search fails, then %u is 0.

Trim $a $b removes leading and trailing spaces from $b and stores it in $a.

TrimLeft $a $b removes leading spaces from $b and stores it in $a.

TrimRight $a $b removes trailing spaces from $b and stores it in $a.

Uppercase $a $b stores in $a string $b in uppercase.

Lowercase $a $b stores in $a string $b in lowercase.

ReverseString $a $b stores in $a string $b back to front

Copy $a $b %i [%d] stores in $a a sub-string of $b starting at position %i with a length of %d bytes (or less if %d is too long). If %d is not specified, copies till the end of string $b.

Replace $a $b $c $d stores in $a string $b modified: replaces sub-string $c in $b with sub-string $d ($d can also be an empty string).

Split $a1 $a2 $a $d
SplitExact $a1 $a2 $a $d
splits string $a into two strings at first occurrence of sub-string $d. If $d is not found in $a, $a1 will contain $a unmodified and $a2 will be empty. Otherwise, $a1 and $a2 will contain the parts before and after $d (they may also be empty). (version 2.99986 upwards) SplitExact is case sensitive, Split is not. (up to version 2.99985) Split was case sensitive, SplitExact did not exist.

SplitFromEnd $a1 $a2 $a $d
SplitExactFromEnd $a1 $a2 $a $d
splits string $a into two strings at last occurrence of sub-string $d. If $d is not found in $a, $a1 will contain $a unmodified and $a2 will be empty. Otherwise, $a1 and $a2 will contain the parts before and after $d (they may also be empty). (version 2.99986 upwards) SplitExactFromEnd is case sensitive, SplitFromEnd is not. (up to version 2.99985) SplitFromEnd was case sensitive, SplitExactFromEnd did not exist.

SplitAtChars $a1 $c1 $a2 $a $c splits string $a into 3 strings at first occurrence of one of the characters in sub-string $c. If none is found in $a, $a1 will contain $a unmodified, $c1 and $a2 will be empty. Otherwise, $c1 will contain the character found, $a1 and $a2 will contain the parts before and after $c (they may also be empty).

SplitAtNumber $a1 $n $a2 $a splits string $a into 3 strings at first occurrence of any number. If no number is found in $a, $a1 will contain $a unmodified, $n and $a2 will be empty. Otherwise, $n will contain the number found in string format (use %n = $n to convert to numeric), $a1 and $a2 will contain the parts before and after $n (they may also be empty).

EscapeSTR $r $a $c $e xelagot 3.600
searches in $a for characters specified in string $c, and prepends to them the escape character specified in $e. If the length of $e is zero, changes nothing, if it is bigger than one character, it uses the first character as escape character. the result is assigned to $r. For example:

$a = "my dog's tail" EscapeSTR $r $a "'" "\"
will have in $r

my dog\'s tail
and
$a = "\my dog's tail\" EscapeSTR $r $a "'\" "\"
will have in $r

\\my dog\'s tail\\

DBEncode $r $a xelagot 3.600
encodes string $a and assigns the result to $r. The characters encoded are:
% to %1
, to %2
= to %3
This makes a string suitable to be included in string lists used as databases.

Do not use this statement when working with the new DB string list statements, they apply DBEncode and DBDecode automatically! See here for the new DB statements.

DBDecode $r $a xelagot 3.600
decodes string $a and assigns the result to $r. The characters decoded are:
%1 to %
%2 to ,
%3 to =
To be used on strings encoded with DBEncode.

Do not use this statement when working with the new DB string list statements, they apply DBEncode and DBDecode automatically! See here for the new DB statements.

URLencode $a $b xelagot 2.9999957
encodes into $a string $b applying a format used in urls: spaces are coded as '+'; numbers, letters ('A'-'Z' and 'a'-'z'), and the underscore are left as is; the rest is encoded to '%' followed by two bytes representing the hexadecimal code of the symbol.

URLdecode $a $b xelagot 2.9999957
decodes into $a string $b applying a format used in urls: '+' is decoded as a space; the '%' followed by two bytes representing the hexadecimal code of the symbol is decoded as that symbol (or the '%' and the following two bytes are ignored if they are out of range or invalid), the rest is left as is.

HTMLencode $a $b xelagot 2.9999975
encodes into $a string $b applying a format used in html strings. Only a few characters are encoded: the double quotes to '"', '&' to '&', '<' to '<', '>' to '>' and the non breaking space (0xa0) to ' '.

StringFromReal $a %b [%d] extracts the floating point value in %b and assigns it in string format to $a. You may also indicate the number of decimals with an optional %d.

StringFromInt $a %b extracts the integer value in %b (rounding off to the nearest integer) and assigns it in string format to $a.

GetUnusedChar $c concatenation xelagot 3.606

Stores in $c a character (1 byte) not used the concatenatable part.
It combines Concat $n ... with GetUnusedChar $c $n. I introduced this statement to allow making trivia files by script, thus being able to automatically determine the Separator needed for that format. Example:
GetUnusedChar $Sep $Category $Answer1 $Answer2 $Question
sets in $Sep a usable separator character for a trivia line.

GetFirstSDF $r $t xelagot 3.606

If $t contains a valid comma separated string in SDF format, GetFirstSDF extracts to $r the first field (substring), leaving the rest in $t. The SDF system joins fields into a comma separated string. If a comma or space are found in the field, the field is surrounded by double-quotes. If a double quote is found in a field, another double-quote is added to it. Each field is then inserted into a string, separated from the previous field by a comma.
Xelagot has a few new functions that use this SDF system. GetFirstSDF allows you to decode and extract the substrings. Example of functions that use SDF for this are: MemGetKeysSDF, MemGetSectionsSDF, SListGetNamesSDF, DBGetNamesSDF.

The statements involving location, person or object have corresponding numeric, location, person and object equivalents. See Numeric operations, Location operations and Person operations and Object operations.

GetTeleport $a assigns to $a a string containing the coordinates of the bot (no world) in AW format, ready for use in warp and teleport actions in AW objects.

GetTeleport $a %n assigns to $a a string containing the coordinates of bot number %n (no world) in AW format, ready for use in warp and teleport actions in AW objects. %n starts at 1, numbers out of range default to the bot running the script.

GetTeleport $a @b
GetTeleport $a &b
GetTeleport $a ~b assigns to $a a string containing the coordinates stored in location variable @b, in person variable &b or in object variable ~b (no world) in AW format, ready for use in warp and teleport actions in AW objects.

GetLocation $a assigns to $a a string containing the coordinates, rotations and the world of the bot.

GetLocation $a %n assigns to $a a string containing the coordinates, rotations and the world of bot number %n. %n starts at 1, numbers out of range default to the bot running the script.

GetLocation $a @b
GetLocation $a &b
GetLocation $a ~b assigns to $a a string containing the coordinates, rotations and the world stored in location variable @b, in person variable &b or in object variable ~b.

GetPosition $a assigns to $a a string containing the coordinates and rotations of the bot.

GetPosition $a %n assigns to $a a string containing the coordinates and rotations of bot number %n. %n starts at 1, numbers out of range default to the bot running the script.

GetPosition $a @b
GetPosition $a &b
GetPosition $a ~b assigns to $a a string containing the coordinates and rotations stored in location variable @b, in person variable &b or in object variable ~b.

3.3 statement
GetCoords $a assigns to $a a string containing the coordinates (not the rotations) of the bot.

3.3 statement
GetCoords $a %n assigns to $a a string containing the coordinates (not the rotations) of bot number %n. %n starts at 1, numbers out of range default to the bot running the script.

3.3 statements
GetCoords $a @b
GetPosition $a &b
GetPosition $a ~b assigns to $a a string containing the coordinates (not the rotations) stored in location variable @b, in person variable &b or in object variable ~b.

GetWorld $a assigns to $a a string containing the world the bot is in.

GetWorld $a %n assigns to $a a string containing the world bot number %n is in. %n starts at 1, numbers out of range default to the bot running the script.

GetWorld $a @b
GetWorld $a &b
GetWorld $a ~b
3.3 statement
GetWorld $a $b assigns to $a a string containing the world name stored in location variable @b, in person variable &b or in object variable ~b (in 3.3: or extracts the world name from a location string $b, which may contain or not the other location parameters, but must contain a valid world name).

GetUniverse $a assigns to $a a string containing the universe the bot is in.

GetUniverse $a %n assigns to $a a string containing the universe bot number %n is in. %n starts at 1, numbers out of range default to the bot running the script.

GetUniverse $a &b assigns to $a a string containing the universe name stored in person variable &b.

GetName $a assigns to $a a string containing the bot's name (without square brackets).

GetName $a %n assigns to $a a string containing bot number %n's name (without square brackets). %n starts at 1, numbers out of range default to the bot running the script.

GetName $a &b assigns to $a a string containing the name stored in person variable &b.

GetID $a assigns to $a a string containing the bot's ID.

GetID $a %n assigns to $a a string containing the bot's ID. %n starts at 1, numbers out of range default to the bot running the script.

GetID $a &b assigns to $a a string containing the personal ID stored in person variable &b.

GetAddress $a &b assigns to $a a string containing the IP stored in person variable &b, if it has been retrieved by the bot. See event Address.

GetModel $a ~b assigns to $a a string containing the model stored in object variable ~b.

GetDescription $a ~b assigns to $a a string containing the description stored in object variable ~b.

GetAction $a ~b assigns to $a a string containing the action stored in object variable ~b.

GetObjectID $a ~b assigns to $a a string containing an ID uniquely identifying object ~b in a world. For obvious reasons, an object will only have a valid ID if it is retrieved from the world by scanning, or in the ObjectClick and ObjectSelect events, or in ObjectCreate and ObjectResult events as result of a building or modifying activity by the bot. Note that the variable sent for building or modifying is updated automatically by the program at the moment it is sent to the server - even if ObjectCreate or ObjectResult events are not installed. The validity of this ID - and of ObjectNumber, on which it depends - lasts as long as the object has not been modified or deleted in the world, and is lost to the bot if the object variable (in this case ~b) is modified in any way, i.e. if the script modifies an object variable in any way, the ID cannot be retrieved. An invalid ID gives an empty string in $a. This ID can be kept in string lists or timeout lists, so as to be able to identify an object. Useful for games involving object deletion and scores, to avoid the double-click effect caused by lag. This ID is created by the xelagot program, and consists of a combination of the Object number (an ActiveWorlds attribute) and the object coordinates.

The statements involving date and time have corresponding numeric and date-time equivalents. See Numeric operations and Date and time operations. Unless otherwise stated or implemented in the script, time values are in VRT.

GetDateTime $a
GetLocalDateTime $a
assigns to $a the current date and time as a string, according to the local settings of the computer. (VRT or Local Time).

GetDateTime $a !b assigns to $a all values stored in !b as a string, according to the local settings of the computer.

GetDate $a
GetLocalDate $a
assigns to $a the current date as a string, according to the local settings of the computer. (VRT or Local Time).

GetDate $a !b assigns to $a the date stored in !b as a string, according to the local settings of the computer.

GetTime $a
GetLocalTime $a
assigns to $a the current time as a string, according to the local settings of the computer. (VRT or Local Time).

GetTime $a !b assigns to $a the time stored in !b as a string, according to the local settings of the computer.

GetYear $a [$s]
GetLocalYear $a [$s]
assigns to $a the current year as a string. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetYear $a !b [$s] assigns to $a the year stored in !b as a string. $s is an optional string variable or literal to be appended to $a.

GetMonth $a [$s]
GetLocalMonth $a [$s]
assigns to $a the current month name, according to the language file in use. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetMonth $a !b [$s] assigns to $a the month name corresponding to the value stored in !b, according to the language file in use. $s is an optional string variable or literal to be appended to $a. (Bug fixed x1 2.9999969).

GetDay $a [$s]
GetLocalDay $a [$s]
assigns to $a the current day of the month as a string. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetDay $a !b [$s] assigns to $a the day of the month stored in !b as a string. $s is an optional string variable or literal to be appended to $a.

GetHour $a [$s]
GetLocalHour $a [$s]
assigns to $a the current hour as a string. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetHour $a !b [$s] assigns to $a the hour stored in !b as a string. $s is an optional string variable or literal to be appended to $a.

GetMinute $a [$s]
GetLocalMinute $a [$s]
assigns to $a the current minutes as a string. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetMinute $a !b [$s] assigns to $a the minutes stored in !b as a string. $s is an optional string variable or literal to be appended to $a.

GetSecond $a [$s]
GetLocalSecond $a [$s]
assigns to $a the current seconds as a string. $s is an optional string variable or literal to be appended to $a. (VRT or Local Time).

GetSecond $a !b [$s] assigns to $a the seconds stored in !b as a string. $s is an optional string variable or literal to be appended to $a.

GetDayOfWeek $a !b [$s] gets the name of day of the week of the date stored in date-time variable !b and stores it in variable $a, in the language of the Language file in use. (Bug fixed x1 2.9999969).

GetDayOfWeek $a %b [$s] gets the name of day of the week correspondig to the number in %b (or literal) and stores it in variable $a, in the language of the Language file in use. In doing so, it first reduces the number to the range 1 to 7 using ModOne. (Bug fixed x1 2.9999969)

DateTimeString $a !t makes a string containing year + month + day + hour + minute + second + milliseconds: 17 characters, example "20000105201512331". This string can be used to form unique filenames, for example, for backing up surveys.

Example, using a date-time variable:
GetDateTime !t GetSecond $s !t GetMinute $m !t ":" GetHour $h !t " hr " GetDayOfWeek $w !t Concat $a "It is " $w ", the time is " $h $m $s Say $a
Would have the bot say something like:
It is Tuesday, the time is 5 hr 32:55

ErrorCode $a %e assigns to $a the error string corresponding to error number %e.

CONDITIONAL STATEMENTS FOR STRINGS

See Conditional Statements for a general explanation.

Please note: within these statements, elements must be clearly separated by spaces. This includes the operators!

case insensitive
IfString $a operator $b statement1

case sensitive
IfStringExact $a operator $b statement1

$a and $b can be variables or string literals. An optional
Else statement2
may follow on the next line.

the operator may be one of the following:

= equal

<> not equal

> greater than

< smaller than

>=
or
=>
greater or equal

<=
or
=<
smaller or equal

IsIn
is contained in

IsNotIn
is not contained in

IsWordIn
is a word in... separators are: Space and the following characters .,;:¡!¿?

Index

case insensitive IfString $a operator $b statement1 case sensitive IfStringExact $a operator $b statement1	$a and $b can be variables or string literals. An optional Else statement2 may follow on the next line.
the *operator* may be one of the following:
=	equal
<>	not equal
>	greater than
<	smaller than
>= or =>	greater or equal
<= or =<	smaller or equal
IsIn	is contained in
IsNotIn	is not contained in
IsWordIn	is a word in... separators are: Space and the following characters .,;:¡!¿?