DwString Man Page

From 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- mimelib/doc/string.html | 717 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 717 insertions(+) create mode 100644 mimelib/doc/string.html (limited to 'mimelib/doc/string.html') diff --git a/mimelib/doc/string.html b/mimelib/doc/string.html new file mode 100644 index 000000000..80db3700c --- /dev/null +++ b/mimelib/doc/string.html @@ -0,0 +1,717 @@ + + + DwString Man Page + + +

+ NAME +

+DwString -- String class +

+ SYNOPSIS +

class DW_EXPORT DwString {
+
+public:
+
+    static const size_t npos;
+    DwString();
+    DwString(const DwString& aStr, size_t aPos=0, size_t aLen=npos);
+    DwString(const char* aBuf, size_t aLen);
+    DwString(const char* aCstr);
+    DwString(size_t aLen, char aChar);
+    DwString(char* aBuf, size_t aSize, size_t aStart, size_t aLen);
+    virtual ~DwString();
+    DwString& operator = (const DwString& aStr);
+    DwString& operator = (const char* aCstr);
+    DwString& operator = (char aChar);
+    size_t size() const;
+    size_t length() const;
+    size_t max_size() const;
+    void resize(size_t aLen, char aChar);
+    void resize(size_t aLen);
+    size_t capacity() const;
+    void reserve(size_t aSize);
+    void clear();
+    DwBool empty() const;
+    const char& operator [] (size_t aPos) const;
+    char& operator [] (size_t aPos);
+    const char& at(size_t aPos) const;
+    char& at(size_t aPos);
+    DwString& operator += (const DwString& aStr);
+    DwString& operator += (const char* aCstr);
+    DwString& operator += (char aChar);
+    DwString& append(const DwString& aStr);
+    DwString& append(const DwString& aStr, size_t aPos, size_t aLen);
+    DwString& append(const char* aBuf, size_t aLen);
+    DwString& append(const char* aCstr);
+    DwString& append(size_t aLen, char aChar);
+    DwString& assign(const DwString& aStr);
+    DwString& assign(const DwString& aStr, size_t aPos, size_t aLen);
+    DwString& assign(const char* aBuf, size_t aLen);
+    DwString& assign(const char* aCstr);
+    DwString& assign(size_t aLen, char aChar);
+    DwString& insert(size_t aPos1, const DwString& aStr);
+    DwString& insert(size_t aPos1, const DwString& aStr, size_t aPos2,
+        size_t aLen2);
+    DwString& insert(size_t aPos1, const char* aBuf, size_t aLen2);
+    DwString& insert(size_t aPos1, const char* aCstr);
+    DwString& insert(size_t aPos1, size_t aLen2, char aChar);
+    DwString& erase(size_t aPos=0, size_t aLen=npos);
+    DwString& replace(size_t aPos1, size_t aLen1, const DwString& aStr);
+    DwString& replace(size_t aPos1, size_t aLen1, const DwString& aStr,
+        size_t aPos2, size_t aLen2);
+    DwString& replace(size_t aPos1, size_t aLen1, const char* aBuf,
+        size_t aLen2);
+    DwString& replace(size_t aPos1, size_t aLen1, const char* aCstr);
+    DwString& replace(size_t aPos1, size_t aLen1, size_t aLen2, char aChar);
+    size_t copy(char* aBuf, size_t aLen, size_t aPos=0) const;
+    void swap(DwString& aStr);
+    const char* c_str() const;
+    const char* data() const;
+    size_t find(const DwString& aStr, size_t aPos=0) const;
+    size_t find(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t find(const char* aCstr, size_t aPos=0) const;
+    size_t find(char aChar, size_t aPos=0) const;
+    size_t rfind(const DwString& aStr, size_t aPos=npos) const;
+    size_t rfind(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t rfind(const char* aCstr, size_t aPos=npos) const;
+    size_t rfind(char aChar, size_t aPos=npos) const;
+    size_t find_first_of(const DwString& aStr, size_t aPos=0) const;
+    size_t find_first_of(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t find_first_of(const char* aCstr, size_t aPos=0) const;
+    size_t find_last_of(const DwString& aStr, size_t aPos=npos) const;
+    size_t find_last_of(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t find_last_of(const char* aCstr, size_t aPos=npos) const;
+    size_t find_first_not_of(const DwString& aStr, size_t aPos=0) const;
+    size_t find_first_not_of(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t find_first_not_of(const char* aCstr, size_t aPos=0) const;
+    size_t find_last_not_of(const DwString& aStr, size_t aPos=npos) const;
+    size_t find_last_not_of(const char* aBuf, size_t aPos, size_t aLen) const;
+    size_t find_last_not_of(const char* aCstr, size_t aPos=npos) const;
+    DwString substr(size_t aPos=0, size_t aLen=npos) const;
+    int compare(const DwString& aStr) const;
+    int compare(size_t aPos1, size_t aLen1, const DwString& aStr) const;
+    int compare(size_t aPos1, size_t aLen1, const DwString& aStr,
+        size_t aPos2, size_t aLen2) const;
+    int compare(const char* aCstr) const;
+    int compare(size_t aPos1, size_t aLen1, const char* aBuf,
+        size_t aLen2=npos) const;
+    virtual const char* ClassName() const;
+    int ObjectId() const;
+    void ConvertToLowerCase();
+    void ConvertToUpperCase();
+    void Trim();
+    void WriteTo(ostream& aStrm) const;
+    int RefCount() const;
+    void TakeBuffer(char* aBuf, size_t aSize, size_t aStart, size_t aLen);
+    void ReleaseBuffer(char** aBuf, size_t* aSize, size_t* aStart, size_t* aLen);
+    void CopyTo(DwString* aStr) const;
+
+protected:
+
+    DwStringRep* mRep;
+    size_t  mStart;
+    size_t  mLength;
+    void _copy();
+    void _replace(size_t aPos1, size_t aLen1, const char* aBuf, size_t aLen2);
+    void _replace(size_t aPos1, size_t aLen1, size_t aLen2, char aChar);
+    friend void mem_free(char*);
+
+public:
+
+    virtual void PrintDebugInfo(ostream& aStrm) const;
+    virtual void CheckInvariants() const;
+};
+

+ DESCRIPTION +

+DwString is the workhorse of the MIME++ library. Creating, +parsing, or otherwise manipulating MIME messages is basically a matter of +manipulating strings. DwString provides all the basic +functionality required of a string object, including copying, comparing, +concatenating, and so on. +

+DwString is similar to the string class that +is part of the proposed ANSI standard C++ library. Some of the member functions +present in the ANSI string are not present in +DwString: mostly these are the functions that deal with +iterators. DwString also includes some member functions and +class utility functions that are not a part of the ANSI +string class. These non-ANSI functions are easy to distinguish: +they all begin with upper-case letters, and all ANSI functions begin with +lower-case letters. The library classes themselves use only the ANSI +string functions. At some point in the future, MIME++ will +probably allow the option to substitute the ANSI string class +for DwString. +

+DwString makes extensive use of copy-on-write, even when +extracting substrings. It is this feature that distiguishes +DwString from most other string classes. +DwString also handles binary data, which can contain embedded +NUL characters. +

+ Public Member Functions +

+ DwString()
+DwString(const DwString& aStr, size_t aPos=0, size_t aLen=npos)
+DwString(const char* aBuf, size_t aLen)
+DwString(const char* aCstr)
+DwString(size_t aLen, char aChar)
+DwString(char* aBuf, size_t aSize, size_t aStart, size_t aLen) +

+The first constructor is the default constructor, which sets the +DwString object's contents to be empty. +

+The second constructor is the copy constructor, which copies at most +aLen characters beginning at position +aPos from aStr to the new +DwString object. It will not copy more characters than what +are available in aStr. aPos must be less +than or equal to aStr.size(). +

+The third constructor copies aLen characters from the buffer +aBuf into the new DwString object. +aBuf need not be NUL-terminated and may contain NUL characters. +

+The fourth constructor copies the contents of the NUL-terminated string +aCstr into the new DwString object. +

+The fifth constructor sets the contents of the new +DwString object to be the character aChar +repeated aLen times. +

+The sixth constructor is an advanced constructor that sets the contents +of the new DwString object to the aLen characters +starting at offset aStart in the buffer +aBuf. aSize is the allocated size of +aBuf. This constructor is provided for efficiency in setting +a new DwString's contents from a large buffer. It is efficient +because no copying takes place. Instead, aBuf becomes the +buffer used internally by the DwString object, which takes +responsibility for deleting the buffer. Because DwString +will free the buffer using delete [], the buffer should have +been allocated using new. See also: TakeBuffer(), and +ReleaseBuffer(). +

+ DwString& operator = (const +DwString& aStr)
+DwString& operator = (const char* aCstr)
+DwString& operator = (char aChar) +

+Assigns the contents of the operand to this string. aCstr +must point to a NUL-terminated array of characters (a C string). Returns +*this. +

+ size_t size() const +

+Returns the number of characters in this string's contents. This member function +is identical to length() +

+ size_t length() const +

+Returns the number of characters in this string's contents. This member function +is identical to size() +

+ size_t max_size() const + +

+Returns the maximum length that this string can ever attain. +

+ void resize(size_t aLen, char +aChar)
+void resize(size_t aLen) +

+Changes the length of this string. If the string shortened, the final characters +are truncated. If the string is expanded, the added characters will be NULs +or the character specified by aChar. +

+ size_t capacity() const + +

+Returns the size of the internal buffer used for this string, which will +always be greater than or equal to the length of the string. +

+ void reserve(size_t aSize) + +

+If aSize is greater than the current capacity of this string, +this member function will increase the capacity to be at least +aSize. +

+ void clear() +

+Sets this string's contents to be empty. +

+ DwBool empty() const +

+Returns a true value if and only if the contents of this string are empty. +

+ const char& operator [] +(size_t aPos) const
+char& operator [] (size_t aPos) +

+Returns DwString::at(aPos) const or +DwString::at(aPos). Note that the non-const version always +assumes that the contents will be modified and therefore always copies a +shared internal buffer before it returns. +

+ const char& at(size_t aPos) const +
+char& at(size_t aPos) +

+Returns the character at position aPos in the string's contents. +The non-const version returns an lvalue that may be assigned to. Note that +the non-const version always assumes that the contents will be modified and +therefore always copies a shared internal buffer before it returns. +

+ DwString& operator += +(const DwString& aStr)
+DwString& operator += (const char* aCstr)
+DwString& operator += (char aChar) +

+Appends the contents of the operand to this string. aCstr +must point to a NUL-terminated array of characters (a C string). Returns +*this. +

+ DwString& append(const +DwString& aStr)
+DwString& append(const DwString& aStr, size_t aPos, size_t aLen) +
+DwString& append(const char* aBuf, size_t aLen)
+DwString& append(const char* aCstr)
+DwString& append(size_t aLen, char aChar) +

+Appends characters to (the end of) this string. Returns +*this. +

+The first version appends all of the characters from +aStr. +

+The second version appends at most aLen characters from +aStr beginning at position aPos. +aPos must be less than or equal to +aStr.size(). The function will not append more characters +than what are available in aStr. +

+The third version appends aLen characters from +aBuf, which is not assumed to be NUL-terminated and can contain +embedded NULs. +

+The fourth version appends characters from the NUL-terminated string +aCstr. +

+The fifth version appends aChar repeated +aLen times. +

+ DwString& assign(const +DwString& aStr)
+DwString& assign(const DwString& aStr, size_t aPos, size_t aLen) +
+DwString& assign(const char* aBuf, size_t aLen)
+DwString& assign(const char* aCstr)
+DwString& assign(size_t aLen, char aChar) +

+Assigns characters to this string. Returns *this. +

+The first version assigns all of the characters from +aStr. +

+The second version assigns at most aLen characters from +aStr beginning at position aPos. +aPos must be less than or equal to +aStr.size(). The function will not assign more characters +than what are available in aStr. +

+The third version assigns aLen characters from +aBuf, which is not assumed to be NUL-terminated and can contain +embedded NULs. +

+The fourth version assigns characters from the NUL-terminated string +aCstr. +

+The fifth version assigns aChar repeated +aLen times. +

+ DwString& insert(size_t aPos1, +const DwString& aStr)
+DwString& insert(size_t aPos1, const DwString& aStr, size_t aPos2, +size_t aLen2)
+DwString& insert(size_t aPos1, const char* aBuf, size_t aLen2)
+DwString& insert(size_t aPos1, const char* aCstr)
+DwString& insert(size_t aPos1, size_t aLen2, char aChar) +

+Inserts characters into this string beginning at position +aPos1. Returns *this. +

+The first version inserts all of the characters from +aStr. +

+The second version inserts at most aLen2 characters from +aStr beginning at position aPos2. +aPos1 must be less than or equal to +aStr.size(). The function will not assign more characters +than what are available in aStr. +

+The third version inserts aLen2 characters from +aBuf, which is not assumed to be NUL-terminated and can contain +embedded NULs. +

+The fourth version inserts characters from the NUL-terminated string +aCstr. +

+The fifth version inserts aChar repeated +aLen2 times. +

+ DwString& erase(size_t aPos=0, +size_t aLen=npos) +

+Erases (removes) at most aLen characters beginning at position +aPos from this string. The function will not erase more +characters than what are available. Returns *this. +

+ DwString& replace(size_t +aPos1, size_t aLen1, const DwString& aStr)
+DwString& replace(size_t aPos1, size_t aLen1, const DwString& aStr, +size_t aPos2, size_t aLen2)
+DwString& replace(size_t aPos1, size_t aLen1, const char* aBuf, size_t +aLen2)
+DwString& replace(size_t aPos1, size_t aLen1, const char* aCstr)
+DwString& replace(size_t aPos1, size_t aLen1, size_t aLen2, char aChar) + +

+Removes aLen1 characters beginning at position +aPos1 and inserts other characters. Returns +*this. +

+The first version inserts all of the characters from +aStr. +

+The third version inserts aLen2 characters from +aBuf, which is not assumed to be NUL-terminated and can contain +embedded NULs. +

+The fourth version inserts characters from the NUL-terminated string +aCstr. +

+The fifth version inserts aChar repeated +aLen2 times. +

+ size_t copy(char* aBuf, size_t +aLen, size_t aPos=0) const +

+Copies at most aLen characters beginning at position +aPos from this string to the buffer pointed to by +aBuf. Returns the number of characters copied. +

+ void swap(DwString& aStr) + +

+Swaps the contents of this string and aStr. +

+ const char* c_str() const + +

+ const char* data() const + +

+These member functions permit access to the internal buffer used by the +DwString object. c_str() returns a NUL-terminated +string suitable for use in C library functions. data() returns +a pointer to the internal buffer, which may not be NUL-terminated. +

+c_str() may copy the internal buffer in order to place the +terminating NUL. This is not a violation of the const declaration: it is +a logical const, not a bit-representation const. It could have the side effect +of invalidating a pointer previously returned by c_str() +or data(). +

+The characters in the returned string should not be modified, and should +be considered invalid after any call to a non-const member function or another +call to c_str(). +

+ size_t find(const DwString& +aStr, size_t aPos=0) const
+size_t find(const char* aBuf, size_t aPos, size_t aLen) const
+size_t find(const char* aCstr, size_t aPos=0) const
+size_t find(char aChar, size_t aPos=0) const +

+Performs a forward search for a sequence of characters in the +DwString object. The return value is the position of the +sequence in the string if found, or DwString::npos if not +found. +

+The first version searches beginning at position aPos for +the sequence of characters in aStr. +

+The second version searches beginning at position aPos for +the sequence of aLen characters in aBuf, +which need not be NUL-terminated and can contain embedded NULs. +

+The third version searches beginning at position aPos for +the sequence of characters in the NUL-terminated string +aCstr. +

+The fourth version searches beginning at position aPos for +the character aChar. +

+ size_t rfind(const DwString& +aStr, size_t aPos=npos) const
+size_t rfind(const char* aBuf, size_t aPos, size_t aLen) const
+size_t rfind(const char* aCstr, size_t aPos=npos) const
+size_t rfind(char aChar, size_t aPos=npos) const +

+Performs a reverse search for a sequence of characters in the +DwString object. The return value is the position of the +sequence in the string if found, or DwString::npos if not +found. +

+The first version searches beginning at position aPos for +the sequence of characters in aStr. +

+The second version searches beginning at position aPos for +the sequence of aLen characters in aBuf, +which need not be NUL-terminated and can contain embedded NULs. +

+The third version searches beginning at position aPos for +the sequence of characters in the NUL-terminated string +aCstr. +

+The fourth version searches beginning at position aPos for +the character aChar. +

+ size_t find_first_of(const +DwString& aStr, size_t aPos=0) const
+size_t find_first_of(const char* aBuf, size_t aPos, size_t aLen) const
+size_t find_first_of(const char* aCstr, size_t aPos=0) const +

+Performs a forward search beginning at position aPos for +the first occurrence of any character from a specified set of characters. +The return value is the position of the character if found, or +DwString::npos if not found. +

+The first version searches for any character in the string +aStr. +

+The second version searches for any of the aLen characters +in aBuf. +

+The third version searches for any character in the NUL-terminated string +aCstr. +

+ size_t find_last_of(const +DwString& aStr, size_t aPos=npos) const
+size_t find_last_of(const char* aBuf, size_t aPos, size_t aLen) const
+size_t find_last_of(const char* aCstr, size_t aPos=npos) const +

+Performs a reverse search beginning at position aPos for +the first occurrence of any character from a specified set of characters. +If aPos is greater than or equal to the number of characters +in the string, then the search starts at the end of the string. The return +value is the position of the character if found, or +DwString::npos if not found. +

+The first version searches for any character in the string +aStr. +

+The second version searches for any of the aLen characters +in aBuf. +

+The third version searches for any character in the NUL-terminated string +aCstr. +

+ size_t +find_first_not_of(const DwString& aStr, +size_t aPos=0) const
+size_t find_first_not_of(const char* aBuf, size_t aPos, size_t aLen) const +
+size_t find_first_not_of(const char* aCstr, size_t aPos=0) const +

+Performs a forward search beginning at position aPos for +the first occurrence of any character not in a specified set of +characters. The return value is the position of the character if found, or +DwString::npos if not found. +

+The first version searches for any character not in the string +aStr. +

+The second version searches for any character not among the +aLen characters in aBuf. +

+The third version searches for any character not in the NUL-terminated string +aCstr. +

+ size_t +find_last_not_of(const DwString& aStr, +size_t aPos=npos) const
+size_t find_last_not_of(const char* aBuf, size_t aPos, size_t aLen) const +
+size_t find_last_not_of(const char* aCstr, size_t aPos=npos) const + +

+Performs a reverse search beginning at position aPos for +the first occurrence of any character not in a specified set of +characters. If aPos is greater than or equal to the number +of characters in the string, then the search starts at the end of the string. +The return value is the position of the character if found, or +DwString::npos if not found. +

+The first version searches for any character not in the string +aStr. +

+The second version searches for any character not among the +aLen characters in aBuf. +

+The third version searches for any character not in the NUL-terminated string +aCstr. +

+ DwString substr(size_t aPos=0, +size_t aLen=npos) const +

+Returns a string that contains at most aLen characters from +the DwString object beginning at position +aPos. The returned substring will not contain more characters +than what are available in the superstring DwString object. +

+ int compare(const DwString& +aStr) const
+int compare(size_t aPos1, size_t aLen1, const DwString& aStr) const
+int compare(size_t aPos1, size_t aLen1, const DwString& aStr, size_t +aPos2, size_t aLen2) const
+int compare(const char* aCstr) const
+int compare(size_t aPos1, size_t aLen1, const char* aBuf, size_t aLen2=npos) +const +

+These member functions compare a sequence of characters to this +DwString object, or a segment of this +DwString object. They return -1, 0, or 1, depending on whether +this DwString object is less than, equal to, or greater than +the compared sequence of characters, respectively. +

+The first version compares aStr to this string. +

+The second version compares aStr to the segment of this string +of length aLen beginning at position +aPos. +

+The third version compares the {tt aLen2} characters beginning at position +aPos2 in aStr with the +aLen1 characters beginning at position +aPos1 in this DwString object. +

+The fourth version compares the NUL-terminated string +aCstr to this DwString. +

+The fifth version compares the aLen2 characters in +aBuf with this DwString. +

+ virtual const char* +ClassName() const +

+This virtual function returns the name of the class as a NUL-terminated char +string. +

+ int ObjectId() const + +

+Returns the unique object id for this DwString. +

+ void +ConvertToLowerCase()
+void ConvertToUpperCase() +

+Converts this DwString object's characters to all lower case +or all upper case. +

+ void Trim() +

+Removes all white space from the beginning and the end of this +DwString object. White space characters include ASCII HT, +LF, and SPACE. +

+ void WriteTo(ostream& aStrm) +const +

+Writes the contents of this DwString object to the stream +aStrm. +

+ int RefCount() const + +

+This advanced member function returns the number of references to +the internal buffer used by the DwString object. +

+ void TakeBuffer(char* aBuf, +size_t aSize, size_t aStart, size_t aLen) +

+This advanced member function sets the contents of the +DwString object to the aLen characters starting +at offset aStart in the buffer aBuf. +aSize is the allocated size of aBuf. This +member function is provided for efficiency in setting a +DwString's contents from a large buffer. It is efficient +because no copying takes place. Instead, aBuf becomes the +buffer used internally by the DwString object, which takes +responsibility for deleting the buffer. Because DwString will free the buffer +using delete [], the buffer should have been allocated using +new. See also: ReleaseBuffer(). +

+ void ReleaseBuffer(char** +aBuf, size_t* aSize, size_t* aStart, size_t* aLen) +

+This advanced member function is the symmetric opposite of +TakeBuffer(), to the extent that such an opposite is possible. +It provides a way to ``export'' the buffer used internally by the +DwString object. Note, however, that because of the +copy-on-modify feature of DwString, the +DwString object may not have sole ownership of its internal +buffer. When that is case, ReleaseBuffer() will return a +copy of the buffer. You can check to see if the internal buffer is shared +by calling RefCount(). On return from this member function, +the DwString object will have valid, but empty, contents. +It is recommended that you use this function only on rare occasions where +you need to export efficiently a large buffer. +

+ void CopyTo(DwString* aStr) const + +

+This advanced member function copies this DwString +object to aStr. This member function is different from the +assignment operator, because it physically copies the buffer instead of just +duplicating a reference to it. +

+ virtual void +PrintDebugInfo(ostream& aStrm) const + +

+Prints debugging information about the object to aStrm. +

+This member function is available only in the debug version of the library. +

+ virtual void +CheckInvariants() const +

+Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +

+This member function is available only in the debug version of the library. +

+ Public Data Members +

+ static const size_t npos + +

+npos is assigned the value (size_t)-1. + -- cgit v1.2.1