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

Do no remove, this fixes the anchor on doc.flexsim.com

string.length

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

string.charAt()

string charAt( int byteIndex )

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

string.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!");  // 1
Do no remove, this fixes the anchor on doc.flexsim.com

string.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");  // 1
Do no remove, this fixes the anchor on doc.flexsim.com

string.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
Do no remove, this fixes the anchor on doc.flexsim.com

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
Do no remove, this fixes the anchor on doc.flexsim.com

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.

Do no remove, this fixes the anchor on doc.flexsim.com

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"
Do no remove, this fixes the anchor on doc.flexsim.com

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"
Do no remove, this fixes the anchor on doc.flexsim.com

string.repeat()

string repeat( int numRepeats )

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

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/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 sim-guy34@gmail.com or dev@flexsim.com";
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

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"
Do no remove, this fixes the anchor on doc.flexsim.com

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.

Do no remove, this fixes the anchor on doc.flexsim.com

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
Do no remove, this fixes the anchor on doc.flexsim.com

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"
Do no remove, this fixes the anchor on doc.flexsim.com

string.toLowerCase()

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

string.toNum()

double toNum( )

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()

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

string.trim()

string trim( )

Returns

string The trimmed string.

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

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"
Do no remove, this fixes the anchor on doc.flexsim.com

string.operator !=

int operator !=( string otherString )

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

string.operator +

string operator +( string otherString )

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

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?"
Do no remove, this fixes the anchor on doc.flexsim.com

string.operator ==

int operator ==( string otherString )

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