gecko/xpcom/string/public/nsTString.h

719 lines
25 KiB
C
Raw Normal View History

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Mozilla.
*
* The Initial Developer of the Original Code is IBM Corporation.
* Portions created by IBM Corporation are Copyright (C) 2003
* IBM Corporation. All Rights Reserved.
*
* Contributor(s):
* Rick Gessner <rickg@netscape.com> (original author)
* Scott Collins <scc@mozilla.org>
* Darin Fisher <darin@meer.net>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
/**
* This is the canonical null-terminated string class. All subclasses
* promise null-terminated storage. Instances of this class allocate
* strings on the heap.
*
* NAMES:
* nsString for wide characters
* nsCString for narrow characters
*
* This class is also known as nsAFlat[C]String, where "flat" is used
* to denote a null-terminated string.
*/
class nsTString_CharT : public nsTSubstring_CharT
{
public:
typedef nsTString_CharT self_type;
public:
/**
* constructors
*/
nsTString_CharT()
: substring_type() {}
explicit
nsTString_CharT( char_type c )
: substring_type()
{
Assign(c);
}
explicit
nsTString_CharT( const char_type* data, size_type length = size_type(-1) )
: substring_type()
{
Assign(data, length);
}
nsTString_CharT( const self_type& str )
: substring_type()
{
Assign(str);
}
nsTString_CharT( const substring_tuple_type& tuple )
: substring_type()
{
Assign(tuple);
}
explicit
nsTString_CharT( const substring_type& readable )
: substring_type()
{
Assign(readable);
}
// |operator=| does not inherit, so we must define our own
self_type& operator=( char_type c ) { Assign(c); return *this; }
self_type& operator=( const char_type* data ) { Assign(data); return *this; }
self_type& operator=( const self_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_tuple_type& tuple ) { Assign(tuple); return *this; }
/**
* returns the null-terminated string
*/
const char_type* get() const
{
return mData;
}
/**
* returns character at specified index.
*
* NOTE: unlike nsTSubstring::CharAt, this function allows you to index
* the null terminator character.
*/
char_type CharAt( index_type i ) const
{
NS_ASSERTION(i <= mLength, "index exceeds allowable range");
return mData[i];
}
char_type operator[]( index_type i ) const
{
return CharAt(i);
}
#if MOZ_STRING_WITH_OBSOLETE_API
/**
* Search for the given substring within this string.
*
* @param aString is substring to be sought in this
* @param aIgnoreCase selects case sensitivity
* @param aOffset tells us where in this string to start searching
* @param aCount tells us how far from the offset we are to search. Use
* -1 to search the whole string.
* @return offset in string, or kNotFound
*/
NS_COM PRInt32 Find( const nsCString& aString, PRBool aIgnoreCase=PR_FALSE, PRInt32 aOffset=0, PRInt32 aCount=-1 ) const;
NS_COM PRInt32 Find( const char* aString, PRBool aIgnoreCase=PR_FALSE, PRInt32 aOffset=0, PRInt32 aCount=-1 ) const;
#ifdef CharT_is_PRUnichar
NS_COM PRInt32 Find( const nsAFlatString& aString, PRInt32 aOffset=0, PRInt32 aCount=-1 ) const;
NS_COM PRInt32 Find( const PRUnichar* aString, PRInt32 aOffset=0, PRInt32 aCount=-1 ) const;
#endif
/**
* This methods scans the string backwards, looking for the given string
*
* @param aString is substring to be sought in this
* @param aIgnoreCase tells us whether or not to do caseless compare
* @param aOffset tells us where in this string to start searching.
* Use -1 to search from the end of the string.
* @param aCount tells us how many iterations to make starting at the
* given offset.
* @return offset in string, or kNotFound
*/
NS_COM PRInt32 RFind( const nsCString& aString, PRBool aIgnoreCase=PR_FALSE, PRInt32 aOffset=-1, PRInt32 aCount=-1 ) const;
NS_COM PRInt32 RFind( const char* aCString, PRBool aIgnoreCase=PR_FALSE, PRInt32 aOffset=-1, PRInt32 aCount=-1 ) const;
#ifdef CharT_is_PRUnichar
NS_COM PRInt32 RFind( const nsAFlatString& aString, PRInt32 aOffset=-1, PRInt32 aCount=-1 ) const;
NS_COM PRInt32 RFind( const PRUnichar* aString, PRInt32 aOffset=-1, PRInt32 aCount=-1 ) const;
#endif
/**
* Search for given char within this string
*
* @param aChar is the character to search for
* @param aOffset tells us where in this string to start searching
* @param aCount tells us how far from the offset we are to search.
* Use -1 to search the whole string.
* @return offset in string, or kNotFound
*/
// PRInt32 FindChar( PRUnichar aChar, PRInt32 aOffset=0, PRInt32 aCount=-1 ) const;
NS_COM PRInt32 RFindChar( PRUnichar aChar, PRInt32 aOffset=-1, PRInt32 aCount=-1 ) const;
/**
* This method searches this string for the first character found in
* the given string.
*
* @param aString contains set of chars to be found
* @param aOffset tells us where in this string to start searching
* (counting from left)
* @return offset in string, or kNotFound
*/
NS_COM PRInt32 FindCharInSet( const char* aString, PRInt32 aOffset=0 ) const;
PRInt32 FindCharInSet( const self_type& aString, PRInt32 aOffset=0 ) const
{
return FindCharInSet(aString.get(), aOffset);
}
#ifdef CharT_is_PRUnichar
NS_COM PRInt32 FindCharInSet( const PRUnichar* aString, PRInt32 aOffset=0 ) const;
#endif
/**
* This method searches this string for the last character found in
* the given string.
*
* @param aString contains set of chars to be found
* @param aOffset tells us where in this string to start searching
* (counting from left)
* @return offset in string, or kNotFound
*/
NS_COM PRInt32 RFindCharInSet( const char_type* aString, PRInt32 aOffset=-1 ) const;
PRInt32 RFindCharInSet( const self_type& aString, PRInt32 aOffset=-1 ) const
{
return RFindCharInSet(aString.get(), aOffset);
}
/**
* Compares a given string to this string.
*
* @param aString is the string to be compared
* @param aIgnoreCase tells us how to treat case
* @param aCount tells us how many chars to compare
* @return -1,0,1
*/
#ifdef CharT_is_char
NS_COM PRInt32 Compare( const char* aString, PRBool aIgnoreCase=PR_FALSE, PRInt32 aCount=-1 ) const;
#endif
/**
* Equality check between given string and this string.
*
* @param aString is the string to check
* @param aIgnoreCase tells us how to treat case
* @param aCount tells us how many chars to compare
* @return boolean
*/
#ifdef CharT_is_char
PRBool EqualsIgnoreCase( const char* aString, PRInt32 aCount=-1 ) const {
return Compare(aString, PR_TRUE, aCount) == 0;
}
#else
NS_COM PRBool EqualsIgnoreCase( const char* aString, PRInt32 aCount=-1 ) const;
#endif // !CharT_is_PRUnichar
/**
* Perform string to float conversion.
*
* @param aErrorCode will contain error if one occurs
* @return float rep of string value
*/
NS_COM float ToFloat( PRInt32* aErrorCode ) const;
/**
* Perform string to int conversion.
* @param aErrorCode will contain error if one occurs
* @param aRadix tells us which radix to assume; kAutoDetect tells us to determine the radix for you.
* @return int rep of string value, and possible (out) error code
*/
NS_COM PRInt32 ToInteger( PRInt32* aErrorCode, PRUint32 aRadix=kRadix10 ) const;
PRInt32 ToInteger( nsresult* aErrorCode, PRUint32 aRadix=kRadix10 ) const {
return ToInteger(reinterpret_cast<PRInt32*>(aErrorCode), aRadix);
}
/**
* |Left|, |Mid|, and |Right| are annoying signatures that seem better almost
* any _other_ way than they are now. Consider these alternatives
*
* aWritable = aReadable.Left(17); // ...a member function that returns a |Substring|
* aWritable = Left(aReadable, 17); // ...a global function that returns a |Substring|
* Left(aReadable, 17, aWritable); // ...a global function that does the assignment
*
* as opposed to the current signature
*
* aReadable.Left(aWritable, 17); // ...a member function that does the assignment
*
* or maybe just stamping them out in favor of |Substring|, they are just duplicate functionality
*
* aWritable = Substring(aReadable, 0, 17);
*/
NS_COM size_type Mid( self_type& aResult, PRUint32 aStartPos, PRUint32 aCount ) const;
size_type Left( self_type& aResult, size_type aCount ) const
{
return Mid(aResult, 0, aCount);
}
size_type Right( self_type& aResult, size_type aCount ) const
{
aCount = NS_MIN(mLength, aCount);
return Mid(aResult, mLength - aCount, aCount);
}
/**
* Set a char inside this string at given index
*
* @param aChar is the char you want to write into this string
* @param anIndex is the ofs where you want to write the given char
* @return TRUE if successful
*/
NS_COM PRBool SetCharAt( PRUnichar aChar, PRUint32 aIndex );
/**
* These methods are used to remove all occurrences of the
* characters found in aSet from this string.
*
* @param aSet -- characters to be cut from this
*/
NS_COM void StripChars( const char* aSet );
/**
* This method strips whitespace throughout the string.
*/
NS_COM void StripWhitespace();
/**
* swaps occurence of 1 string for another
*/
NS_COM void ReplaceChar( char_type aOldChar, char_type aNewChar );
NS_COM void ReplaceChar( const char* aSet, char_type aNewChar );
NS_COM void ReplaceSubstring( const self_type& aTarget, const self_type& aNewValue);
NS_COM void ReplaceSubstring( const char_type* aTarget, const char_type* aNewValue);
/**
* This method trims characters found in aTrimSet from
* either end of the underlying string.
*
* @param aSet -- contains chars to be trimmed from both ends
* @param aEliminateLeading
* @param aEliminateTrailing
* @param aIgnoreQuotes -- if true, causes surrounding quotes to be ignored
* @return this
*/
NS_COM void Trim( const char* aSet, PRBool aEliminateLeading=PR_TRUE, PRBool aEliminateTrailing=PR_TRUE, PRBool aIgnoreQuotes=PR_FALSE );
/**
* This method strips whitespace from string.
* You can control whether whitespace is yanked from start and end of
* string as well.
*
* @param aEliminateLeading controls stripping of leading ws
* @param aEliminateTrailing controls stripping of trailing ws
*/
NS_COM void CompressWhitespace( PRBool aEliminateLeading=PR_TRUE, PRBool aEliminateTrailing=PR_TRUE );
/**
* assign/append/insert with _LOSSY_ conversion
*/
NS_COM void AssignWithConversion( const nsTAString_IncompatibleCharT& aString );
NS_COM void AssignWithConversion( const incompatible_char_type* aData, PRInt32 aLength=-1 );
NS_COM void AppendWithConversion( const nsTAString_IncompatibleCharT& aString );
NS_COM void AppendWithConversion( const incompatible_char_type* aData, PRInt32 aLength=-1 );
using nsTSubstring_CharT::AppendInt;
/**
* Append the given integer to this string
* @param aInteger The integer to append
* @param aRadix The radix to use; can be 8, 10 or 16.
* @deprecated Use AppendInt( PRInt32 aInteger ) or
* AppendInt( PRUint32 aInteger, PRInt32 aRadix = 10 )
*/
NS_COM void AppendInt( PRInt32 aInteger, PRInt32 aRadix ); //radix=8,10 or 16
/**
* Append the given 64-bit integer to this string.
* @param aInteger The integer to append
* @param aRadix The radix to use; can be 8, 10 or 16.
* @deprecated Use AppendInt( PRInt64 aInteger ) or
* AppendInt( PRUint64 aInteger, PRInt32 aRadix = 10 )
*/
NS_COM void AppendInt( PRInt64 aInteger, PRInt32 aRadix );
/**
* Append the given float to this string
*/
NS_COM void AppendFloat( float aFloat );
NS_COM void AppendFloat( double aFloat );
#endif // !MOZ_STRING_WITH_OBSOLETE_API
protected:
explicit
nsTString_CharT( PRUint32 flags )
: substring_type(flags) {}
// allow subclasses to initialize fields directly
nsTString_CharT( char_type* data, size_type length, PRUint32 flags )
: substring_type(data, length, flags) {}
};
class nsTFixedString_CharT : public nsTString_CharT
{
public:
typedef nsTFixedString_CharT self_type;
typedef nsTFixedString_CharT fixed_string_type;
public:
/**
* @param data
* fixed-size buffer to be used by the string (the contents of
* this buffer may be modified by the string)
* @param storageSize
* the size of the fixed buffer
* @param length (optional)
* the length of the string already contained in the buffer
*/
NS_COM nsTFixedString_CharT( char_type* data, size_type storageSize );
NS_COM nsTFixedString_CharT( char_type* data, size_type storageSize, size_type length );
// |operator=| does not inherit, so we must define our own
self_type& operator=( char_type c ) { Assign(c); return *this; }
self_type& operator=( const char_type* data ) { Assign(data); return *this; }
self_type& operator=( const substring_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_tuple_type& tuple ) { Assign(tuple); return *this; }
protected:
friend class nsTSubstring_CharT;
size_type mFixedCapacity;
char_type *mFixedBuf;
};
/**
* nsTAutoString_CharT
*
* Subclass of nsTString_CharT that adds support for stack-based string
* allocation. It is normally not a good idea to use this class on the
* heap, because it will allocate space which may be wasted if the string
* it contains is significantly smaller or any larger than 64 characters.
*
* NAMES:
* nsAutoString for wide characters
* nsCAutoString for narrow characters
*/
class NS_STACK_CLASS nsTAutoString_CharT : public nsTFixedString_CharT
{
public:
typedef nsTAutoString_CharT self_type;
public:
/**
* constructors
*/
nsTAutoString_CharT()
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{}
explicit
nsTAutoString_CharT( char_type c )
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{
Assign(c);
}
explicit
nsTAutoString_CharT( const char_type* data, size_type length = size_type(-1) )
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{
Assign(data, length);
}
nsTAutoString_CharT( const self_type& str )
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{
Assign(str);
}
explicit
nsTAutoString_CharT( const substring_type& str )
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{
Assign(str);
}
nsTAutoString_CharT( const substring_tuple_type& tuple )
: fixed_string_type(mStorage, kDefaultStorageSize, 0)
{
Assign(tuple);
}
// |operator=| does not inherit, so we must define our own
self_type& operator=( char_type c ) { Assign(c); return *this; }
self_type& operator=( const char_type* data ) { Assign(data); return *this; }
self_type& operator=( const self_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_tuple_type& tuple ) { Assign(tuple); return *this; }
enum { kDefaultStorageSize = 64 };
private:
char_type mStorage[kDefaultStorageSize];
};
//
// nsAutoString stores pointers into itself which are invalidated when an
// nsTArray is resized, so nsTArray must not be instantiated with nsAutoString
// elements!
//
template<class E> class nsTArrayElementTraits;
template<>
class nsTArrayElementTraits<nsTAutoString_CharT> {
public:
template<class A> struct Dont_Instantiate_nsTArray_of;
template<class A> struct Instead_Use_nsTArray_of;
static Dont_Instantiate_nsTArray_of<nsTAutoString_CharT> *
Construct(Instead_Use_nsTArray_of<nsTString_CharT> *e) {
return 0;
}
template<class A>
static Dont_Instantiate_nsTArray_of<nsTAutoString_CharT> *
Construct(Instead_Use_nsTArray_of<nsTString_CharT> *e,
const A &arg) {
return 0;
}
static Dont_Instantiate_nsTArray_of<nsTAutoString_CharT> *
Destruct(Instead_Use_nsTArray_of<nsTString_CharT> *e) {
return 0;
}
};
/**
* nsTXPIDLString extends nsTString such that:
*
* (1) mData can be null
* (2) objects of this type can be automatically cast to |const CharT*|
* (3) getter_Copies method is supported to adopt data allocated with
* NS_Alloc, such as "out string" parameters in XPIDL.
*
* NAMES:
* nsXPIDLString for wide characters
* nsXPIDLCString for narrow characters
*/
class nsTXPIDLString_CharT : public nsTString_CharT
{
public:
typedef nsTXPIDLString_CharT self_type;
public:
nsTXPIDLString_CharT()
: string_type(char_traits::sEmptyBuffer, 0, F_TERMINATED | F_VOIDED) {}
// copy-constructor required to avoid default
nsTXPIDLString_CharT( const self_type& str )
: string_type(char_traits::sEmptyBuffer, 0, F_TERMINATED | F_VOIDED)
{
Assign(str);
}
// return nsnull if we are voided
const char_type* get() const
{
return (mFlags & F_VOIDED) ? nsnull : mData;
}
// this case operator is the reason why this class cannot just be a
// typedef for nsTString
operator const char_type*() const
{
return get();
}
// need this to diambiguous operator[int]
char_type operator[]( PRInt32 i ) const
{
return CharAt(index_type(i));
}
// |operator=| does not inherit, so we must define our own
self_type& operator=( char_type c ) { Assign(c); return *this; }
self_type& operator=( const char_type* data ) { Assign(data); return *this; }
self_type& operator=( const self_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_tuple_type& tuple ) { Assign(tuple); return *this; }
};
/**
* getter_Copies support for use with raw string out params:
*
* NS_IMETHOD GetBlah(char**);
*
* void some_function()
* {
* nsXPIDLCString blah;
* GetBlah(getter_Copies(blah));
* // ...
* }
*/
class NS_STACK_CLASS nsTGetterCopies_CharT
{
public:
typedef CharT char_type;
nsTGetterCopies_CharT(nsTSubstring_CharT& str)
: mString(str), mData(nsnull) {}
~nsTGetterCopies_CharT()
{
mString.Adopt(mData); // OK if mData is null
}
operator char_type**()
{
return &mData;
}
private:
nsTSubstring_CharT& mString;
char_type* mData;
};
inline
nsTGetterCopies_CharT
getter_Copies( nsTSubstring_CharT& aString )
{
return nsTGetterCopies_CharT(aString);
}
/**
* nsTAdoptingString extends nsTXPIDLString such that:
*
* (1) Adopt given string on construction or assignment, i.e. take
* the value of what's given, and make what's given forget its
* value. Note that this class violates constness in a few
* places. Be careful!
*/
class nsTAdoptingString_CharT : public nsTXPIDLString_CharT
{
public:
typedef nsTAdoptingString_CharT self_type;
public:
explicit nsTAdoptingString_CharT() {}
explicit nsTAdoptingString_CharT(char_type* str, size_type length = size_type(-1))
{
Adopt(str, length);
}
// copy-constructor required to adopt on copy. Note that this
// will violate the constness of |str| in the operator=()
// call. |str| will be truncated as a side-effect of this
// constructor.
nsTAdoptingString_CharT( const self_type& str )
{
*this = str;
}
// |operator=| does not inherit, so we must define our own
self_type& operator=( const substring_type& str ) { Assign(str); return *this; }
self_type& operator=( const substring_tuple_type& tuple ) { Assign(tuple); return *this; }
// Adopt(), if possible, when assigning to a self_type&. Note
// that this violates the constness of str, str is always
// truncated when this operator is called.
NS_COM self_type& operator=( const self_type& str );
private:
// NOT TO BE IMPLEMENTED.
self_type& operator=( const char_type* data );
self_type& operator=( char_type* data );
};