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 >:
Inheritance graph
[legend]
Collaboration diagram for ACE_String_Base< CHAR >:
Collaboration graph
[legend]

List of all members.

Public Types

typedef
ACE_String_Base_Iterator< CHAR > 		ITERATOR
typedef
ACE_String_Base_Const_Iterator
< CHAR > 		CONST_ITERATOR
typedef
ACE_String_Base_Iterator< CHAR > 		iterator
typedef
ACE_String_Base_Const_Iterator
< CHAR > 		const_iterator
typedef ACE_Allocator::size_type size_type

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.
iterator begin (void)
const_iterator begin (void) const
iterator end (void)
const_iterator end (void) const

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

Friends

class ACE_String_Base_Iterator< CHAR >
class ACE_String_Base_Const_Iterator< CHAR >

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.

Definition at line 67 of file String_Base.h.

Member Typedef Documentation

template<class CHAR>
typedef ACE_String_Base_Const_Iterator<CHAR> ACE_String_Base< CHAR >::const_iterator

Definition at line 81 of file String_Base.h.

template<class CHAR>
typedef ACE_String_Base_Const_Iterator<CHAR> ACE_String_Base< CHAR >::CONST_ITERATOR

Definition at line 77 of file String_Base.h.

template<class CHAR>
typedef ACE_String_Base_Iterator<CHAR> ACE_String_Base< CHAR >::iterator

Definition at line 80 of file String_Base.h.

template<class CHAR>
typedef ACE_String_Base_Iterator<CHAR> ACE_String_Base< CHAR >::ITERATOR

Definition at line 76 of file String_Base.h.

template<class CHAR>
typedef ACE_Allocator::size_type ACE_String_Base_Const::size_type

Definition at line 41 of file String_Base_Const.h.

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.

Definition at line 28 of file String_Base.cpp.

00029   : allocator_ (the_allocator ? the_allocator : ACE_Allocator::instance ()),
00030     len_ (0),
00031     buf_len_ (0),
00032     rep_ (&ACE_String_Base<CHAR>::NULL_String_),
00033     release_ (false)
00034 {
00035   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00036 }

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

Definition at line 41 of file String_Base.cpp.

00044   : allocator_ (the_allocator ? the_allocator : ACE_Allocator::instance ()),
00045     len_ (0),
00046     buf_len_ (0),
00047     rep_ (0),
00048     release_ (false)
00049 {
00050   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00051   this->set (s, release);
00052 }

template<class CHAR>
ACE_String_Base< CHAR >::ACE_String_Base ( const CHAR *  s,
typename ACE_String_Base< CHAR >::size_type  len,
ACE_Allocator *  the_allocator = 0,
bool  release = true 
) [inline]

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

Definition at line 71 of file String_Base.cpp.

00076   : allocator_ (the_allocator ? the_allocator : ACE_Allocator::instance ()),
00077     len_ (0),
00078     buf_len_ (0),
00079     rep_ (0),
00080     release_ (false)
00081 {
00082   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00083 
00084   this->set (s, len, release);
00085 }

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

Definition at line 90 of file String_Base.cpp.

00091   : allocator_ (s.allocator_ ? s.allocator_ : ACE_Allocator::instance ()),
00092     len_ (0),
00093     buf_len_ (0),
00094     rep_ (0),
00095     release_ (false)
00096 {
00097   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00098 
00099   this->set (s.rep_, s.len_, true);
00100 }

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'

Definition at line 55 of file String_Base.cpp.

00057   : allocator_ (the_allocator ? the_allocator : ACE_Allocator::instance ()),
00058     len_ (0),
00059     buf_len_ (0),
00060     rep_ (0),
00061     release_ (false)
00062 {
00063   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00064 
00065   this->set (&c, 1, true);
00066 }

template<class CHAR>
ACE_String_Base< CHAR >::ACE_String_Base ( typename ACE_String_Base< CHAR >::size_type  len,
CHAR  c = 0,
ACE_Allocator *  the_allocator = 0 
) [inline]

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

Definition at line 103 of file String_Base.cpp.

00107   : allocator_ (the_allocator ? the_allocator : ACE_Allocator::instance ()),
00108     len_ (0),
00109     buf_len_ (0),
00110     rep_ (0),
00111     release_ (false)
00112 {
00113   ACE_TRACE ("ACE_String_Base<CHAR>::ACE_String_Base");
00114 
00115   this->resize (len, c);
00116 }

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

Deletes the memory...

Definition at line 119 of file String_Base.cpp.

00120 {
00121   ACE_TRACE ("ACE_String_Base<CHAR>::~ACE_String_Base");
00122 
00123   if (this->buf_len_ != 0 && this->release_)
00124       this->allocator_->free (this->rep_);
00125 }

Member Function Documentation

template<class CHAR>
ACE_String_Base< CHAR > & ACE_String_Base< CHAR >::append ( const CHAR *  s,
typename ACE_String_Base< CHAR >::size_type  slen 
) [inline]

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.

Definition at line 213 of file String_Base.cpp.

00215 {
00216   ACE_TRACE ("ACE_String_Base<CHAR>::append(const CHAR*, size_type)");
00217   if (slen > 0 && slen != npos)
00218   {
00219     // case 1. No memory allocation needed.
00220     if (this->buf_len_ >= this->len_ + slen + 1)
00221     {
00222       // Copy in data from new string.
00223       ACE_OS::memcpy (this->rep_ + this->len_, s, slen * sizeof (CHAR));
00224     }
00225     else // case 2. Memory reallocation is needed
00226     {
00227       const size_type new_buf_len =
00228         ace_max(this->len_ + slen + 1, this->buf_len_ + this->buf_len_ / 2);
00229 
00230       CHAR *t = 0;
00231 
00232       ACE_ALLOCATOR_RETURN (t,
00233         (CHAR *) this->allocator_->malloc (new_buf_len * sizeof (CHAR)), *this);
00234 
00235       // Copy memory from old string into new string.
00236       ACE_OS::memcpy (t, this->rep_, this->len_ * sizeof (CHAR));
00237 
00238       ACE_OS::memcpy (t + this->len_, s, slen * sizeof (CHAR));
00239 
00240       if (this->buf_len_ != 0 && this->release_)
00241         this->allocator_->free (this->rep_);
00242 
00243       this->release_ = true;
00244       this->rep_ = t;
00245       this->buf_len_ = new_buf_len;
00246     }
00247 
00248     this->len_ += slen;
00249     this->rep_[this->len_] = 0;
00250   }
00251 
00252   return *this;
00253 }

template<class CHAR>
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.

Definition at line 22 of file String_Base.inl.

00023 {
00024   ACE_TRACE ("ACE_String_Base<CHAR>::assign_nocopy");
00025   this->set (s.rep_, s.len_, false);
00026   return *this;
00027 }

template<class CHAR >
ACE_String_Base< CHAR >::const_iterator ACE_String_Base< CHAR >::begin ( void   )  const [inline]

Definition at line 153 of file String_Base.inl.

00154 {
00155   ACE_TRACE ("ACE_String_Base<CHAR>::begin");
00156   return const_iterator (*this);
00157 }

template<class CHAR >
ACE_String_Base< CHAR >::iterator ACE_String_Base< CHAR >::begin ( void   )  [inline]

Definition at line 146 of file String_Base.inl.

00147 {
00148   ACE_TRACE ("ACE_String_Base<CHAR>::begin");
00149   return iterator (*this);
00150 }

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

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

Definition at line 91 of file String_Base.inl.

00092 {
00093   return this->rep_;
00094 }

template<class CHAR >
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.

Definition at line 37 of file String_Base.inl.

00038 {
00039   ACE_TRACE ("ACE_String_Base<CHAR>::capacity");
00040   return this->buf_len_;
00041 }

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.

Definition at line 296 of file String_Base.cpp.

00297 {
00298   // This can't use set(), because that would free memory if release=false
00299   if (release)
00300   {
00301     if (this->buf_len_ != 0 && this->release_)
00302       this->allocator_->free (this->rep_);
00303 
00304     this->rep_ = &ACE_String_Base<CHAR>::NULL_String_;
00305     this->len_ = 0;
00306     this->buf_len_ = 0;
00307     this->release_ = false;
00308   }
00309   else
00310     {
00311       this->fast_clear ();
00312     }
00313 }

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.

Definition at line 383 of file String_Base.cpp.

00384 {
00385   ACE_TRACE ("ACE_String_Base<CHAR>::compare");
00386 
00387   if (this->rep_ == s.rep_)
00388     return 0;
00389 
00390   // Pick smaller of the two lengths and perform the comparison.
00391   size_type smaller_length = ace_min (this->len_, s.len_);
00392 
00393   int result = ACE_OS::memcmp (this->rep_,
00394                                s.rep_,
00395                                smaller_length * sizeof (CHAR));
00396 
00397   if (result == 0 && this->len_ != s.len_)
00398     result = this->len_ > s.len_ ? 1 : -1;
00399   return result;
00400 }

template<class CHAR >
void ACE_String_Base< CHAR >::dump ( void   )  const [inline]

Dump the state of an object.

Definition at line 13 of file String_Base.inl.

00014 {
00015 #if defined (ACE_HAS_DUMP)
00016   ACE_TRACE ("ACE_String_Base<CHAR>::dump");
00017 #endif /* ACE_HAS_DUMP */
00018 }

template<class CHAR >
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.

Definition at line 50 of file String_Base.inl.

00051 {
00052   return this->is_empty ();
00053 }

template<class CHAR >
ACE_String_Base< CHAR >::const_iterator ACE_String_Base< CHAR >::end ( void   )  const [inline]

Definition at line 167 of file String_Base.inl.

00168 {
00169   ACE_TRACE ("ACE_String_Base<CHAR>::end");
00170   return const_iterator (*this, 1);
00171 }

template<class CHAR >
ACE_String_Base< CHAR >::iterator ACE_String_Base< CHAR >::end ( void   )  [inline]

Definition at line 160 of file String_Base.inl.

00161 {
00162   ACE_TRACE ("ACE_String_Base<CHAR>::end");
00163   return iterator (*this, 1);
00164 }

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.

Definition at line 351 of file String_Base.cpp.

00352 {
00353   this->len_ = 0;
00354   if (this->release_)
00355     {
00356       // String retains the original buffer.
00357       if (this->rep_ != &ACE_String_Base<CHAR>::NULL_String_)
00358         this->rep_[0] = 0;
00359     }
00360   else
00361     {
00362       // External buffer: string relinquishes control of it.
00363       this->buf_len_ = 0;
00364       this->rep_ = &ACE_String_Base<CHAR>::NULL_String_;
00365     }
00366 }

template<class CHAR >
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.

Definition at line 85 of file String_Base.inl.

00086 {
00087   return this->rep_;
00088 }

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

Definition at line 275 of file String_Base.cpp.

00276 {
00277   ACE_TRACE ("ACE_String_Base<CHAR>::fast_resize");
00278 
00279   // Only reallocate if we don't have enough space...
00280   if (this->buf_len_ <= len)
00281     {
00282       if (this->buf_len_ != 0 && this->release_)
00283         this->allocator_->free (this->rep_);
00284 
00285       this->rep_ = static_cast<CHAR*>
00286                      (this->allocator_->malloc ((len + 1) * sizeof (CHAR)));
00287       this->buf_len_ = len + 1;
00288       this->release_ = true;
00289     }
00290   this->len_ = 0;
00291   if (len > 0)
00292     this->rep_[0] = 0;
00293 }

template<class CHAR>
ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::find ( CHAR  c,
typename ACE_String_Base< CHAR >::size_type  pos = 0 
) const [inline]

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.

Definition at line 438 of file String_Base.cpp.

00441 {
00442   CHAR *substr = this->rep_ + pos;
00443   CHAR *pointer = ACE_OS::strnchr (substr, c, this->len_ - pos);
00444   if (pointer == 0)
00445     return ACE_String_Base<CHAR>::npos;
00446   else
00447     return pointer - this->rep_;
00448 }

template<class CHAR>
ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::find ( const CHAR *  s,
typename ACE_String_Base< CHAR >::size_type  pos = 0 
) const [inline]

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.

Definition at line 424 of file String_Base.cpp.

00427 {
00428   CHAR *substr = this->rep_ + pos;
00429   size_t len = ACE_OS::strlen (s);
00430   CHAR *pointer = ACE_OS::strnstr (substr, s, len);
00431   if (pointer == 0)
00432     return ACE_String_Base<CHAR>::npos;
00433   else
00434     return pointer - this->rep_;
00435 }

template<class CHAR>
ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::find ( const ACE_String_Base< CHAR > &  str,
typename ACE_String_Base< CHAR >::size_type  pos = 0 
) const [inline]

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.

Definition at line 131 of file String_Base.inl.

00133 {
00134   ACE_TRACE ("ACE_String_Base<CHAR>::find");
00135   return this->find (str.rep_, pos);
00136 }

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

Definition at line 256 of file String_Base.cpp.

00257 {
00258   return
00259     ACE::hash_pjw (reinterpret_cast<char *> (
00260                       const_cast<CHAR *> (this->rep_)),
00261                    this->len_ * sizeof (CHAR));
00262 }

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

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

Definition at line 44 of file String_Base.inl.

00045 {
00046   return this->len_ == 0;
00047 }

template<class CHAR >
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

Definition at line 30 of file String_Base.inl.

00031 {
00032   ACE_TRACE ("ACE_String_Base<CHAR>::length");
00033   return this->len_;
00034 }

template<class CHAR>
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.

Definition at line 125 of file String_Base.inl.

00126 {
00127   return !(*this == s);
00128 }

template<class CHAR>
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.

Definition at line 118 of file String_Base.inl.

00119 {
00120   ACE_TRACE ("ACE_String_Base<CHAR>::operator!=");
00121   return !(*this == s);
00122 }

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.

Definition at line 654 of file String_Base.cpp.

00655 {
00656   ACE_TRACE ("ACE_String_Base<CHAR>::operator+=(const CHAR)");
00657   const size_type slen = 1;
00658   return this->append (&c, slen);
00659 }

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.

Definition at line 636 of file String_Base.cpp.

00637 {
00638   size_t slen = 0;
00639   if (s != 0)
00640     slen = ACE_OS::strlen (s);
00641   return this->append (s, slen);
00642 }

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.

Definition at line 646 of file String_Base.cpp.

00647 {
00648   ACE_TRACE ("ACE_String_Base<CHAR>::operator+=(const ACE_String_Base<CHAR> &)");
00649   return this->append (s.rep_, s.len_);
00650 }

template<class CHAR>
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.

Definition at line 99 of file String_Base.inl.

00100 {
00101   ACE_TRACE ("ACE_String_Base<CHAR>::operator <");
00102   return compare (s) < 0;
00103 }

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.

Definition at line 327 of file String_Base.cpp.

00328 {
00329   ACE_TRACE ("ACE_String_Base<CHAR>::operator=");
00330 
00331   // Check for self-assignment.
00332   if (this != &s)
00333     {
00334       this->set (s.rep_, s.len_, true);
00335     }
00336 
00337   return *this;
00338 }

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.

Definition at line 317 of file String_Base.cpp.

00318 {
00319   ACE_TRACE ("ACE_String_Base<CHAR>::operator=");
00320   if (s != 0)
00321     this->set (s, true);
00322   return *this;
00323 }

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.

Definition at line 414 of file String_Base.cpp.

00415 {
00416   size_t len = ACE_OS::strlen (s);
00417   return this->len_ == len &&
00418          ACE_OS::memcmp (this->rep_,
00419                          s,
00420                          len * sizeof (CHAR)) == 0;
00421 }

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.

Definition at line 405 of file String_Base.cpp.

00406 {
00407   return this->len_ == s.len_ &&
00408          ACE_OS::memcmp (this->rep_,
00409                          s.rep_,
00410                          this->len_ * sizeof (CHAR)) == 0;
00411 }

template<class CHAR>
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.

Definition at line 108 of file String_Base.inl.

00109 {
00110   ACE_TRACE ("ACE_String_Base<CHAR>::operator >");
00111   return compare (s) > 0;
00112 }

template<class CHAR>
CHAR & ACE_String_Base< CHAR >::operator[] ( typename ACE_String_Base< CHAR >::size_type  slot  )  [inline]

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

Definition at line 77 of file String_Base.inl.

00079 {
00080   ACE_TRACE ("ACE_String_Base<CHAR>::operator[]");
00081   return this->rep_[slot];
00082 }

template<class CHAR >
const CHAR & ACE_String_Base< CHAR >::operator[] ( typename ACE_String_Base< CHAR >::size_type  slot  )  const [inline]

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

Definition at line 67 of file String_Base.inl.

00069 {
00070   ACE_TRACE ("ACE_String_Base<CHAR>::operator[]");
00071   return this->rep_[slot];
00072 }

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.

Definition at line 371 of file String_Base.cpp.

00372 {
00373   ACE_TRACE ("ACE_String_Base<CHAR>::rep");
00374 
00375   CHAR *new_string;
00376   ACE_NEW_RETURN (new_string, CHAR[this->len_ + 1], 0);
00377   ACE_OS::strsncpy (new_string, this->rep_, this->len_+1);
00378 
00379   return new_string;
00380 }

template<class CHAR>
void ACE_String_Base< CHAR >::resize ( typename ACE_String_Base< CHAR >::size_type  len,
CHAR  c = 0 
) [inline]

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.

Definition at line 265 of file String_Base.cpp.

00267 {
00268   ACE_TRACE ("ACE_String_Base<CHAR>::resize");
00269 
00270   fast_resize(len);
00271   ACE_OS::memset (this->rep_, c, this->buf_len_ * sizeof (CHAR));
00272 }

template<class CHAR>
ACE_String_Base< CHAR >::size_type ACE_String_Base< CHAR >::rfind ( CHAR  c,
typename ACE_String_Base< CHAR >::size_type  pos = npos 
) const [inline]

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.

Definition at line 451 of file String_Base.cpp.

00454 {
00455   if (pos == npos || pos > this->len_)
00456     pos = this->len_;
00457 
00458   // Do not change to prefix operator!  Proper operation of this loop
00459   // depends on postfix decrement behavior.
00460   for (size_type i = pos; i-- != 0; )
00461     if (this->rep_[i] == c)
00462       return i;
00463 
00464   return ACE_String_Base<CHAR>::npos;
00465 }

template<class CHAR>
void ACE_String_Base< CHAR >::set ( const CHAR *  s,
typename ACE_String_Base< CHAR >::size_type  len,
bool  release 
) [inline]

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.

Definition at line 129 of file String_Base.cpp.

00132 {
00133   // Case 1. Going from memory to more memory
00134   size_type new_buf_len = len + 1;
00135   if (s != 0 && len != 0 && release && this->buf_len_ < new_buf_len)
00136     {
00137       CHAR *temp = 0;
00138       ACE_ALLOCATOR (temp,
00139                      (CHAR *) this->allocator_->malloc (new_buf_len * sizeof (CHAR)));
00140 
00141       if (this->buf_len_ != 0 && this->release_)
00142         this->allocator_->free (this->rep_);
00143 
00144       this->rep_ = temp;
00145       this->buf_len_ = new_buf_len;
00146       this->release_ = true;
00147       this->len_ = len;
00148       ACE_OS::memcpy (this->rep_, s, len * sizeof (CHAR));
00149       this->rep_[len] = 0;
00150     }
00151   else // Case 2. No memory allocation is necessary.
00152     {
00153       // Free memory if necessary and figure out future ownership
00154       if (!release || s == 0 || len == 0)
00155         {
00156           if (this->buf_len_ != 0 && this->release_)
00157             {
00158               this->allocator_->free (this->rep_);
00159               this->release_ = false;
00160             }
00161         }
00162       // Populate data.
00163       if (s == 0 || len == 0)
00164         {
00165           this->buf_len_ = 0;
00166           this->len_ = 0;
00167           this->rep_ = &ACE_String_Base<CHAR>::NULL_String_;
00168           this->release_ = false;
00169         }
00170       else if (!release) // Note: No guarantee that rep_ is null terminated.
00171         {
00172           this->buf_len_ = len;
00173           this->len_ = len;
00174           this->rep_ = const_cast <CHAR *> (s);
00175           this->release_ = false;
00176         }
00177       else
00178         {
00179           ACE_OS::memcpy (this->rep_, s, len * sizeof (CHAR));
00180           this->rep_[len] = 0;
00181           this->len_ = len;
00182         }
00183     }
00184 }

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.

Definition at line 341 of file String_Base.cpp.

00342 {
00343   size_t length = 0;
00344   if (s != 0)
00345     length = ACE_OS::strlen (s);
00346 
00347   this->set (s, length, release);
00348 }

template<class CHAR>
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).

Definition at line 139 of file String_Base.inl.

00140 {
00141   ACE_TRACE ("ACE_String_Base<CHAR>::strstr");
00142   return this->find (s.rep_);
00143 }

template<class CHAR >
ACE_String_Base< CHAR > ACE_String_Base< CHAR >::substr ( typename ACE_String_Base< CHAR >::size_type  offset,
typename ACE_String_Base< CHAR >::size_type  length = npos 
) const [inline]

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

Definition at line 56 of file String_Base.inl.

00059 {
00060   ACE_TRACE ("ACE_String_Base<CHAR>::substr");
00061   return this->substring (offset, length);
00062 }

template<class CHAR >
ACE_String_Base< CHAR > ACE_String_Base< CHAR >::substring ( typename ACE_String_Base< CHAR >::size_type  offset,
typename ACE_String_Base< CHAR >::size_type  length = npos 
) const [inline]

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

Definition at line 188 of file String_Base.cpp.

00191 {
00192   ACE_String_Base<CHAR> nill;
00193   size_type count = length;
00194 
00195   // case 1. empty string
00196   if (this->len_ == 0)
00197     return nill;
00198 
00199   // case 2. start pos past our end
00200   if (offset >= this->len_)
00201     return nill;
00202   // No length == empty string.
00203   else if (length == 0)
00204     return nill;
00205   // Get all remaining bytes.
00206   else if (length == npos || count > (this->len_ - offset))
00207     count = this->len_ - offset;
00208 
00209   return ACE_String_Base<CHAR> (&this->rep_[offset], count, this->allocator_);
00210 }

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.

Definition at line 468 of file String_Base.cpp.

00469 {
00470   std::swap (this->allocator_ , str.allocator_);
00471   std::swap (this->len_       , str.len_);
00472   std::swap (this->buf_len_   , str.buf_len_);
00473   std::swap (this->rep_       , str.rep_);
00474   std::swap (this->release_   , str.release_);
00475 }

Friends And Related Function Documentation

template<class CHAR>
friend class ACE_String_Base_Const_Iterator< CHAR > [friend]

Definition at line 73 of file String_Base.h.

template<class CHAR>
friend class ACE_String_Base_Iterator< CHAR > [friend]

Definition at line 72 of file String_Base.h.

Member Data Documentation

template<class CHAR>
ACE_String_Base< CHAR >::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

Definition at line 560 of file String_Base.h.

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

Pointer to a memory allocator.

Definition at line 566 of file String_Base.h.

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.

Definition at line 577 of file String_Base.h.

template<class CHAR>
size_type ACE_String_Base< CHAR >::len_ [protected]

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

Definition at line 571 of file String_Base.h.

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

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

Definition at line 592 of file String_Base.h.

template<class CHAR>
bool ACE_String_Base< CHAR >::release_ [protected]

Flag that indicates if we own the memory

Definition at line 587 of file String_Base.h.

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

Pointer to data.

Definition at line 582 of file String_Base.h.

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Generated on Sat Nov 21 23:18:28 2009 for ACE by  doxygen 1.6.1