-
Notifications
You must be signed in to change notification settings - Fork 7
Standard Library
string join(const array<string> &in arr, const string &in delimiter)
This function concatenates the strings in the array into a large string, separated by the given delimiter.
PARAMETERS
arr: const array<string> &in
delimiter: const string &in
RETURN VALUE
Return type: string
EXAMPLE
array<string> x ={"1 is digit", "2.0 is double"};
string y = ",";
string z = join(x,y);
ECHO(z);
OUTPUT
AT script: 1 is digit,2.0 is double
int64 parseInt(const string &in str, uint base = 10, uint &out byteCount = 0)
This function parses the string for a signed integer value. The base can be 10 or 16 to support decimal numbers or hexadecimal numbers. If byteCount is provided it will be set to the number of bytes that were considered as part of the integer value.
PARAMETERS
str: const string &in
base: uint default=10
byteCount: uint &out default=0
RETURN VALUE
Return type: int64
EXAMPLE #1
int numOfBytes=0;
int x = parseInt("-10",10, numOfBytes);
ECHO(x);
ECHO(numOfBytes);
OUTPUT
AT script: -10
AT script: 3 <--- number of bytes to contain -10.
EXAMPLE #2
int numOfBytes=0;
int x = parseInt("30",10, numOfBytes);
ECHO(x);
ECHO(numOfBytes);
OUTPUT
AT script: 30
AT script: 2 <--- number of bytes to contain 30.
uint64 parseUInt(const string &in str, uint base = 10, uint &out byteCount = 0)
This function parses the string for an integer value. The base can be 10 or 16 to support decimal numbers or hexadecimal numbers. If byteCount is provided it will be set to the number of bytes that were considered as part of the integer value.
PARAMETERS
str: const string &in
base: uint default=10
byteCount: uint &out default=0
RETURN VALUE
Return type: uint64
EXAMPLE
int numOfBytes=0;
int x = parseInt("10",16, numOfBytes);
ECHO(x);
ECHO(numOfBytes);
OUTPUT
AT script: 16
AT script: 2 <--- number of bytes to contain 16.
double parseFloat(const string &in str, uint &out byteCount = 0)
This function parses the string for a floating point value. If byteCount is provided it will be set to the number of bytes that were considered as part of the value.
PARAMETERS
str: const string &in
byteCount: uint &out default=0
RETURN VALUE
Return type: double
EXAMPLE
int numOfBytes=0;
float x = parseFloat("29.98",numOfBytes);
ECHO(x);
ECHO(numOfBytes);
OUTPUT
AT script: 29.980000
AT script: 5 <--- number of bytes to contain 29.98.
string formatInt(int64 val, const string &in options = '', uint width = 0)
This function converts signed integer val to string with options as 'l' for decimal or 'H' for hexadecimal. If width is provided the minimum length of the return string will be the value of width.
PARAMETERS
val: int64
options: const string &in default=''
width: uint default=0
RETURN VALUE
Return type: string
EXAMPLE
int number = 10;
// Left justify number in string with 10 characters
string justified = formatInt(number, 'l', 10);
ECHO(justified);
// Create hexadecimal representation with capital letters, right justified
string hex = formatInt(number, 'H', 10);
ECHO(hex);
number = -10;
justified = formatInt(number, 'l', 10);
ECHO(justified);
OUTPUT
AT script: 10
AT script: A
AT script: -10
string formatUInt(uint64 val, const string &in options = '', uint width = 0)
This function converts unsigned integer val to string with options as 'l' for decimal or 'H' for hexadecimal. If width is provided the minimum length of the return string will be the value of width.
PARAMETERS
val: uint64
options: const string &in default=''
width: uint default=0
RETURN VALUE
Return type: string
EXAMPLE
int number = 10;
// Left justify number in string with 10 characters
string justified = formatUInt(number, 'l', 10);
ECHO(justified);
OUTPUT
AT script: 10
string formatFloat(double val, const string &in options = '', uint width = 0, uint precision = 0)
This function converts double/float val to string with options as 'l' for decimal or 'H' for hexadecimal. If width is provided the minimum length of the return string will be the value of width. If precision is provided the minimum number of decimal points with be the value of precision.
PARAMETERS
val: double
options: const string &in default=''
width: uint default=0
precision: uint default=0
RETURN VALUE
Return type: string
EXAMPLE
int number = 10;
string num = formatFloat(number, '0', 8, 2);
ECHO(num);
OUTPUT
AT script: 00010.00
The above format functions take a string that defines how the number should be formatted. The string is a combination of the following characters:
* l = left justify
* 0 = pad with zeroes
* \+ = always include the sign, even if positive
* space = add a space in case of a positive number
* h = hexadecimal integer small letters (not valid for formatFloat)
* H = hexadecimal integer capital letters (not valid for formatFloat)
* e = exponent character with small e (only valid for formatFloat)
* E = exponent character with capital E (only valid for formatFloat)
EXAMPLE
// Left justify number in a string with 10 characters
string justified = formatInt(number, 'l', 10);
// Create hexadecimal representation with capital letters, right justified
string hex = formatInt(number, 'H', 10);
// Right justified, padded with zeroes and two digits after the decimal separator
string num = formatFloat(number, '0', 8, 2);
uint length() const
This method returns the length of the string.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
ECHO("Example End");
OUTPUT
[10:49:40.213] Script Started
[10:49:40.213] AT script: Example Start
[10:49:40.213] AT script: 9
[10:49:40.213] AT script: Example End
[10:49:40.266] Script Stopped
void resize(unit reslegth)
This method resizes/sets the length of the string.
PARAMETERS
reslegth: unit
RETURN VALUE
Return type: void
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
ECHO("Example End");
OUTPUT
[10:51:12.868] Script Started
[10:51:12.868] AT script: Example Start
[10:51:12.868] AT script: 14
[10:51:12.868] AT script: Example End
[10:51:12.923] Script Stopped
bool isEmpty() const
This method returns true if the string is empty, i.e. the length is zero.
PARAMETERS
none
RETURN VALUE
Return type: bool
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
if( valStringOne.isEmpty() ){
ECHO("Empty");
}
else{
ECHO("Not empty");
}
ECHO("Example End");
OUTPUT
[10:56:05.260] Script Started
[10:56:05.261] AT script: Example Start
[10:56:05.261] AT script: 14
[10:56:05.261] AT script: Not empty
[10:56:05.261] AT script: Example End
[10:56:05.312] Script Stopped
string substr(uint start = 0, int count = -1) const
This method returns a string with the content starting at the start and the number of bytes given by count. The default arguments will return the whole string as the new string.
PARAMETERS
start: uint default=0
count: int default=-1
RETURN VALUE
Return type: string
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
ECHO( valStringOne.substr(0,3) );
ECHO("Example End");
OUTPUT
[11:00:18.311] Script Started
[11:00:18.311] AT script: Example Start
[11:00:18.311] AT script: 14
[11:00:18.311] AT script: Str
[11:00:18.311] AT script: Example End
[11:00:18.362] Script Stopped
void insert(uint pos, const string &in other)
This method inserts another string other at position pos in the original string.
PARAMETERS
pos: uint
other: const string &in
RETURN VALUE
Return type: void
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
valStringOne.insert(6,"Inserted");
ECHO( valStringOne );
ECHO("Example End");
OUTPUT
[11:28:11.030] Script Started
[11:28:11.030] AT script: Example Start
[11:28:11.030] AT script: 14
[11:28:11.030] AT script: StringInsertedOne
[11:28:11.030] AT script: Example End
[11:28:11.087] Script Stopped
void erase(uint pos, int count = -1)
This method erases a range of characters from the string, starting at position pos and counting count characters.
PARAMETERS
pos: uint
count: int default=-1
RETURN VALUE
Return type: void
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
valStringOne.erase(6,3);
ECHO( valStringOne );
ECHO("Example End");
OUTPUT
[11:30:30.495] Script Started
[11:30:30.495] AT script: Example Start
[11:30:30.495] AT script: 14
[11:30:30.495] AT script: String
[11:30:30.495] AT script: Example End
[11:30:30.549] Script Stopped
int findFirst(const string &in str, uint start = 0) const
This method finds the first occurrence of the value str in the string, starting at the start. If no occurrence is found a negative value will be returned.
PARAMETERS
str: const string &in
start: uint default=0
RETURN VALUE
Return type: int
EXAMPLE
string valStringOne = "StringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valStringOne.resize(valStringOne.length()+5);
valIntRetrun = valStringOne.length();
ECHO(valIntRetrun);
valIntRetrun = valStringOne.findFirst("One",0);
ECHO( valIntRetrun );
ECHO("Example End");
OUTPUT
[11:34:53.168] Script Started
[11:34:53.168] AT script: Example Start
[11:34:53.168] AT script: 14
[11:34:53.168] AT script: 6
[11:34:53.168] AT script: Example End
[11:34:53.232] Script Stopped
int findLast(const string &in str, int start = -1) const
This method finds the last occurrence of the value str in the string. If the start is informed the search will begin at that position, i.e. any potential occurrence after that position will not be searched. If no occurrence is found a negative value will be returned.
PARAMETERS
str: const string &in
start: int default=-1
RETURN VALUE
Return type: int
EXAMPLE
string valStringOne = "StringOneStringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valIntRetrun = valStringOne.findLast("One");
ECHO( valIntRetrun );
ECHO("Example End");
OUTPUT
[11:40:54.164] Script Started
[11:40:54.164] AT script: Example Start
[11:40:54.164] AT script: 15
[11:40:54.164] AT script: Example End
[11:40:54.227] Script Stopped
int findFirstOf(const string &in chars, int start = 0) const
int findFirstNotOf(const string &in chars, int start = 0) const
int findLastOf(const string &in chars, int start = -1) const
int findLastNotOf(const string &in chars, int start = -1) const
The first variant finds the first character in the string that matches one of the characters in chars, starting at the start. If no occurrence is found a negative value will be returned.
The second variant finds the first character that doesn't match any of those in chars. The third and last variants are the same except they start the search from the end of the string.
PARAMETERS
chars: const string &in
start: int
RETURN VALUE
Return type: int
EXAMPLE
string valStringOne = "StringOneStringOne";
int valIntRetrun = 0;
ECHO("Example Start");
valIntRetrun = valStringOne.findFirstOf("One");
ECHO( valIntRetrun );
ECHO("Example End");
OUTPUT
[11:42:09.533] Script Started
[11:42:09.533] AT script: Example Start
[11:42:09.533] AT script: 4
[11:42:09.533] AT script: Example End
[11:42:09.584] Script Stopped
Note These functions work on the individual bytes in the strings. They do not attempt to understand encoded characters, e.g. UTF-8 encoded characters that can take up to 4 bytes.
array<string>@ split(const string &in delimiter) const
This method splits the string into smaller strings where the delimiter is found.
PARAMETERS
delimiter: const string &in
RETURN VALUE
Return type: array<string>@
EXAMPLE
array<string> strArr = "This is a line, separated, by commas.".split(",");
for(int i=0; i<strArr.length(); i++)
{
ECHO(strArr[i]);
}
OUTPUT
AT script: This is a line
AT script: separated
AT script: by commas.
Declare array variables with the array identifier followed by the type of elements within angle brackets. e.g.,
array<int> a; A zero-length array of integers
array<int> b(3); An array of integers with 3 elements
array<int> c(3, 1); An array of integers with 3 elements, all set to 1 by default
array<int> d = {5,6,7}; An array of integers with 3 elements with specific values
array<array<int>> a; An empty array of arrays of integers
array<array<int>> b = {{1,2},{3,4}} A 2 by 2 array with initialized values
= assignment The assignment operator performs a shallow copy of the content.
[] index operator The index operator returns the reference of an element allowing it to be inspected or modified. If the index is out of range, then an exception will be raised.
==, != equality Performs a value comparison on each of the elements in the two arrays and returns true if all match the used operator.
uint length() const Returns the length of the array.
void resize(uint) Sets the new length of the array.
void reverse() Reverses the order of the elements in the array.
void insertAt(uint index, const T& in value)
void insertAt(uint index, const array<T>& arr)
The above two methods, insert a new element, or another array of elements, into the array at the specified index.
void insertLast(const T& in) Appends an element at the end of the array.
void removeAt(uint index) Removes the element at the specified index.
void removeLast() Removes the last element of the array.
void removeRange(uint start, uint count) Removes count elements starting from the start.
void sortAsc()
void sortAsc(uint startAt, uint count)
The above two methods sorts the elements in the array in ascending order. For object types, this will use the type's opCmp method. The second variant will sort only the elements starting at index startAt and the following count elements.
void sortDesc()
void sortDesc(uint startAt, uint count)
This does the same thing as sortAsc except sorts the elements in descending order.
void sort(const less &in compareFunc, uint startAt = 0, uint count = uint(-1)) This method takes as input a callback function to use for comparing two elements when sorting the array.
The callback function should take as parameters two references of the same type of the array elements and it should return a bool. The return value should be true if the first argument should be placed before the second argument.
array<int> arr = {3,2,1};
arr.sort(function(a,b) { return a < b; });
The example shows how to use the sort method with a callback to an anonymous function.
Here's another example where the callback function is declared explicitly.
bool lessForInt(const int &in a, const int &in b){
return a < b;
}
bool lessForHandle(const obj @&in a, const obj @&in b){
return a < b;
}
void sortArrayOfInts(array<int> @arr) { arr.sort(lessForInt); }
void sortArrayOfHandles(array<obj@> @arr) { arr.sort(lessForHandle); }
int find(const T& in)
int find(uint startAt, const T& in)
The above two methods will return the index of the first element that has the same value as the wanted value. If no match is found the methods will return a negative value.
For object types, this will use the type's opEquals or opCmp method to compare the value. For arrays of handles, any null handle will be skipped.
int findByRef(const T& in)
int findByRef(uint startAt, const T& in)
The above two methods will search for a matching address. These are especially useful for arrays of handles where specific instances of objects are desired, and not just objects that happen to have equal value.
If no match is found the methods will return a negative value.
EXAMPLE
void main()
{
array<int> arr = {1,2,3,4,5,6,7,8,9,4};
ECHO( arr.find(4) );
ECHO( arr.find(6,4) );
arr.reverse();
for( uint n = 0; n < arr.length(); n++ )
ECHO(arr[n]);
arr.insertLast(0);
arr.insertAt(2,4);
arr.removeAt(1);
arr.sortAsc();
int sum = 0;
for( uint n = 0; n < arr.length(); n++ )
sum += arr[n];
ECHO(sum);
}
OUTPUT
[19:28:22.453] Script Started
[19:28:22.453] AT script: 3
[19:28:22.454] AT script: 9
[19:28:22.454] AT script: 4
[19:28:22.454] AT script: 9
[19:28:22.454] AT script: 8
[19:28:22.454] AT script: 7
[19:28:22.454] AT script: 6
[19:28:22.454] AT script: 5
[19:28:22.454] AT script: 4
[19:28:22.454] AT script: 3
[19:28:22.454] AT script: 2
[19:28:22.454] AT script: 1
[19:28:22.454] AT script: 44
[19:28:22.507] Script Stopped
uint get_year() const property
This method returns the year of the date stored in the object.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_year();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 2023
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
uint get_month() const property
This method returns the month of the date stored in the object. The range is 1 to 12, i.e. January to December.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_month();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 5
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
uint get_day() const property
This method returns the day of the month of the date stored in the object.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_day();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 10
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
uint get_hour() const property
This method returns the hour of the time (UTC) stored in the object. The range is 0 to 23.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_hour();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 6
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
uint get_minute() const property
This method returns the minute of the time stored in the object. The range is 0 to 59.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_minute();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 44
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
uint get_second() const property
This method returns the second of the time stored in the object. The range is 0 to 59.
PARAMETERS
none
RETURN VALUE
Return type: uint
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valReturned = valDateTime.get_second();
ECHO(valReturned );
ECHO("Example End");
OUTPUT
[11:44:20.889] Script Started
[11:44:20.889] AT script: Example Start
[11:44:20.889] AT script: 20
[11:44:20.889] AT script: Example End
[11:44:20.939] Script Stopped
bool setDate(uint year, uint month, uint day)
This method sets the date. It returns true if the specified date is valid. It does not modify the object if not valid.
PARAMETERS
year: uint
month: uint
day: uint
RETURN VALUE
Return type: bool
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valDateTime.setDate(2023, 5, 11);
valReturned = valDateTime.get_year();
ECHO(valReturned);
valReturned = valDateTime.get_month();
ECHO(valReturned);
valReturned = valDateTime.get_day();
ECHO(valReturned);
ECHO("Example End");
OUTPUT
[11:59:12.734] Script Started
[11:59:12.734] AT script: Example Start
[11:59:12.734] AT script: 2023
[11:59:12.734] AT script: 5
[11:59:12.734] AT script: 11
[11:59:12.734] AT script: Example End
[11:59:12.796] Script Stopped
bool setTime(uint hour, uint minute, uint second)
This method sets the time. It returns true if the specified time is valid. It does not modify the object if not valid.
PARAMETERS
hour: uint
minute: uint
second: uint
RETURN VALUE
Return type: bool
EXAMPLE
datetime valDateTime;
int valReturned = 0;
ECHO("Example Start");
valDateTime.setTime(9, 10, 11);
valReturned = valDateTime.get_hour();
ECHO(valReturned);
valReturned = valDateTime.get_minute();
ECHO(valReturned);
valReturned = valDateTime.get_second();
ECHO(valReturned);
ECHO("Example End");
OUTPUT
[11:59:12.734] Script Started
[11:59:12.734] AT script: Example Start
[11:59:12.734] AT script: 9
[11:59:12.734] AT script: 10
[11:59:12.734] AT script: 11
[11:59:12.734] AT script: Example End
[11:59:12.796] Script Stopped
JSON Support is added in AT Scripting at a core level. Please check the following API:
enum jsonType{OBJECT_VALUE,ARRAY_VALUE,BOOLEAN_VALUE,STRING_VALUE,NUMBER_VALUE,REAL_VALUE,NULL_VALUE};
void set(const string &in, const bool&in)
bool get(const string &in, bool &out) const
void set(const string &in, const int64&in)
bool get(const string &in, int64 &out) const
void set(const string &in, const double&in)
bool get(const string &in, double &out) const
void set(const string &in, const string&in)
bool get(const string &in, string &out) const
void set(const string &in, const array<json@>&in)
bool get(const string &in, array<json@> &out) const
bool exists(const string &in) const
bool isEmpty() const
uint getSize() const
void clear()
jsonType getType()
= assignment
The assignment operator performs a shallow copy of the content.
[] index operator
The index operator takes a string for the key and returns a reference to the value. If the key/value pair doesn't exist it will be inserted with a null value.
json@ jsonParseFile(const string& in)
json@ jsonParse(const string& in)
bool jsonWriteFile(const json& in json,const string& in)
bool jsonWrite(const json& in json,string& out)
Basic trigonometric functions Support is added in AT Scripting at a core level. Please check the following API:
https://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_math.html
The m-center GUI provides a Key/Value pair edit box where the user can configure "Script global variables", which can be accessed in the angel script. Users can add, edit, or delete a global variable with the help of the interface provided (Buttons Add/Edit/Delete). Move Up and Move Down buttons are provided just to re-arrange the variables according to the user's choice.
Users can also add, edit, or delete the Script global variables through the AT Script commands. A general example is given below. Variables added through the script are also available in the UI interface and vice versa.
Script global variables are non-volatile, which means if the user closes the AT script or the m-center, it will retain the global variables.
EXAMPLE
void main()
{
string var1;
string var2;
var1 = string(mc_env["testVar"]); // Accessing a global variable and saving to a string
mc_env.get("testVar", var2); // Alternate Access method
mc_env["testVar"] = "value2"; // Setting a value of global variable
mc_env["newVar"] = "value3"; // Creating a new global variable If a variable does not exist, it will be created
}
void SET_ABORT_CALLBACK(function callback)
This macro is used to set the user-defined function (callback) which will be called when the user stops or aborts the script.
The callback function can be set using MACRO void SET_ABORT_CALLBACK(callback).
The callback function name can be custom or user-defined.
The macro signature should remain as specified in the example below.
PARAMETERS
callback: callback function
RETURN VALUE
Return type: none
EXAMPLE
void main(){
...
SET_ABORT_CALLBACK(MyCallback);
...
}
void MyCallback()
{
ECHO("Script Abort event");
}
Reference: AngelScripts