Public Member Functions
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...
 
AI_DEVICE bool operator== (const AtString &rhs) const
 Comparing two AtString objects is an extremely fast pointer comparison.
 
AI_DEVICE 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...
 
AI_DEVICE const char * c_str () const
 Returns the string as a const char*. More...
 
AI_DEVICE void clear ()
 
AI_DEVICE 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());
}
AI_DEVICE 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*.

AI_DEVICE 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:

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com