Description
A class that represents a sequence of characters.
Contains methods for examining, searching and replacing, and manipulating strings.
Encoding and String Indexes
Strings in FlexSim are encoded in UTF-8 format.
This means that for simple ASCII strings, each
character takes up a single byte (8-bits). However, non-ASCII characters may consist of
up to 4 bytes. For example, the greek Σ character requires two bytes to encode
in UTF-8.
Since any character in a string may be made up of multiple bytes, it is non-trivial to access
characters in the string by their character index. As such, FlexSim's string interface uses byte-based indexing
for accessing the characters inside the string. In other words, all string methods that take or
return indexes into the string (charAt(),
substr(), slice(),
indexOf(), lastIndexOf(),
search(), slice(),
length, array [] operator),
take and return byte indexes, not character indexes. Also, in FlexSim, all indexing
is 1-based, such that the first byte in a string is accessed by index 1 (not index 0 like in many other
programming languages).
Take the string "Σ=σ" for example. While the = character is technically the second character and thus would
be at "character index" 2, since the Σ character takes up two bytes, the = character is accessed with "byte index" 3.
string("Σ=σ").charAt(3) // returns "="
Note also that, given this rule, some command calls may give back the same results for different byte indexes
because the same character takes up several bytes.
string("Σ=σ").charAt(1) // returns "Σ"
string("Σ=σ").charAt(2) // returns same "Σ"
Usually this will not affect the way you manipulate strings, especially since there are many methods that
do not involve accessing characters by their index, such as using the
replace() and/or match() methods.
If you do need to manually access characters in a string, there are several methods of ensuring that your
code will work for all types of characters.
The easiest way to manipulate individual characters without worrying about encoding is to use the
split() and join() methods. The
split() method will split the string up into an Array of individual characters. Once
it is split, you can traverse the array using character, not byte, indexes. After you are finished you can join the
array back into a string.
string str = "Σ=σ";
Array asArray = str.split();
for (int i = 1; i <= asArray.length; i++) {
if (asArray[i] == "=")
asArray[i] = "≠";
}
str = asArray.join(); // "Σ≠σ"
If you want to search the string by character instead of by byte, but don't want to split it into an array,
you can loop through the string and,
using the charAt() method, increment the looping index based
on the byte-length of each character.
string str = "Σ=σ";
string curChar = "";
for (int i = 1; i <= str.length; i += curChar.length) {
curChar = str.charAt(i);
if (curChar == "=") {
str = str.substring(1, i) + "≠" + str.substring(i + curChar.length);
curChar = "≠";
}
}
If you are searching the string looking for/replacing only ASCII character values, searching the string using the [ ]
array operator can be used.
string str = "Σ=σ";
for (int i = 1; i <= str.length; i++) {
if (str[i] == '=') // comparing a byte to an ASCII character works fine
str[i] = '#'; // setting a byte to an ASCII character works fine,
// as long as the existing byte was already an ASCII character.
}
Finally, the string provides the byteToCharIndex() and charToByteIndex()
methods to convert between character and byte indexes. Note that these methods do require a search of the string, so they will be slow for long strings.
Properties
length |
The length, in bytes, of the string. |
Methods
byteToCharIndex |
Returns the character index associated with a specific byte index in the string. |
charAt |
Returns the character at a given byte index in the string. |
charToByteIndex |
Returns the byte index associated with a specific character index in the string. |
endsWith |
Checks if the string ends with the specified substring. |
includes |
Checks if the string contains the specified substring. |
indexOf |
Returns the index of the first occurence of the specified substring. |
lastIndexOf |
Returns the index of the last occurence of the specified substring. |
match |
Searches the string for matches to a pattern. |
padEnd |
Pads the end of the string with the padString to the given length. |
padStart |
Pads the start of the string with the padString to the given length. |
repeat |
Makes a new string out of copies of the original. |
replace |
Replaces a series of characters with another. |
search |
Searches the string for an internal string or pattern. |
slice |
Extracts a section of a string and returns a new string. |
split |
Splits the string into an array of substrings. |
startsWith |
Checks if the string starts with the specified substring. |
substr |
Extracts a section of a string and returns a new string. |
toLowerCase |
Converts all letters to lowercase. |
toNum |
Interprets the string's content as a floating point number. |
toUpperCase |
Converts all letters to uppercase. |
trim |
Removes leading and trailing whitespace. |
Static Methods
fromNum |
Converts the given number to a string. |
Operators
!= |
Compares two strings. |
[ ] |
Gets or sets a byte element in the string. |
+ |
Concatenates two strings |
+= |
Assigns the string to be a concatenation with another string |
== |
Compares two strings. |
Details
Do no remove, this fixes the anchor on doc.flexsim.com
readonly int length
Description
The length, in bytes, of the string.
int numBytes = str.length;
Do no remove, this fixes the anchor on doc.flexsim.com
string.byteToCharIndex()
int byteToCharIndex(
int byteIndex
)
|
Parameters
byteIndex |
The 1-based byte index of the target character. |
Returns
int
|
The 1-based character index of the character. |
Description
Returns the character index associated with a specific byte index in the string.
string text = "Σ=σ";
int charIndex = text.byteToCharIndex(text.search("=")); // 2
int numChars = text.byteToCharIndex(text.length); // 3 - the number of characters in the string
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
byteIndex |
The 1-based byte index of the target character. |
Returns
string
|
The target character, as a string. |
Description
Returns the character at a given byte index in the string.
string text = "Hello World!";
string e = text.charAt(2); // "e"
Do no remove, this fixes the anchor on doc.flexsim.com
string.charToByteIndex()
int charToByteIndex(
int charIndex
)
|
Parameters
charIndex |
The 1-based character index of the target character. |
Returns
int
|
The 1-based byte index of the character. |
Description
Returns the byte index associated with a specific character index in the string.
string text = "Σ=σ";
int byteIndex = text.charToByteIndex(2); // 3
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
str |
The substring to look for. |
Returns
int
|
1 if the string ends with the specified substring, 0 otherwise. |
Description
Checks if the string ends with the specified substring.
string text = "Hello World!";
int worldEnd = text.endsWith("World!"); // 1
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
str |
The substring to look for. |
Returns
int
|
1 if the string contains the specified substring, 0 otherwise. |
Description
Checks if the string contains the specified substring.
string text = "Hello World!";
int containsWorld = text.includes("World"); // 1
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
str |
The substring to look for. |
Returns
int
|
The byte index of the first occurence of the specified substring, -1 if there are no occurences. |
Description
Returns the index of the first occurence of the specified substring.
string text = "Hello World!";
int oIndex = text.indexOf("o"); // 5
Do no remove, this fixes the anchor on doc.flexsim.com
string.lastIndexOf()
Parameters
str |
The substring to look for. |
Returns
int
|
The byte index of the last occurence of the specified substring, -1 if there are no occurences. |
Description
Returns the index of the last occurence of the specified substring.
string text = "Hello World!";
int oIndex = text.indexOf("o"); // 8
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
pattern |
The pattern of characters to look for, a regular expression. |
Returns
RegExResult
|
A RegExResult object that provides access to matches |
Description
Searches the string for matches to a pattern.
string str = "A noisy noise annoys an oyster.";
var result = str.match(/nois/g);
Array matches = [result[1], result[2]]; // ["nois", "nois"]
See the replace() method for further discussion of regular expressions.
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
targetLength |
The desired length of the padded string. |
padString |
The string used to pad the current string. |
Returns
string
|
The string padded to the specified length. |
Description
Pads the end of the string with the padString to the given length.
Pads the end of the string with the padString to the given targetLength. If the targetLength
is less than the string's length, the string will be returned unpadded.
string s = "abc";
s.padEnd(10); // "abc "
s.padEnd(10, "foo"); // "abcfoofoof"
s.padEnd(6,"123465"); // "abc123"
s.padEnd(8, "0"); // "abc00000"
s.padEnd(1); // "abc"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
targetLength |
The desired length of the padded string. |
padString |
The string used to pad the current string. |
Returns
string
|
The string padded to the specified length. |
Description
Pads the start of the string with the padString to the given length.
Pads the start of the string with the padString to the given targetLength. If the targetLength
is less than the string's length, the string will be returned unpadded.
string s = "abc";
s.padStart(10); // " abc"
s.padStart(10, "foo"); // "foofoofabc"
s.padStart(6,"123465"); // "123abc"
s.padStart(8, "0"); // "00000abc"
s.padStart(1); // "abc"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
numRepeats |
The number of repetitions. |
Returns
string
|
A new string made up of copies of the original. |
Description
Makes a new string out of copies of the original.
string str = "Clap";
string applause = str.repeat(3); // "ClapClapClap"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
findStr |
The string to look for. |
replaceWith |
The string to replace findStr with. |
replaceAll |
Set to 1 to replace all instances of findStr. |
findPattern |
The pattern of characters to look for, a regular expression. |
Returns
string
|
A copy of the string with a find pattern replaced with a new string. |
Description
Replaces a series of characters with another.
Regular Expressions
A regular expression is a concise way of specifying a pattern of characters to look for. You start and end
a regular expression with a forward slash "/" (similar to how you start and end a string with quotes) and then add modifiers:
/pattern/modifiers
Here is a brief explanation of some regular expression syntax.
Modifiers
These come after the closing / of the regular expression and modify their behavior
g - Global Match, matches all occurences, and not just the first one.
i - Case-insensitive match.
Brackets
[] - Matches any character in the brackets. Can use a dash to specify a range of characters.
[abc] - matches an a, b or c.
[a-z] - matches any lowercase letter.
[0-9] - matches any numerical digit.
[^abc] - matches any character that is not an a, b or c.
Or
| - Matches any of the alternatives separated by a |.
(abc|cba)- matches the sequence "abc" or "cba".
(gray|grey) or gr(a|e)y - matches "gray" and "grey".
Quantifiers
Define the quantity of characters the preceding expression will match
* - Matches any string that has zero or more of the specified characters.
ab*c - matches "ac", "abc", "abbc", "abbbc", etc. Basically any sequence of an a, any number of b's, and then a c.
+ - Matches any string that has at least one of the specified characters.
ab+c - almost the same as ab*c except that "ac" no longer matches.
? - Matches any string that has at zero or one of the specified characters.
colou?r - matches both "color" and "colour".
Repetitions
{n} - Matches n number of occurences.
{m,n} - Matches at least m, up to n number of occurences.
Periods
. - Matches any character.
\. - Matches a period.
Examples
This code removes all numbers. We are using [0-9] to find characters in the numeric range and then we put a plus
after it to find any sequence of numbers no matter how long. Finally we add the g modifier to match all occurences.
Replace any instances of blue or green regardless of case with red.
string text = "Blue cars are really green.";
return text.replace(/blue|green/gi, "red"); // "red cars are really red."
Replace all 3 letter words starting with b and ending with t.
string text = "My favorite words are: bit bat but bot bet.";
return text.replace(/b[aeiou]t/g, "Money"); // My favorite words are: Money Money Money Money Money.
Hide any email addresses. Note that "\." is how you specify you want to see a period and not just any character.
string text = "Email me at [email protected] or [email protected]";
return text.replace(/([a-z0-9_\.-]+)@([0-9a-z\.-]+)\.([a-z\.]{2,6})/g, "###"); //Email me at ### or ###
FlexScript's string regular expression implementation uses c++'s regex
library for its functionality, using the ECMAScript grammar.
Our design was also guided by JavaScript's
regular expression implementation.
For more detailed information on building regular expressions, refer to that documentation. Note that we do not (yet) implement
JavaScript's /m, /y, or /u regular expression flags.
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
str |
The string or pattern to search for. |
Returns
int
|
If found, the 1-based byte index of the found string. Otherwise -1. |
Description
Searches the string for an internal string or pattern.
string str = "Hello, how are you?";
int howIndex = str.search("how"); // 8
A regular expression can also be used to find strings.
string str = "Hello, how are you?";
int howIndex = str.split(/h[a-z]+/); // 8 (first word starting with h)
See the replace() method for further discussion of regular expressions.
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
beginIndex |
The 1-based byte index of the first character to extract. If this index
is in the middle of a multi-byte character, it will extract the full character. If it is a negative number,
the start position is string.length + beginIndex, or in other words it is an offset from the end of the
string. |
endIndex |
The 1-based byte index of the end character. The extraction will go up-to-but-not-including
the character at this index. If the index
is in the middle of a multi-byte character, the extraction will include that full character.
If this parameter is left out, the method will extract to the end of the string. If the parameter
is negative, then the end index will be string.length + endIndex, or in other words it is
an offset from the end of the string.
|
Returns
Description
Extracts a section of a string and returns a new string.
string text = "Hello World!";
string subText = text.slice(1, 6); // "Hello"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
delimiter |
The string that marks the separators for where the string should be split.
If this parameter is excluded or is an empty string, every character will be separated into its own array element. |
limit |
The maximum number of array elements to return. If excluded, it will split the whole string. |
Returns
Array
|
An array of substrings made by splitting the string whenever the specified separator is found. |
Description
Splits the string into an array of substrings.
string str = "Hello, how are you?";
Array subStrings = str.split(" ", 3); // ["Hello,", "how", "are"]
string csv = "foo,bar,,baz";
Array subStrings = csv.split(","); // ["foo", "bar", "", "baz"]
A regular expression can also be used to find strings to delimit by. This code removes numbers:
string str = "abcd123efg456hij789klm0";
Array subStrings = str.split(/[0-9]+/g); // ["abcd", "efg", "hij", "klm", ""]
See the replace() method for further discussion of regular expressions.
Do no remove, this fixes the anchor on doc.flexsim.com
string.startsWith()
Parameters
str |
The substring to look for. |
Returns
int
|
1 if the string starts with the specified substring, 0 otherwise. |
Description
Checks if the string starts with the specified substring.
string text = "Hello World!";
int worldStart = text.startsWith("Hello"); // 1
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
beginIndex |
The 1-based byte index of the first character to extract. If this index
is in the middle of a multi-byte character, it will extract the full character. If it is a negative number,
the start position is string.length + beginIndex, or in other words it is an offset from the end of the
string.
|
length |
The length of the target string, in bytes.
|
Returns
Description
Extracts a section of a string and returns a new string.
string text = "Hello World!";
string subText = text.substr(1, 5); // "Hello"
Do no remove, this fixes the anchor on doc.flexsim.com
string.toLowerCase()
Returns
string
|
A new string with all lowercase letters. |
Description
Converts all letters to lowercase.
string text = "Hello World!";
string lower = text.toLowerCase(); // "hello world!"
Do no remove, this fixes the anchor on doc.flexsim.com
Returns
double
|
The interpreted content of the string as a double. |
Description
Interprets the string's content as a floating point number.
string text = "1.5";
double number = text.toNum(); // 1.500
Do no remove, this fixes the anchor on doc.flexsim.com
string.toUpperCase()
Returns
string
|
A new string with all uppercase letters. |
Description
Converts all letters to uppercase.
string text = "Hello World!";
string lower = text.toUpperCase(); // "HELLO WORLD!"
Do no remove, this fixes the anchor on doc.flexsim.com
Returns
Description
Removes leading and trailing whitespace.
string text = " Hello World! ";
string trim = text.trim(); // "Hello World!"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
num |
The number to be converted. |
precision |
The desired number of decimal places to be printed.
Use -1 for automatic precision. |
Returns
string
|
The number as a string. |
Description
Converts the given number to a string.
string text1 = string.fromNum(1.5); // "1.5"
string text2 = string.fromNum(1.5, 2); // "1.50"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
otherString |
The string to compare to this one. |
Returns
int
|
True if the strings are not equal, false otherwise. |
Description
Compares two strings.
"Hello" != "hello" // true
Do no remove, this fixes the anchor on doc.flexsim.com
string.operator [ ]
int
operator [ ](
int byteIndex
)
|
Parameters
byteIndex |
The 1-based byte index of the target byte. |
Returns
int
|
An element of the array. |
Description
Gets or sets a byte element in the string.
The [ ] operator accesses individual elements of the string as byte values. For
an ASCII string, these can be compared to ASCII character values using single-quote
literals such as 'A', 'B', 'C', etc. All ASCII character values are in the integer range [1, 127].
For multi-byte characters, accessing an individual byte will return a value that is
in the integer range [128, 255]. Non-ASCII multi-byte characters in the string that are accessed with
the [ ] operator are read-only. If you try to set the value of a byte that is part of a multi-byte
character using the [ ] operator, FlexSim will throw an exception.
string str = "Σ=σ";
for (int i = 1; i <= str.length; i++) {
if (str[i] == '=') // comparing a byte to an ASCII character works fine
str[i] = '#'; // setting a byte to an ASCII character works fine,
// as long as the existing byte was already an ASCII character.
if (str[i] >= 128)
str[i] = ' '; // setting a byte that is part of a multi-byte character will throw an exception
}
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
otherString |
The string to concatenate with this one. |
Returns
string
|
A new concatenated string. |
Description
Concatenates two strings
string str = "Hello" + ", how are you?"; // "Hello, how are you?"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
otherString |
The string to concatenate with this one. |
Returns
string
|
The concatenated string and assigns it to the variable. |
Description
Assigns the string to be a concatenation with another string
string str = "Hello"
str += ", how are you?"; // "Hello, how are you?"
Do no remove, this fixes the anchor on doc.flexsim.com
Parameters
otherString |
The string to compare to this one. |
Returns
int
|
True if the strings are exactly equal, false otherwise. |
Description
Compares two strings.
"Hello" == "Hello" // true