#include <ustring.h>
Classes | |
struct | TableRep |
Public Types | |
typedef char | value_type |
typedef value_type * | pointer |
typedef value_type & | reference |
typedef const value_type & | const_reference |
typedef size_t | size_type |
typedef std::string::const_iterator | const_iterator |
typedef std::string::const_reverse_iterator | const_reverse_iterator |
Public Member Functions | |
ustring (void) | |
ustring (const char *str) | |
ustring (const char *str, size_type pos, size_type n) | |
ustring (const char *str, size_type n) | |
ustring (size_type n, char c) | |
ustring (const std::string &str) | |
ustring (const std::string &str, size_type pos, size_type n=npos) | |
ustring (const ustring &str) | |
ustring (const ustring &str, size_type pos, size_type n=npos) | |
~ustring () | |
const ustring & | assign (const ustring &str) |
const ustring & | assign (const ustring &str, size_type pos, size_type n=npos) |
const ustring & | assign (const std::string &str) |
const ustring & | assign (const std::string &str, size_type pos, size_type n=npos) |
const ustring & | assign (const char *str) |
const ustring & | assign (const char *str, size_type n) |
const ustring & | assign (size_type n, char c) |
const ustring & | operator= (const ustring &str) |
const ustring & | operator= (const char *str) |
const ustring & | operator= (const std::string &str) |
const ustring & | operator= (char c) |
const char * | c_str () const |
const char * | data () const |
const std::string & | string () const |
void | clear (void) |
size_t | length (void) const |
size_t | hash (void) const |
size_t | size (void) const |
bool | empty (void) const |
operator int (void) | |
const_iterator | begin () const |
const_iterator | end () const |
const_reverse_iterator | rbegin () const |
const_reverse_iterator | rend () const |
const_reference | operator[] (size_type pos) const |
size_type | copy (char *s, size_type n, size_type pos=0) const |
int | compare (const ustring &str) const |
int | compare (const std::string &str) const |
bool | operator== (const ustring &str) const |
bool | operator!= (const ustring &str) const |
bool | operator== (const std::string &x) const |
bool | operator!= (const std::string &x) const |
bool | operator< (const ustring &x) const |
Static Public Member Functions | |
static ustring | format (const char *fmt,...) OPENIMAGEIO_PRINTF_ARGS(1 |
Static Public Attributes | |
static const size_type | npos = static_cast<size_type>(-1) |
static const off_t | chars_offset = sizeof(std::string)+2*sizeof(unsigned int) |
Friends | |
int | compare (const std::string &a, const ustring &b) |
bool | operator== (const std::string &a, const ustring &b) |
bool | operator!= (const std::string &a, const ustring &b) |
static ustring friend std::ostream & | operator<< (std::ostream &out, const ustring &str) |
A ustring is an alternative to char* or std::string for storing strings, in which the character sequence is unique (allowing many speed advantages for assignment, equality testing, and inequality testing).
The implementation is that behind the scenes there is a hash set of allocated strings, so the characters of each string are unique. A ustring itself is a pointer to the characters of one of these canonical strings. Therefore, assignment and equality testing is just a single 32- or 64-bit int operation, the only mutex is when a ustring is created from raw characters, and the only malloc is the first time each canonical ustring is created.
The internal table also contains a std::string version and the length of the string, so converting a ustring to a std::string (via ustring::string()) or querying the number of characters (via ustring::size() or ustring::length()) is extremely inexpensive, and does not involve creation/allocation of a new std::string or a call to strlen.
We try very hard to completely mimic the API of std::string, including all the constructors, comparisons, iterations, etc. Of course, the charaters of a ustring are non-modifiable, so we do not replicate any of the non-const methods of std::string. But in most other ways it looks and acts like a std::string and so most templated algorthms that would work on a "const std::string &" will also work on a ustring.
Usage guidelines:
Compared to standard strings, ustrings have several advantages:
But there are some problems, too. Canonical strings are never freed from the table. So in some sense all the strings "leak", but they only leak one copy for each unique string that the program ever comes across. Also, creation of unique strings from raw characters is more expensive than for standard strings, due to hashing, table queries, and other overhead.
On the whole, ustrings are a really great string representation
ustrings are not so hot
ustring::ustring | ( | void | ) | [inline] |
Default ctr for ustring -- make an empty string.
ustring::ustring | ( | const char * | str | ) | [inline, explicit] |
Construct a ustring from a null-terminated C string (char *).
ustring::ustring | ( | const char * | str, | |
size_type | pos, | |||
size_type | n | |||
) | [inline] |
Construct a ustring from at most n characters of str, starting at position pos.
ustring::ustring | ( | const char * | str, | |
size_type | n | |||
) | [inline] |
Construct a ustring from the first n characters of str.
ustring::ustring | ( | size_type | n, | |
char | c | |||
) | [inline] |
Construct a ustring from n copies of character c.
ustring::ustring | ( | const std::string & | str | ) | [inline, explicit] |
Construct a ustring from a C++ std::string.
ustring::ustring | ( | const std::string & | str, | |
size_type | pos, | |||
size_type | n = npos | |||
) | [inline] |
Construct a ustring from an indexed substring of a std::string.
ustring::ustring | ( | const ustring & | str, | |
size_type | pos, | |||
size_type | n = npos | |||
) | [inline] |
ustring::~ustring | ( | ) | [inline] |
ustring destructor.
const ustring& ustring::assign | ( | size_type | n, | |
char | c | |||
) | [inline] |
Assign n copies of c to *this.
const ustring& ustring::assign | ( | const char * | str, | |
size_type | n | |||
) | [inline] |
Assign the first n characters of str to *this.
const ustring& ustring::assign | ( | const char * | str | ) | [inline] |
Assign a null-terminated C string (char*) to *this.
const ustring& ustring::assign | ( | const std::string & | str, | |
size_type | pos, | |||
size_type | n = npos | |||
) | [inline] |
Assign a substring of a std::string to *this.
const ustring& ustring::assign | ( | const std::string & | str | ) | [inline] |
Assign a std::string to *this.
Assign a substring of a ustring to *this.
const_iterator ustring::begin | ( | ) | const [inline] |
Return a const_iterator that references the first character of the string.
const char* ustring::c_str | ( | ) | const [inline] |
Return a C string representation of a ustring.
void ustring::clear | ( | void | ) | [inline] |
Reset to an empty string.
int ustring::compare | ( | const std::string & | str | ) | const [inline] |
Return 0 if *this is lexicographically equal to str, -1 if this is lexicographically earlier than str, 1 if *this is lexicographically after str.
int ustring::compare | ( | const ustring & | str | ) | const [inline] |
Return 0 if *this is lexicographically equal to str, -1 if this is lexicographically earlier than str, 1 if *this is lexicographically after str.
size_type ustring::copy | ( | char * | s, | |
size_type | n, | |||
size_type | pos = 0 | |||
) | const [inline] |
Dump into character array s the characters of this ustring, beginning with position pos and copying at most n characters.
const char* ustring::data | ( | ) | const [inline] |
Return a C string representation of a ustring.
bool ustring::empty | ( | void | ) | const [inline] |
Is the string empty -- i.e., is it the NULL pointer or does it point to an empty string?
const_iterator ustring::end | ( | ) | const [inline] |
Return a const_iterator that references the end of a traversal of the characters of the string.
static ustring ustring::format | ( | const char * | fmt, | |
... | ||||
) | [static] |
Construct a ustring in a printf-like fashion. In other words, something like: ustring s = ustring::format ("blah %d %g", (int)foo, (float)bar);
size_t ustring::hash | ( | void | ) | const [inline] |
Return a hashed version of the string
size_t ustring::length | ( | void | ) | const [inline] |
Return the number of characters in the string.
ustring::operator int | ( | void | ) | [inline] |
Cast to int, which is interpreted as testing whether it's not an empty string. This allows you to write "if (t)" with the same semantics as if it were a char*.
bool ustring::operator!= | ( | const std::string & | x | ) | const [inline] |
Test a ustring (*this) for lexicographic inequality with std::string x.
bool ustring::operator!= | ( | const ustring & | str | ) | const [inline] |
Test two ustrings for inequality -- are they comprised of different sequences of characters. Note that because ustrings are unique, this is a trivial pointer comparison, not a char-by-char loop as would be the case with a char* or a std::string.
bool ustring::operator< | ( | const ustring & | x | ) | const [inline] |
Test for lexicographic 'less', comes in handy for lots of STL containers and algorithms.
const ustring& ustring::operator= | ( | const std::string & | str | ) | [inline] |
Assign a C++ std::string to a ustring.
const ustring& ustring::operator= | ( | const char * | str | ) | [inline] |
Assign a null-terminated C string (char *) to a ustring.
bool ustring::operator== | ( | const std::string & | x | ) | const [inline] |
Test a ustring (*this) for lexicographic equality with std::string x.
bool ustring::operator== | ( | const ustring & | str | ) | const [inline] |
Test two ustrings for equality -- are they comprised of the same sequence of characters. Note that because ustrings are unique, this is a trivial pointer comparison, not a char-by-char loop as would be the case with a char* or a std::string.
const_reference ustring::operator[] | ( | size_type | pos | ) | const [inline] |
Return a reference to the character at the given position. Note that it's up to the caller to be sure pos is within the size of the string.
const_reverse_iterator ustring::rbegin | ( | ) | const [inline] |
Return a const_reverse_iterator that references the last character of the string.
const_reverse_iterator ustring::rend | ( | ) | const [inline] |
Return a const_reverse_iterator that references the end of a reverse traversal of the characters of the string.
size_t ustring::size | ( | void | ) | const [inline] |
Return the number of characters in the string.
const std::string& ustring::string | ( | ) | const [inline] |
Return a C++ std::string representation of a ustring.
int compare | ( | const std::string & | a, | |
const ustring & | b | |||
) | [friend] |
Return 0 if a is lexicographically equal to b, -1 if a is lexicographically earlier than b, 1 if a is lexicographically after b.
bool operator!= | ( | const std::string & | a, | |
const ustring & | b | |||
) | [friend] |
Test for lexicographic inequality between std::string a and ustring b.
Generic stream output of a ustring.
bool operator== | ( | const std::string & | a, | |
const ustring & | b | |||
) | [friend] |
Test for lexicographic equality between std::string a and ustring b.
const off_t ustring::chars_offset = sizeof(std::string)+2*sizeof(unsigned int) [static] |
Constant defining how far beyond the beginning of a TableRep are the canonical characters.