StringStream Values

The StringStream class allows you to construct and parse strings using all the text file I/O functions. For example, you can set up a StringStream and build it up by performing prints and formats to it, just as you would to a text file. Conversely, you can convert a String into a StringStream and then work through it using functions like readLine(), readValue(), skipToString(), etc. Since Strings are easily converted to and from StringStreams, this is often a convenient way to work on large, complex strings.

The StringStream class can be used in conjunction with the AppData accessing functions for storing and retrieving large and complex amounts of script-generated data permanently within a 3ds Max scene file.

Constructors

stringStream <initial_string>

 

<string> as stringStream

Convert existing String to StringStream.

See also String Literals and String Values.

Operators

<stringstream> as string

Convert StringStream to a String

Methods

copy <stringstream>

Create a separate copy of the StringStream

Associated Methods

print <value> to:<stringstream>

 

format "<fmt_string>" {values} to:<stringstream>

The print() and format() functions provide a way to build up a StringStream a piece at a time. As with text file output, each call to print or format appends to existing text, the StringStream dynamically grows as needed. Note that you can reposition output streaming using the seek() function documented below.

The following functions are identical to the text file input functions available for text FileStream values. (See the FileStream Values class documentation). When called on StringStream instances, they read progressively through the string extracting successive values and lines and characters, etc.

readValue <stringstream> [ ignoreStringEscapes:<boolean> ]

Read and evaluate the next MAXScript <operand> from the stringStream.

If the optional ignoreStringEscapes: keyword argument is not supplied or supplied as false and the value read is a string, '\' characters in the string are handled as escape characters. If true, '\' characters in the string are not handled as escape characters. Available in 3ds Max 8 and higher.

For example:

ss = stringstream "\"a\\tb\""

seek ss 0

readvalue ss

Result:

"a  b" -- \t handled as a tab

 

But:

seek ss 0

readvalue ss ignoreStringEscapes:true

Result:

"a\t\b" -- \t handled as characters

 

readExpr <stringstream>

Read and evaluate the next MAXScript <expr> from the stringStream

readLine <stringstream>

Read next line, return as string

readChar <stringstream>

Read next char, return as string

readChars <stringstream> <number>

Reads the specified number of characters and returns them in a string.

readDelimitedString <stringstream> <string>

Takes a delimiter character (as a string) and reads in characters until the delimiter is found (or end-of-file is reached) and returns the characters in a string.

skipToString <stringstream> <string>

Takes a character string and scans forward in the file until it finds an occurrence of the string and positions the file just after that string. If the string is not found, the function returns the value undefined.

skipToNextLine <stringstream>

Positions the input file at the beginning of the next line

execute <stringstream>

Read and evaluate all the expressions left in the stringStream.

filePos <stringstream>

Retrieve the current offset into the file

seek <stringstream> <pos>

Position the file at the given offset so that subsequent I/O will start there.

eof <stringstream>

Returns true if there is no more data in the stringStream, false otherwise.

 

close <stringstream>

 

flush <stringstream>

The close() and flush() functions are provided for consistency with file I/O but are not necessary for StringStreams and do nothing if called.