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> Create a new StringStream using the 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
free <stringStream>Frees the memory used by the stringStream value without waiting for garbage collection.
Available in 3ds Max 9 and higher.
EXAMPLE
ss = stringstream "ABCDE"
--> StringStream:"ABCDE"
ss
--> StringStream:"ABCDE"
free ss
--> OK
ss
--> 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.
<stringstream>append <stringstream> <string>Appends the string passed as second argument to the stringstream provided as first argument.
It operates on the stringstream in place, and also returns the resulting stringstream.
Available in 3ds Max 2012 and higher.
readValue <stringstream> [ ignoreStringEscapes:<boolean> ]
safeReadValue <stringstream> [ ignoreStringEscapes:<boolean> ] [ignoreSSSEState:<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. This option is available in 3ds Max 8 and higher.
The safeReadValue() version always blocks unsafe MAXScript, .NET and Python commands.
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.
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>
safeReadExpr <stringstream> [ignoreSSSEState:<boolean>]Read and evaluate the next MAXScript <expr> from the stringStream. As with execute(), the scope of the evaluation is the global scope, not the current scope.
The safeReadExpr() version always blocks unsafe MAXScript, .NET and Python commands.
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.
readLine <stringstream> Read next line, return as string
readChar <stringstream> Read next char, return as string
readChars <stringstream> <number> errorAtEOF:<boolean>Reads the specified number of characters and returns them in a string.
When the errorAtEOF parameter is false, this method does not throw an exception when it attempts to read past the end of the stringstream. As well, setting this parameter to false and <char_count> to -1 causes this method to read to the end of the stringstream. The default is true.
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.
readDelimitedString (stringStream "This is an abc string") "abc" will return "This is " rather than "This is an".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. Note that the scope of the evaluation is the global scope, not the current scope!
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.