The String class defines the characteristics of character strings. The character strings can be of any length.

Literal

"<characters>"

See String Literals for a description of String literals.

Constructors

<value> as string

Converts any value into its string representation.

Properties

<string>.count: Integer, read-only

The number of characters in the string.

Operators

<string> + <string>

Returns a new string that is the concatenation of two strings.

<string> == <string>
<string> != <string>
<string> > <string>
<string> < <string>
<string> >= <string>
<string> <= <string>

Standard lexical string comparisons (case sensitive).

To perform a case insensitive equality comparison, please use the stricmp() method that performs a lower-case comparison.

<string>[<index_number>]

Returns the indexed character as a single-character string, index starts at 1.

<string>[<index_number>]= <single_character_string>

Sets the indexed character to the given character.

<string>as<class>

Converts the string to an instance of the given class. You can convert a string into a Name value using the as operator.

FOR EXAMPLE

"Foo" as name-- returns #foo 

You can also convert strings to numbers using the as operator.

FOR EXAMPLE

"123.4" as float-- returns 123.4 

You can use any of the Number classes as a target class: Number, Float, or Integer. If you use Number, the appropriate class will be used depending on the syntax of the number in the string.

You can convert a string to a StringStream value using the as operator.

FOR EXAMPLE

"$box01" as stringstream-- returns the string as a stringstream 

Converting a string to a StringStream value allows you to read through a string using the MAXScript's text file I/O operations. See StringStream Values for a description of StringStreams.

Available in in 3ds Max 2022.1 Update and later

You can convert strings to point values using the as operator: point2, point3, and point4.

FOR EXAMPLE

"[1,2]" as point2
--> [1,2]
"[1,2,3]" as point3
--> [1,2,3]
"[1,2,3,4]" as point4
--> [1,2,3,4]
" \t [1,2,3,4] \t " as point4
--> [1,2,3,4] - whitespace at the beginning and end of the string is allowed
"[1,2,3]" as point4
--> undefined - the string must match the target format

Methods

<string>copy <string>

Creates a new copy of the string value and returns it.

FOR EXAMPLE

newstr = copy oldstr

The new value contains a copy of the text contents of the copied string and is independent of the copied string.

free <string>

Frees the memory used by the string value without waiting for garbage collection.

Available in 3ds Max 9 and higher.

EXAMPLE

s = "ABCD"
--> "ABCD"
s
--> "ABCD"
free s
--> OK
s
--> ""

execute <string>

Compiles and evaluates the contents of the string as a MAXScript expression and returns the result of the evaluation.

FOR EXAMPLE

execute"2 + 2"-- yields the value 4
str ="$foo.ffd_2x2x2.control_point_"+
n as string +" = [1,1,1]"
execute str

The result of an execute() call is the result of the last expression in the string argument.

You can use execute() to access object using a computed name.

FOR EXAMPLE

obj = execute ("$foo/"+ child_name)

It retrieves the child of $foo named in the variable child_name .

Here is a more complex example:

EXAMPLE

side ="left"
finger = 2
limb ="arm"
obj = execute ("$torso/"+ limb +"/"+
side +"/finger/"+
finger as string)

The scope of variables used in the evaluated string is global and not the scope in effect when the execute() method is executed. So, if you call execute() within a function, scripted utility, or anywhere where the scope is not global, you will need to explicitly specify the scope of any variables used in the string that is executed. In the following example, the scope of variable posObj is local to utility myUtil , so the string needs to specify the variable’s name as being in myUtil ’s scope:

EXAMPLE

Utility myUtil"My Utility"
(
local posObj
fn test obj =
(
local i, j, thisCont
thisCont=execute ("myUtil.posObj.'"+j+"'pos.controller")
)
)

In general, you cannot access locals from outside of an object, except for top-level locals in rollouts, utilities, tools, and plug-ins (because they are semi-permanent and are stored with these objects). Function parameters and locals are dynamic and stack-based and not accessible as properties of the function definition.

For more information on variable scope, see Scope of Variables and Accessing Locals and Other Items in a Rollout from External Code.

safeExecute <string> [ignoreSSSEState:<boolean>]

This function is identical to execute(), but always evaluates the script string as if Safe Scene Script Execution is enabled (regardless of whether it actually is). This means all unsafe commands are blocked (see the list of blocked commands in the "Safe Scene Script Execution" topic of the 3ds Max User Guide). This approach mitigates the possibility of malicious code from being injected into the script.

NEW in 3ds Max 2024.1 Update The optional ignoreSSSEState keyword argument, if true, specifies that the function is executed using restricted security settings regardless of whether Safe Scene Script Execution is enabled. The default is false.

Available in in 3ds Max 2022.1 Update and later

<Point2> GetTextExtent<string>

Returns a Point2 value containing the size of the string in pixels if it was displayed in a command panel.

<integer>findString<string> <search_string>

Returns the index of search_string in string or undefined if not found.

EXAMPLE

findString "Thanks for all the fish!" "all" -- returns 12 

<array of strings>filterString <string> <token_string> [splitEmptyTokens:<boolean>]

Parses string based on token_string and returns an array of strings. The filterString splits the input string into substrings based on the characters given in token_string , and returns each substring as a member of the array. The token_string is simply a list of 'splitter characters' (when the string is scanned, any occurrence of any of the tokens is regarded as the start of a substring). This function is useful for file import/export scripts or for any type of manual parsing.

FOR EXAMPLE

filterString "MAX Script, is-dead-funky" ", -"

WOULD RETURN

#("MAX","Script","is","dead","funky")

If splitEmptyTokens is false or not specified, sequential tokens are handled as a single token and tokens at the beginning or end of the string are ignored. If splitEmptyTokens is true , each token found will result in string element in the output, with the string element in the cases ignored above being empty strings. Available in 3ds Max 8 and higher.

FOR EXAMPLE

s = "One\t\tThree\tFour"
tokens = filterString s "\t"
--> #("One", "Three", "Four")
tokens = filterString s "\t" splitEmptyTokens:true
--> #("One", "", "Three", "Four")
s ="\t\t\tOne\t\t\tThree\tFour\t\t\t"
tokens = filterString s "\t"
--> #("One", "Three", "Four")
tokens = filterString s "\t" splitEmptyTokens:true
--> #("", "", "", "One", "", "", "Three", "Four", "", "", "")

<string>replace <string> <from_integer> <length_integer> <new_string>

Returns a new string where the substring in string starting at index from_integer and of length length_integer is replaced with the new_string.new_string of any length. The sum of from_integer and length_integer must be less than the length of string .

FOR EXAMPLE

s="1234567890"
s1=replace s 5 3 "inserted string"

RETURNS:

"1234inserted string890"

<string>substring <string> <from_integer> <length_integer>

Returns a new string consisting of the substring in string starting at index from_integer and of length length_integer . If the sum of from_integer and length_integer is greater than the length of string , a shorter string is returned containing as many characters as are available in the source. If a negative value is specified for length_integer , the remainder of the string starting from from_integer is returned.

FOR EXAMPLE

s ="Balerofon"
ss = substring s 5 3-- returns "rof"
ss = substring s 5 -1-- returns "rofon"
ss = substring s 5 100-- returns "rofon" 

<boolean>matchPattern <string> pattern:<pattern_string> [ignoreCase:<boolean>]

Returns true if string is matched by the wild card pattern_string , false otherwise. The comparison is case-insensitive unless ignoreCase:false is specified.

FOR EXAMPLE

s="text1"
matchPattern s pattern:"text?"-- returns true
matchPattern s pattern:"T*"-- returns true
matchPattern s pattern:"T*"ignoreCase:false-- returns false
matchPattern s pattern:"s*"-- returns false 

<string>append <string1> <string2>

Appends string2 to string1 . Operates on string1 in place and returns string1 as its result.

As this method operates on string1 in place, after running the following code snippet, both s1 and s2 will continue to point to the same string value:

s1 = "aa"
s2 = s1
append s1 "bb"
s1-- returns "aabb"
s2-- returns "aabb"and not "aa" 

Append is typically used when incrementally building a large string from many small strings. As the string is operated on in place, memory usage might be significantly reduced because intermediate string values will not remain in memory until the next garbage collection.

<integer>stricmp <string1> <string2>

In 3ds Max6 and higher, this method performs a lower case comparison of string1 and string2.

Returns an integer value < 0 if string1 is less than string 2, = 0 if string1 is identical to string 2, and > 1 if string1 is greater than string 2.

toUpper <string>

Returns a new string value with the string converted to upper case. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

FOR EXAMPLE

toUpper "so long and thanks for all the scripts"

RESULT:

"SO LONG AND THANKS FOR ALL THE SCRIPTS"

toLower <string>

Returns a new string value with the string converted to lower case. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

FOR EXAMPLE

toLower "Life, The Universe And Everything"

RESULT:

"life, the universe and everything"

substituteString <source_string> <from_string> <to_string> 

Returns a new string with all occurrences of <from_string> in <source_string> replaced with <to_string>. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

FOR EXAMPLE

s1 = "Truth, Justice And The American Way"
s2 = "The American Way"
s3 = "All That Stuff"
s4 = substituteString s1 s2 s3

RESULT:

"Truth, Justice And All That Stuff"

replace_LF_with_CRLF <string>

Returns a new string where line feeds in input string are replaced with carriage return/line feed, unless the character preceding the line feed is a carriage return. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

replace_CRLF_with_LF <string>

Returns a new string where carriage return/line feeds in input string are replaced with line feeds. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

The following script shows the use of various literals, constructors, properties, operators, and methods of the String class.

EXAMPLE

-- strings test bed
fn uppercase instring =-- beginning of function definition
( local upper, lower, outstring-- declare variables as local
upper="ABCDEFGHIJKLMNOPQRSTUVWXYZ"-- set variables to literals
lower="abcdefghijklmnopqrstuvwxyz"

-- create an unique copy of the string referenced by instring,
-- and store reference to unique copy in outstring
outstring=copy instring

-- increment from 1 to number of character in string
for i=1 to outstring.count do

-- see if the single character at index i in outstring
-- is present instring lower
-- If so, j equals position in string lower.
-- If not, j equals undefined
( j=findString lower outstring[i]

-- if character was found in lower,
-- replace with corresponding character in upper:
if (j != undefined) do outstring[i]=upper[j]
)
outstring-- value will be returned as function result
)-- end of fn uppercase

s1="AbCdEfGh"-- set variable to literal
s2=uppercase s1-- call function uppercase, passing s1 as parameter
if s1 == s2 do print "strings s2 and s3 are the same"-- compare strings
if s1 != s2 do print "strings s1 and s2 are different"

theObject="sphere"-- set variable to literal
theRadius= (random 10. 100.) as string-- convert number to string
-- concatenate strings and execute string
myObject=execute (theObject +" radius:"+ theRadius)

OUTPUT:

uppercase()-- result to function definition
"AbCdEfGh"-- result of line 24
"ABCDEFGH"-- result of line 25
undefined-- result of line 26 - stringsnot equal,
-- and no else expression in if expression
"strings s1 and s2 are different"-- output from line 27
"strings s1 and s2 are different"-- result of line 27
"sphere"-- result of line 29
"75.4091"-- result of line 30
$Sphere:Sphere001 @ [0.000000,0.000000,0.000000]-- result of line 32. Execute function
-- created a sphere object