String Values

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

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

Standard lexical string comparisons (case sensitive). To perform a case insensitive comparison, first convert the strings to Name values.

<string>[<index_number>]

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

Sets indexed character to character given.

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.

Methods

copy <string>

Creates a new copy of the string value. 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.

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() as a temporary work-around to the current limitation in naming scene objects - there is currently no way to name an object using a computed name. For example:

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

would retrieve the child of $foo named in the variable child_name. Here's a more complex 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:

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.

GetTextExtent <string>

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

findString <string> <search_string>

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

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

filterString <string> <token_string>

Parses string based on token_string and returns an array of strings. 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")

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 can be any length. The sum of from_integer and length_integer must be less than the length of string. An example usage is:

s="1234567890"

s1=replace s 5 3 "inserted string" -- returns "1234inserted string890"

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"

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

Examples

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

Script:

-- 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 in string 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 of outstring 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 - strings not 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:Sphere01 @ [0.0,0.0,0.0] -- result of line 32. Execute function

-- created a sphere object