AtString Class Reference

Arnold String allows for fast string comparisons. More...

#include <ai_string.h>

Public Member Functions
	AtString (const char *str)
	Creating an AtString from a char* is an expensive operation. More...
bool	operator== (const AtString &rhs) const
	Comparing two AtString objects is an extremely fast pointer comparison.
bool	operator!= (const AtString &rhs) const
size_t	length () const
	Computing the length is a fast constant time operation.
bool	empty () const
	Returns true if underlying char* is NULL or "".
	operator const char * () const
	AtString will automatically call c_str() in most situations and so can be automatically used in places that expect a char*. More...
const char *	c_str () const
	Returns the string as a const char*. More...
void	clear ()
size_t	hash () const
	Returns a hashed version of the string. More...

Detailed Description

Arnold String allows for fast string comparisons.

Since it is expensive to create, try to create an AtString once in a preprocess, for instance in node_initialize, and then reuse it instead of creating it over and over, for instance, in shader_evaluate where it could get called millions of times. For string constants, use a static const in the function, or better yet, in the global scope:

static const AtString some_string("some_string"); // this is created only once
void Foo() {
   func_that_uses_string(some_string);
}

The underlying string data contained by an AtString will exist over the entire lifetime of the Arnold library. If you unload the Arnold library in your process, any AtString objects still in existence will become invalid and using them will likely result in a crash or other undefined behavior.

Constructor & Destructor Documentation

AtString::AtString ( const char *  str )

inlineexplicit

Creating an AtString from a char* is an expensive operation.

Try not to do this often. Copying AtString is just a fast pointer copy, so passing AtString by value is fine. Passing NULL to the AtString constructor is valid and c_str() will then return NULL.

Member Function Documentation

AtString::operator const char * ( ) const

inline

AtString will automatically call c_str() in most situations and so can be automatically used in places that expect a char*.

However, functions with a variable number of arguments (printf, AiMsg, ...) will require manually converting to char* with the c_str() member function.

void Bar(const char* str);
void Foo(const AtString astr) {
   Bar(astr);                // passing AtString to a function that expects a const char* happens automatically
   const char* cstr = astr;  // likewise, passing an AtString to a const char* is automatic.  These have no overhead.
   printf("calling printf must use c_str() method: %s", astr.c_str());
} 

const char* AtString::c_str ( ) const

inline

Returns the string as a const char*.

Calling this directly is not normally needed and instead an AtString can be directly used as if it was a const char*.

size_t AtString::hash ( ) const

inline

Returns a hashed version of the string.

This hash is not guaranteed to stay the same across Arnold versions, it should not be written to file or used to influence the look of a shader.

---

The documentation for this class was generated from the following file:

• core/include/ai_string.h