SharedString

SharedStrings, once set up as defined in the Shared String Library documentation, can be used almost just like STL strings.  They are immutable, that is, you cannot change the value without reassigning a new string value.

TODO: Complete this documentation

Summary
SharedStrings, once set up as defined in the Shared String Library documentation, can be used almost just like STL strings.
Initializes shared string to /str/; defaults to the empty string if no string is specified.
Initializes shared string to /str/.
Initialize a shared string to the value of /rhs/.
Unregisters the string’s value with the manager.
Returns a constant reference to the string’s value.
Returns a 0-terminated C-style string.
Get the length of the stored string.
Test for case-insensitive equality against /rhs/.
There are three equality operators, overloaded for efficiency.
There are three addition operators, and three += operators.
There are three equality operators, overloaded for efficiency.
There are three less-than operators, overloaded for efficiency.
Points to the string in the manager.
Unregisters the string with the manager.
Registers a string with the shared string table.

Constructors/ Destructor

Default constructor

Initializes shared string to /str/; defaults to the empty string if no string is specified.

Usage

// initialize string s to contain 'hello there'
string str = "hello there";
shared_str s(str);

Author

David C.  Haley (david at the-haleys dot com)

Parameters

strThe initial value of the string

Constructor for C-style strings

Initializes shared string to /str/.  Necessary to disambiguate assignment operators/constructors on certain compilers.

Usage

// initialize string s to contain 'hello there'
shared_str s = "hello there";

Author

David C.  Haley (david at the-haleys dot com)

Parameters

strThe initial value of the string

Copy constructor

Initialize a shared string to the value of /rhs/.

Usage

shared_str s = "hello"; // call normal constructor for s
shared_str t = s; // copy constructor

Author

David C.  Haley (david at the-haleys dot com)

Parameters rhs - The string whose value to initialize to

Destructor

Unregisters the string’s value with the manager.

Author

David C.  Haley (david at the-haleys dot com)

Public methods

str

inline const std::string & str() const

Returns a constant reference to the string’s value.

Returning a constant reference avoids having to copy the string if you don’t have to.

Note

The reference’s validity is undefined if you unregister the string it came from.  (In practice, it should work as long as some other string is using the same value.  But this is not safe practice so you should avoid it.)

Usage

shared_str s = "hello";
cout << s.str() << endl;

Author

David C.  Haley (david at the-haleys dot com)

Returns

A constant reference to the string value

c_str

inline const char * c_str() const

Returns a 0-terminated C-style string.

Convenient if you need the C-style pointer and don’t want to go through the string object.

See usage note for str() regarding safety of the pointer after unregistering the shared string.

Usage

shared_str s = "hello";
printf( "This is the string: %s\n", s.c_str() );

Author

David C.  Haley (david at the-haleys dot com)

Returns

A C-style string pointer to the string’s value.

length

inline typename SharedString<ManagerWrapper>::size_type length() const

Get the length of the stored string.

Usage

shared_str s = "hello";
cout << s.length() << endl; // prints 5

Author

David C.  Haley (david at the-haleys dot com)

Returns

The length of the string

ciEqual

inline bool ciEqual(const SharedString &rhs) const

Test for case-insensitive equality against /rhs/.

Note: Method is overloaded to accept: -SharedString-, -std::string-, -const char *-

Usage

shared_str s = "hello";
cout << s.ciEqual("HeLlO") << endl; // prints 1 (true)

Author

David C.  Haley (david at the-haleys dot com)

Parameters

rhsCheck for case-insensitive equality with this string.

Returns

True if this string is case-insensitively equal to rhs.

Operators

Assignment Operator

There are three equality operators, overloaded for efficiency.

SharedString & operator= (const std::string & rhs)
SharedString & operator= (const SharedString & rhs)
SharedString & operator= (const char * rhs)

They all do the expected thing, and assign rhs to the string on the left hand side (‘this’).

Usage

shared_str s;
s = "foobar";

Parameters

rhsThe value to assign to the left-hand side.

Return

The new value of the string.  (e.g. s = “foo” returns s with value “foo”)

Addition Operator

There are three addition operators, and three += operators.

SharedString operator + (const std::string & rhs) const
SharedString operator + (const SharedString & rhs) const
SharedString operator + (const char * rhs) const

SharedString & operator += (const std::string & rhs)
SharedString & operator += (const SharedString & rhs)
SharedString & operator += (const char * rhs)

They all do the expected thing, and add rhs to the string on the left hand side (‘this’).

Usage

shared_str s = "fo";
s = s + "o";
s += "bar";
// s now contains "foobar"

Parameters

rhsThe value to add to the left-hand side.

Return

The result of the addition.  In the case of the + operator, the returned string is a new copy.  In the case of +=, the returned string is the original left-hand side.

Equality Operator

There are three equality operators, overloaded for efficiency.

bool operator == (const SharedString & rhs) const
bool operator == (const std::string & rhs) const
bool operator == (const char * rhs) const

The != operator is also implemented for all three types.

These return true if lhs == rhs.  Equality is case-sensitive.

(For !=, they return false if == is false.)

Usage

shared_str s = "foo";
shared_str s2 = "foo";
ASSERT( s == s2 );
ASSERT( s != "bar" );

Parameters

rhsThe value to test against.

Return

True if ‘this’ == rhs.

Less-than Operator

There are three less-than operators, overloaded for efficiency.

bool operator < (const SharedString & rhs) const
bool operator < (const std::string & rhs) const
bool operator < (const char * rhs) const

These return true if ‘this’ < rhs.  That is, if ‘this’ is lexicographically less than rhs.

Usage

shared_str s = "foo";
shared_str s2 = "bar";
ASSERT( s2 < s );

Parameters

rhsThe value to test against.

Return

True if ‘this’ < rhs.

Private Members

str_

const std::string * str_

Points to the string in the manager.

deleteString

void deleteString()

Unregisters the string with the manager.

This function must be called before changing the string’s value.

Author

David C.  Haley (david at the-haleys dot com)

assignString

void assignString(const std::string &newstr)

Registers a string with the shared string table.  Adds the string if it’s not already present, or increases the reference count.  Stores the pointer returned by the manager.

Author

David C.  Haley (david at the-haleys dot com)

Parameters

newstrThe string to register and store.
An implementation of shared strings in C++.
inline const std::string & str() const
Returns a constant reference to the string’s value.
inline const char * c_str() const
Returns a 0-terminated C-style string.
inline typename SharedString<ManagerWrapper>::size_type length() const
Get the length of the stored string.
inline bool ciEqual(const SharedString &rhs) const
Test for case-insensitive equality against /rhs/.
const std::string * str_
Points to the string in the manager.
void deleteString()
Unregisters the string with the manager.
void assignString(const std::string &newstr)
Registers a string with the shared string table.
SharedStrings, once set up as defined in the Shared String Library documentation, can be used almost just like STL strings.