Developer Guide (Version 1.11)


Lumberyard has a custom reference-counted string class CryString (declared in CryString.h) which is a replacement for STL std::string. CryString should always be preferred over std::string. For convenience, string is used as a typedef for CryString.

How to Use Strings as Key Values for STL Containers

The following code shows good (efficient) and bad usage:

const char *szKey= "Test"; map< string, int >::const_iterator iter = m_values.find( CONST_TEMP_STRING( szKey ) ); // Good map< string, int >::const_iterator iter = m_values.find( szKey ); // Bad

By using the suggested method, you avoid the allocation, deallocation, and copying of a temporary string object, which is a common problem for most string classes. By using the macro CONST_TEMP_STRING, the string class uses the pointer directly without having to free data afterwards.

Further Usage Tips

  • Do not use std::string or std::wstring. Instead, use only string and wstring, and never include the standard string header <string>.

  • Use the c_str() method to access the contents of the string.

  • Because strings are reference-counted, never modify memory returned by the c_str() method. Doing so could affect the wrong string instance.

  • Do not pass strings via abstract interfaces; all interfaces should use const char* in interface methods.

  • CryString has a combined interface of std::string and the MFC CString, so you can use both interface types for string operations.

  • Avoid doing many string operations at runtime as they often cause memory reallocations.

  • For fixed size strings (e.g. 256 chars), use CryFixedStringT, which should be preferred over static char arrays.