ustring Class Reference

#include <ustring.h>

List of all members.

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 ustringassign (const ustring &str)
const ustringassign (const ustring &str, size_type pos, size_type n=npos)
const ustringassign (const std::string &str)
const ustringassign (const std::string &str, size_type pos, size_type n=npos)
const ustringassign (const char *str)
const ustringassign (const char *str, size_type n)
const ustringassign (size_type n, char c)
const ustringoperator= (const ustring &str)
const ustringoperator= (const char *str)
const ustringoperator= (const std::string &str)
const ustringoperator= (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)

Detailed Description

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


Constructor & Destructor Documentation

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  )  [inline]

Copy construct a ustring from another ustring.

ustring::ustring ( const ustring str,
size_type  pos,
size_type  n = npos 
) [inline]

Construct a ustring from an indexed substring of a ustring.

ustring::~ustring (  )  [inline]

ustring destructor.


Member Function Documentation

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.

const ustring& ustring::assign ( const ustring str,
size_type  pos,
size_type  n = npos 
) [inline]

Assign a substring of a ustring to *this.

const ustring& ustring::assign ( const ustring str  )  [inline]

Assign 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= ( char  c  )  [inline]

Assign a single char to a ustring.

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.

const ustring& ustring::operator= ( const ustring str  )  [inline]

Assign a ustring to another 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.


Friends And Related Function Documentation

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.

static ustring friend std::ostream& operator<< ( std::ostream &  out,
const ustring str 
) [friend]

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.


Member Data Documentation

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.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Tue Oct 27 06:30:41 2009 for OpenImageIO by  doxygen 1.6.1