string
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
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
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); // 3string.endsWith()
| int endsWith( string str ) |
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!"); // 1string.includes()
| int includes( string str ) |
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"); // 1string.indexOf()
| int indexOf( string str ) |
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
string.lastIndexOf()
| int lastIndexOf( string str ) |
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
string.match()
| RegExResult match( RegExp pattern ) |
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.
string.padEnd()
| string padEnd( int targetLength , string padString = " " ) |
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"string.padStart()
| string padStart( int targetLength , string padString = " " ) |
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"string.replace()
| string replace( string findStr , string replaceWith , int replaceAll = 0 ) |
| string replace( RegExp findPattern , string replaceWith ) |
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/modifiersHere 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.
Capture Groups
You can also define what are called capture groups using parentheses. By wrapping parentheses around a character pattern, results found within the parentheses will be saved for use in the replace string. Use the terms $1, $2, etc. in the replace string to reference the first, second, third, etc. captured group in the search pattern.
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.
string text = "300 out of 500 soda cans";
return text.replace(/[0-9]+/g, ""); // " out of soda cans"
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. The string.replace() method's regular expression overload is a wrapper around a call to std::regex_replace. 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.
string.search()
| int search( string str ) |
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"); // 8A 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.
string.slice()
| string slice( int beginIndex , int endIndex = 0 ) |
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
| string | The extracted string. |
Description
Extracts a section of a string and returns a new string.
string text = "Hello World!";
string subText = text.slice(1, 6); // "Hello"string.split()
| Array split( string delimiter = "" , int limit = -1 ) |
| Array split( RegExp delimiter , int limit = -1 ) |
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.
string.startsWith()
| int startsWith( string str ) |
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
string.substr()
| string substr( int beginIndex , int length ) |
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
| string | The extracted string. |
Description
Extracts a section of a string and returns a new string.
string text = "Hello World!";
string subText = text.substr(1, 5); // "Hello"string.fromNum()
| static string fromNum( double num , int precision = -1 ) |
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"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
}string.operator +=
| string operator +=( string otherString ) |
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?"