ACE_String_Base< CHAR > Class Template Reference

This class provides a wrapper facade for C strings. More...

#include <String_Base.h>

Inheritance diagram for ACE_String_Base< CHAR >:

Collaboration diagram for ACE_String_Base< CHAR >:

List of all members.

Public Member Functions

ACE_String_Base (ACE_Allocator *the_allocator=0)

ACE_String_Base (const CHAR *s, ACE_Allocator *the_allocator=0, bool release=true)

ACE_String_Base (const CHAR *s, size_type len, ACE_Allocator *the_allocator=0, bool release=true)

ACE_String_Base (const ACE_String_Base< CHAR > &s)

ACE_String_Base (CHAR c, ACE_Allocator *the_allocator=0)

ACE_String_Base (size_type len, CHAR c=0, ACE_Allocator *the_allocator=0)

~ACE_String_Base (void)

const CHAR & operator[] (size_type slot) const

CHAR & operator[] (size_type slot)

ACE_String_Base< CHAR > & operator= (const CHAR *s)

ACE_String_Base< CHAR > & operator= (const ACE_String_Base< CHAR > &s)

ACE_String_Base< CHAR > & assign_nocopy (const ACE_String_Base< CHAR > &s)

void set (const CHAR *s, bool release=true)

void set (const CHAR *s, size_type len, bool release)

void clear (bool release=false)

void fast_clear (void)

ACE_String_Base< CHAR > substring (size_type offset, size_type length=npos) const

ACE_String_Base< CHAR > substr (size_type offset, size_type length=npos) const

ACE_String_Base< CHAR > & operator+= (const ACE_String_Base< CHAR > &s)

ACE_String_Base< CHAR > & operator+= (const CHAR *s)

ACE_String_Base< CHAR > & operator+= (const CHAR c)

ACE_String_Base< CHAR > & append (const CHAR *s, size_type slen)

u_long hash (void) const

size_type length (void) const

size_t capacity (void) const

bool is_empty (void) const

bool empty (void) const

CHAR * rep (void) const

const CHAR * fast_rep (void) const

const CHAR * c_str (void) const

size_type strstr (const ACE_String_Base< CHAR > &s) const

size_type find (const ACE_String_Base< CHAR > &str, size_type pos=0) const

size_type find (const CHAR *s, size_type pos=0) const

size_type find (CHAR c, size_type pos=0) const

size_type rfind (CHAR c, size_type pos=npos) const

bool operator== (const ACE_String_Base< CHAR > &s) const

bool operator== (const CHAR *s) const

bool operator< (const ACE_String_Base< CHAR > &s) const

bool operator> (const ACE_String_Base< CHAR > &s) const

bool operator!= (const ACE_String_Base< CHAR > &s) const

bool operator!= (const CHAR *s) const

int compare (const ACE_String_Base< CHAR > &s) const

void dump (void) const

void resize (size_type len, CHAR c=0)

void fast_resize (size_t len)

void swap (ACE_String_Base< CHAR > &str)

Swap the contents of this ACE_String_Base with str.

Public Attributes

ACE_ALLOC_HOOK_DECLARE

Protected Attributes

ACE_Allocator * allocator_

size_type len_

size_type buf_len_

CHAR * rep_

bool release_

Static Protected Attributes

static CHAR NULL_String_ = 0

Detailed Description

template<class CHAR>
class ACE_String_Base< CHAR >

This class provides a wrapper facade for C strings.

This class uses an ACE_Allocator to allocate memory. The user can make this a persistant class by providing an ACE_Allocator with a persistable memory pool. This class is optimized for efficiency, so it doesn't provide any internal locking.

Note:: If an instance of this class is constructed from or assigned an empty string (with first element of ''), then it is not allocated new space. Instead, its internal representation is set equal to a global empty string. CAUTION: in cases when ACE_String_Base is constructed from a provided buffer with the release parameter set to false, ACE_String_Base is not guaranteed to be '' terminated.

Do not use a "@c -1" magic number to refer to the "no position" condition. This was never the right thing to do. The "@c npos" constant should be used in such cases.
Do not assign or pass string positions to or from signed types. Use the "@c size_type" typedef found in all ACE string classes. This typedef is analogous to the "@c size_type" typedef found in the standard C++ string class as well as many STL class templates. If you find yourself casting you're probably doing something wrong.

Constructor & Destructor Documentation

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base ( ACE_Allocator * the_allocator = 0 ) [inline]

Default constructor.

Parameters:

the_allocator

ACE_Allocator associated with string

Returns:: Default ACE_String_Base string.

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base	(	const CHAR *	s,
		ACE_Allocator *	the_allocator = `0`,
		bool	release = `true`
	)			`[inline]`

Constructor that copies s into dynamically allocated memory.

if release == true then a new buffer is allocated internally, and s is copied to the internal buffer. if release == false then the s buffer is used directly. If s == 0 then it will _not_ be used, and instead the internal buffer is set to NULL_String_.

Parameters:

	s	Zero terminated input string
	the_allocator	ACE_Allocator associated with string
	release	Allocator responsible(true)/not reponsible(false) for freeing memory.

Returns:: ACE_String_Base containing const CHAR *s

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base	(	const CHAR *	s,
		size_type	len,
		ACE_Allocator *	the_allocator = `0`,
		bool	release = `true`
	)

Constructor that copies len CHARs of s into dynamically allocated memory (will zero terminate the result).

if release == true then a new buffer is allocated internally. s is copied to the internal buffer. if release == false then the s buffer is used directly. If s == 0 then it will _not_ be used, and instead the internal buffer is set to NULL_String_.

Parameters:

	s	Non-zero terminated input string
	len	Length of non-zero terminated input string
	the_allocator	ACE_Allocator associated with string
	release	Allocator responsible(true)/not reponsible(false) for freeing memory.

Returns:: ACE_String_Base containing const CHAR *s

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base ( const ACE_String_Base< CHAR > & s ) [inline]

Copy constructor.

Parameters:

s

Input ACE_String_Base string to copy

Returns:: Copy of input string s

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base	(	CHAR	c,
		ACE_Allocator *	the_allocator = `0`
	)			`[inline]`

Constructor that copies c into dynamically allocated memory.

Parameters:

	c	Single input character.
	the_allocator	ACE_Allocator associated with string

Returns:: ACE_String_Base containing CHAR 'c'

template<class CHAR>

ACE_String_Base< CHAR >::ACE_String_Base	(	size_type	len,
		CHAR	c = `0`,
		ACE_Allocator *	the_allocator = `0`
	)

Constructor that allocates a len long string.

Warning : This constructor was incorrectly documented in the past. It simply calls resize(len, c). It is probably not advisable to use the second parameter. See resize() for more information.

Parameters:

	len	Amount of space to reserve for the string.
	c	The array is filled with c's
	the_allocator	ACE_Allocator associated with string

Returns:: Empty ACE_String_Base with room for len CHARs

template<class CHAR>

ACE_String_Base< CHAR >::~ACE_String_Base ( void ) [inline]

Deletes the memory...

Member Function Documentation

template<class CHAR>

const CHAR& ACE_String_Base< CHAR >::operator[] ( size_type slot ) const

Return the <slot'th> character in the string (doesn't perform bounds checking).

Parameters:

slot

Index of the desired character

Returns:: The character at index slot

template<class CHAR>

CHAR& ACE_String_Base< CHAR >::operator[] ( size_type slot )

Return the <slot'th> character by reference in the string (doesn't perform bounds checking).

Parameters:

slot

Index of the desired character

Returns:: The character at index slot

template<class CHAR>

ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::operator= ( const CHAR * s ) [inline]

Assignment operator (does copy memory).

Parameters:

s

Input null-terminated CHAR string to assign to this object.

Returns:: Return a copy of the this string.

template<class CHAR>

ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::operator= ( const ACE_String_Base< CHAR > & s ) [inline]

Assignment operator (does copy memory).

Parameters:

s

Input ACE_String_Base string to assign to this object.

Returns:: Return a copy of the this string.

template<class CHAR>

ACE_INLINE ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::assign_nocopy ( const ACE_String_Base< CHAR > & s ) [inline]

Assignment alternative method (does not copy memory).

Parameters:

s

Input ACE_String_Base string to assign to this object.

Returns:: Return this string.

template<class CHAR>

void ACE_String_Base< CHAR >::set	(	const CHAR *	s,
		bool	release = `true`
	)			`[inline]`

Copy s into this ACE_String_Base.

If release == true then a new buffer is allocated internally if the existing one is not big enough to hold s. If the existing buffer is big enough, then it will be used. This means that set(*, 1) can be illegal when the string is constructed with a const char*. (e.g. ACE_String_Base("test", 0, false)).

if release == false then the s buffer is used directly, and any existing buffer is destroyed. If s == 0 then it will _not_ be used, and instead the internal buffer is set to NULL_String_.

Parameters:

	s	Null terminated input string
	release	Allocator responsible(true)/not reponsible(false) for freeing memory.

template<class CHAR>

void ACE_String_Base< CHAR >::set	(	const CHAR *	s,
		size_type	len,
		bool	release
	)

Copy len bytes of s (will zero terminate the result).

If release == true then a new buffer is allocated internally if the existing one is not big enough to hold s. If the existing buffer is big enough, then it will be used. This means that set(*, *, 1) is illegal when the string is constructed with a non-owned const char*. (e.g. ACE_String_Base("test", 0, 0))

If release == false then the s buffer is used directly, and any existing buffer is destroyed. If s == 0 then it will _not_ be used, and instead the internal buffer is set to NULL_String_.

Parameters:

	s	Non-zero terminated input string
	len	Length of input string 's'
	release	Allocator responsible(true)/not reponsible(false) for freeing memory.

template<class CHAR>

void ACE_String_Base< CHAR >::clear ( bool release = false ) [inline]

Clear this string. Memory is _not_ freed if release is false.

Warning: This method was incorrectly documented in the past, but the current implementation has been changed to match the documented behavior.

Warning: clear(false) behaves like fast_clear() below.

Parameters:

release

Memory is freed if true, and not freed if false.

template<class CHAR>

void ACE_String_Base< CHAR >::fast_clear ( void ) [inline]

A more specialized version of clear(): "fast clear". fast_clear() resets the string to 0 length. If the string owns the buffer (

release_== true):
- the string buffer is not freed
- the first character of the buffer is set to 0.

If

release_ is false (this object does not own the buffer):
- the buffer pointer is reset to the NULL_String_ and does not maintain a pointer to the caller-supplied buffer on return
- the maximum string length is reset to 0.

Warning : Calling clear(false) or fast_clear() can have unintended side-effects if the string was constructed (or set()) with an external buffer. The string will be disassociated with the buffer and the next append() or +=() will cause a new buffer to be allocated internally.

template<class CHAR>

ACE_String_Base< CHAR > ACE_String_Base< CHAR >::substring	(	size_type	offset,
		size_type	length = `npos`
	)			const

Return a substring given an offset and length. If length == npos use rest of str. Return empty substring if offset or offset/length are invalid.

Parameters:

	offset	Index of first desired character of the substring.
	length	How many characters to return starting at the offset.

Returns:: The string containing the desired substring

template<class CHAR>

ACE_String_Base< CHAR > ACE_String_Base< CHAR >::substr	(	size_type	offset,
		size_type	length = `npos`
	)			const

Same as <substring>.

Parameters:

	offset	Index of first desired character of the substring.
	length	How many characters to return starting at the offset.

Returns:: The string containing the desired substring

template<class CHAR>

ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::operator+= ( const ACE_String_Base< CHAR > & s ) [inline]

Concat operator (copies memory).

Parameters:

s

Input ACE_String_Base string to concatenate to this string.

Returns:: The combined string (input append to the end of the old). New string is zero terminated.

template<class CHAR>

ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::operator+= ( const CHAR * s ) [inline]

Concat operator (copies memory).

Parameters:

s

Input C string to concatenate to this string.

Returns:: The combined string (input append to the end of the old). New string is zero terminated.

template<class CHAR>

ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::operator+= ( const CHAR c ) [inline]

Concat operator (copies memory).

Parameters:

c

Input CHAR to concatenate to this string.

Returns:: The combined string (input append to the end of the old). New string is zero terminated.

template<class CHAR>

ACE_String_Base< CHAR >& ACE_String_Base< CHAR >::append	(	const CHAR *	s,
		size_type	slen
	)

Append function (copies memory).

Parameters:

	s	Input CHAR array to concatenate to this string.
	slen	The length of the array.

Returns:: The combined string (input append to the end of the old). New string is zero terminated.

template<class CHAR>

u_long ACE_String_Base< CHAR >::hash ( void ) const [inline]

Returns a hash value for this string.

Returns:: Hash value of string

template<class CHAR>

ACE_INLINE ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::length ( void ) const [inline]

Return the length of the string.

Returns:: Length of stored string

template<class CHAR>

ACE_INLINE size_t ACE_String_Base< CHAR >::capacity ( void ) const [inline]

Return the number of allocated CHARs in the string object. This may be greater than the current length of the string.

Returns:: Maximum number of CHAR units that can be stored, including any terminating nul that may be needed.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::is_empty ( void ) const [inline]

Return true if the length of the string is zero, else false.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::empty ( void ) const [inline]

Return true if the length of the string is zero, else false. We recommend using is_empty() instead since it's more consistent with the ACE container naming conventions.

template<class CHAR>

CHAR * ACE_String_Base< CHAR >::rep ( void ) const [inline]

Get a copy of the underlying representation.

This method allocates memory for a copy of the string and returns a pointer to the new area. The caller is responsible for freeing the memory when finished; use delete []

Returns:: Pointer reference to the string data. Returned string is zero terminated.

template<class CHAR>

ACE_INLINE const CHAR * ACE_String_Base< CHAR >::fast_rep ( void ) const [inline]

Get at the underlying representation directly! _Don't_ even think about casting the result to (char *) and modifying it, if it has length 0!

Returns:: Pointer reference to the stored string data. No guarantee is that the string is zero terminated.

template<class CHAR>

ACE_INLINE const CHAR * ACE_String_Base< CHAR >::c_str ( void ) const [inline]

Same as STL String's <c_str> and <fast_rep>.

template<class CHAR>

ACE_INLINE ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::strstr ( const ACE_String_Base< CHAR > & s ) const [inline]

Comparison operator that will match substrings. Returns the slot of the first location that matches, else npos.

Parameters:

s

Input ACE_String_Base string

Returns:: Integer index value of the first location of string s or npos (not found).

template<class CHAR>

size_type ACE_String_Base< CHAR >::find	(	const ACE_String_Base< CHAR > &	str,
		size_type	pos = `0`
	)			const

Find <str> starting at pos. Returns the slot of the first location that matches (will be >= pos), else npos.

Parameters:

	str	Input ACE_String_Base string to search for in stored string.
	pos	Starting index position to start searching for string str.

Returns:: Index value of the first location of string str else npos.

template<class CHAR>

size_type ACE_String_Base< CHAR >::find	(	const CHAR *	s,
		size_type	pos = `0`
	)			const

Find s starting at pos. Returns the slot of the first location that matches (will be >= pos), else npos.

Parameters:

	s	non-zero input string to search for in stored string.
	pos	Starting index position to start searching for string str.

Returns:: Index value of the first location of string str else npos.

template<class CHAR>

size_type ACE_String_Base< CHAR >::find	(	CHAR	c,
		size_type	pos = `0`
	)			const

Find c starting at pos. Returns the slot of the first location that matches (will be >= pos), else npos.

Parameters:

	c	Input character to search for in stored string.
	pos	Starting index position to start searching for string str.

Returns:: Index value of the first location of string str else npos.

template<class CHAR>

size_type ACE_String_Base< CHAR >::rfind	(	CHAR	c,
		size_type	pos = `npos`
	)			const

Find c starting at pos (counting from the end). Returns the slot of the first location that matches, else npos.

Parameters:

	c	Input character to search for in stored string.
	pos	Starting index position to start searching for string str.

Returns:: Index value of the first location of string str else npos.

template<class CHAR>

bool ACE_String_Base< CHAR >::operator== ( const ACE_String_Base< CHAR > & s ) const [inline]

Equality comparison operator (must match entire string).

Parameters:

s

Input ACE_String_Base string to compare against stored string.

Returns:: true if equal, false otherwise.

template<class CHAR>

bool ACE_String_Base< CHAR >::operator== ( const CHAR * s ) const [inline]

Equality comparison operator (must match entire string).

Parameters:

s

Null terminated string to compare against stored string.

Returns:: true if equal, false otherwise.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::operator< ( const ACE_String_Base< CHAR > & s ) const [inline]

Less than comparison operator.

Parameters:

s

Input ACE_String_Base string to compare against stored string.

Returns:: true if less than, false otherwise.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::operator> ( const ACE_String_Base< CHAR > & s ) const [inline]

Greater than comparison operator.

Parameters:

s

Input ACE_String_Base string to compare against stored string.

Returns:: true if greater than, false otherwise.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::operator!= ( const ACE_String_Base< CHAR > & s ) const [inline]

Inequality comparison operator.

Parameters:

s

String to compare against stored string.

Returns:: true if not equal, false otherwise.

template<class CHAR>

ACE_INLINE bool ACE_String_Base< CHAR >::operator!= ( const CHAR * s ) const [inline]

Inequality comparison operator.

Parameters:

s

Null terminated string to compare against stored string.

Returns:: true if not equal, false otherwise.

template<class CHAR>

int ACE_String_Base< CHAR >::compare ( const ACE_String_Base< CHAR > & s ) const [inline]

Performs a strncmp comparison.

Parameters:

s

Input ACE_String_Base string to compare against stored string.

Returns:: Integer value of result (less than 0, 0, greater than 0) depending on how input string s is to the stored string.

template<class CHAR>

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE void ACE_String_Base< CHAR >::dump ( void ) const [inline]

Dump the state of an object.

template<class CHAR>

void ACE_String_Base< CHAR >::resize	(	size_type	len,
		CHAR	c = `0`
	)

This method is designed for high-performance. Please use with care ;-)

Warning : This method was documented incorrectly in the past. The original intention was to change the length of the string to len, and to fill the whole thing with c CHARs. However, what was actually done was to set the length of the string to zero, and fill the buffer with c's. The buffer was also not null-terminated unless c happened to be zero. Rather than fix the method to work as documented, the code is left as is, but the second parameter should probably not be used.

fast_resize just adjusts the buffer if needed and sets the length, it doesn't fill the buffer, so is much faster.

Parameters:

	len	The number of CHARs to reserve
	c	The CHAR to use when filling the string.

template<class CHAR>

void ACE_String_Base< CHAR >::fast_resize ( size_t len ) [inline]

template<class CHAR>

void ACE_String_Base< CHAR >::swap ( ACE_String_Base< CHAR > & str ) [inline]

Swap the contents of this ACE_String_Base with str.

Note:: This is non-throwing operation.

Member Data Documentation

template<class CHAR>

ACE_String_Base< CHAR >::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

template<class CHAR>

ACE_Allocator* ACE_String_Base< CHAR >::allocator_ [protected]

Pointer to a memory allocator.

template<class CHAR>

size_type ACE_String_Base< CHAR >::len_ [protected]

Length of the ACE_String_Base data (not counting the trailing '').

template<class CHAR>

size_type ACE_String_Base< CHAR >::buf_len_ [protected]

Length of the ACE_String_Base data buffer. Keeping track of the length allows to avoid unnecessary dynamic allocations.

template<class CHAR>

CHAR* ACE_String_Base< CHAR >::rep_ [protected]

Pointer to data.

template<class CHAR>

bool ACE_String_Base< CHAR >::release_ [protected]

Flag that indicates if we own the memory

template<class CHAR>

ACE_BEGIN_VERSIONED_NAMESPACE_DECL CHAR ACE_String_Base< CHAR >::NULL_String_ = 0 [inline, static, protected]

Represents the "NULL" string to simplify the internal logic.

The documentation for this class was generated from the following files:


Public Member Functions
	ACE_String_Base (ACE_Allocator *the_allocator=0)
	ACE_String_Base (const CHAR s, ACE_Allocator the_allocator=0, bool release=true)
	ACE_String_Base (const CHAR s, size_type len, ACE_Allocator the_allocator=0, bool release=true)
	ACE_String_Base (const ACE_String_Base< CHAR > &s)
	ACE_String_Base (CHAR c, ACE_Allocator *the_allocator=0)
	ACE_String_Base (size_type len, CHAR c=0, ACE_Allocator *the_allocator=0)
	~ACE_String_Base (void)
const CHAR &	operator[] (size_type slot) const
CHAR &	operator[] (size_type slot)
ACE_String_Base< CHAR > &	operator= (const CHAR *s)
ACE_String_Base< CHAR > &	operator= (const ACE_String_Base< CHAR > &s)
ACE_String_Base< CHAR > &	assign_nocopy (const ACE_String_Base< CHAR > &s)
void	set (const CHAR *s, bool release=true)
void	set (const CHAR *s, size_type len, bool release)
void	clear (bool release=false)
void	fast_clear (void)
ACE_String_Base< CHAR >	substring (size_type offset, size_type length=npos) const
ACE_String_Base< CHAR >	substr (size_type offset, size_type length=npos) const
ACE_String_Base< CHAR > &	operator+= (const ACE_String_Base< CHAR > &s)
ACE_String_Base< CHAR > &	operator+= (const CHAR *s)
ACE_String_Base< CHAR > &	operator+= (const CHAR c)
ACE_String_Base< CHAR > &	append (const CHAR *s, size_type slen)
u_long	hash (void) const
size_type	length (void) const
size_t	capacity (void) const
bool	is_empty (void) const
bool	empty (void) const
CHAR *	rep (void) const
const CHAR *	fast_rep (void) const
const CHAR *	c_str (void) const
size_type	strstr (const ACE_String_Base< CHAR > &s) const
size_type	find (const ACE_String_Base< CHAR > &str, size_type pos=0) const
size_type	find (const CHAR *s, size_type pos=0) const
size_type	find (CHAR c, size_type pos=0) const
size_type	rfind (CHAR c, size_type pos=npos) const
bool	operator== (const ACE_String_Base< CHAR > &s) const
bool	operator== (const CHAR *s) const
bool	operator< (const ACE_String_Base< CHAR > &s) const
bool	operator> (const ACE_String_Base< CHAR > &s) const
bool	operator!= (const ACE_String_Base< CHAR > &s) const
bool	operator!= (const CHAR *s) const
int	compare (const ACE_String_Base< CHAR > &s) const
void	dump (void) const
void	resize (size_type len, CHAR c=0)
void	fast_resize (size_t len)
void	swap (ACE_String_Base< CHAR > &str)
	Swap the contents of this `ACE_String_Base` with str.
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
Protected Attributes
ACE_Allocator *	allocator_
size_type	len_
size_type	buf_len_
CHAR *	rep_
bool	release_
Static Protected Attributes
static CHAR	NULL_String_ = 0

ACE_String_Base< CHAR > Class Template Reference

Public Member Functions

Public Attributes

Protected Attributes

Static Protected Attributes

Detailed Description

template<class CHAR> class ACE_String_Base< CHAR >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class CHAR>
class ACE_String_Base< CHAR >