• Main Page
  • Modules
  • Classes
  • Files
  • File List
  • File Members

StringP.h

Go to the documentation of this file.
00001 #ifndef FDO_STRINGP_H
00002 #define FDO_STRINGP_H       1
00003 
00004 //
00005 // Copyright (C) 2004-2006  Autodesk, Inc.
00006 // 
00007 // This library is free software; you can redistribute it and/or
00008 // modify it under the terms of version 2.1 of the GNU Lesser
00009 // General Public License as published by the Free Software Foundation.
00010 // 
00011 // This library is distributed in the hope that it will be useful,
00012 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014 // Lesser General Public License for more details.
00015 // 
00016 // You should have received a copy of the GNU Lesser General Public
00017 // License along with this library; if not, write to the Free Software
00018 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00019 //
00020 
00021 #ifdef _WIN32
00022 #pragma once
00023 #endif
00024 
00025 /// \brief
00026 /// FdoStringP is smart pointer wrapper around strings. 
00027 /// Provides memory management,plus conversion of strings between unicode and utf8
00028 /// and various string manipulation functions
00029 class FdoStringP
00030 {
00031 public:
00032     /// \brief
00033     /// Creates an empty string with value L"".
00034     /// 
00035     FDO_API_COMMON FdoStringP(void);
00036 
00037     /// \brief
00038     /// Creates a string from another string pointer.
00039     /// 
00040     /// \param oValue 
00041     /// Source string to set this string from.
00042     /// 
00043     FDO_API_COMMON FdoStringP(const FdoStringP& oValue);
00044 
00045     /// \brief
00046     /// Creates a string from a unicode (FdoString) string
00047     /// 
00048     /// \param wValue 
00049     /// the unicode string
00050     /// \param bAttach 
00051     /// true: just point to the given string without copying it to an 
00052     /// internal buffer. The caller is responsible for ensuring that
00053     /// the given string is not deleted before this object.
00054     /// false: copy the given string to an internal buffer
00055     /// 
00056     FDO_API_COMMON FdoStringP( FdoString* wValue, FdoBoolean bAttach = false );
00057 
00058     /// \brief
00059     /// Creates a string from a utf8 string
00060     /// 
00061     /// \param sValue 
00062     /// the utf8 string
00063     /// 
00064     FDO_API_COMMON FdoStringP( const char* sValue );
00065 
00066     /// \brief
00067     /// Destroys this string and releases its contents
00068     /// 
00069     FDO_API_COMMON ~FdoStringP(void);
00070 
00071     /// Operators to copy from other strings in various forms
00072 
00073     /// \brief
00074     /// Copies a string from a string pointer.
00075     /// 
00076     /// \param oString 
00077     /// Source string to copy from.
00078     /// 
00079     /// \return
00080     /// Returns the copied string
00081     /// 
00082     FDO_API_COMMON FdoStringP& operator=( const FdoStringP& oString ); 
00083 
00084     /// \brief
00085     /// Copies a string from a utf8 string.
00086     /// 
00087     /// \param sString 
00088     /// Utf8 string to copy from.
00089     /// 
00090     /// \return
00091     /// Returns the copied string
00092     /// 
00093     FDO_API_COMMON FdoStringP& operator=( const char* sString );
00094 
00095     /// \brief
00096     /// Copies a string from a unicode string.
00097     /// 
00098     /// \param wString 
00099     /// Unicode string to copy from.
00100     /// 
00101     /// \return
00102     /// Returns the copied string
00103     /// 
00104     FDO_API_COMMON FdoStringP& operator=( FdoString* wString );
00105 
00106     /// Various operators for concatenating str2 to this.
00107 
00108     /// \brief
00109     /// Appends a unicode string onto this string. 
00110     /// When performance is critical, += should be used whenever possible
00111     /// since it is up to 5X faster than this operator.
00112     /// 
00113     /// \param str2 
00114     /// Unicode string to concatenate
00115     /// 
00116     /// \return
00117     /// Returns the concatenation of this string plus str2
00118     /// 
00119     FDO_API_COMMON const FdoStringP operator+( FdoString* str2 ) const;
00120 
00121     /// \brief
00122     /// Appends the contents of another string onto this string.
00123     /// When performance is critical, += should be used whenever possible
00124     /// since it is up to 5X faster than this operator.
00125     /// 
00126     /// \param str2 
00127     /// string to concatenate
00128     /// 
00129     /// \return
00130     /// Returns the concatenation of this string plus str2
00131     /// 
00132     FDO_API_COMMON const FdoStringP operator+( const FdoStringP str2 ) const
00133     {
00134         return( (*this) + (FdoString*) str2 );
00135     }
00136 
00137     /// \brief
00138     /// Appends a unicode string onto this string.
00139     /// 
00140     /// \param str2 
00141     /// Unicode string to concatenate
00142     /// 
00143     /// \return
00144     /// Returns the concatenation of this string plus str2
00145     /// 
00146     FDO_API_COMMON FdoStringP operator+=( FdoString* str2 );
00147 
00148     /// \brief
00149     /// Appends the contents of another string onto this string.
00150     /// 
00151     /// \param str2 
00152     /// string to concatenate
00153     /// 
00154     /// \return
00155     /// Returns the concatenation of this string plus str2
00156     /// 
00157     FDO_API_COMMON FdoStringP operator+=( const FdoStringP str2 )
00158     {
00159         (*this) = (*this) + (FdoString*) str2;
00160         return( *this );
00161     }
00162 
00163     /// Various comparison operators.
00164 
00165     /// \brief
00166     /// Greater than comparison operator
00167     /// 
00168     /// \param str2 
00169     /// string to compare
00170     /// 
00171     /// \return
00172     /// Returns true if this string is lexically greater than str2
00173     /// 
00174     FDO_API_COMMON bool operator>( const FdoStringP str2 ) const
00175     {
00176         return( wcscmp( *this, str2 ) > 0 );
00177     }
00178 
00179     /// \brief
00180     /// Greater than or equal comparison operator
00181     /// 
00182     /// \param str2 
00183     /// string to compare
00184     /// 
00185     /// \return
00186     /// Returns true if this string is lexically greater or equal to str2
00187     /// 
00188     FDO_API_COMMON bool operator>=( const FdoStringP str2 ) const
00189     {
00190         return( wcscmp( *this, str2 ) >= 0 );
00191     }
00192 
00193     /// \brief
00194     /// Equals comparison operator
00195     /// 
00196     /// \param str2 
00197     /// string to compare
00198     /// 
00199     /// \return
00200     /// Returns true if this string is lexically equal to str2
00201     /// 
00202     FDO_API_COMMON bool operator==( const FdoStringP str2 ) const
00203     {
00204         return( wcscmp( *this, str2 ) == 0 );
00205     }
00206 
00207     /// \brief
00208     /// Equals comparison operator
00209     /// 
00210     /// \param str2 
00211     /// Unicode string to compare
00212     /// 
00213     /// \return
00214     /// Returns true if this string is lexically equal to str2
00215     /// 
00216     FDO_API_COMMON bool operator==( FdoString* str2 ) const
00217     {
00218         return( wcscmp( *this, str2 ? str2 : L"" ) == 0 );
00219     }
00220 
00221     /// \brief
00222     /// Not Equals comparison operator
00223     /// 
00224     /// \param str2 
00225     /// Unicode string to compare
00226     /// 
00227     /// \return
00228     /// Returns true if this string is not lexically equal to str2
00229     /// 
00230     FDO_API_COMMON bool operator!=( FdoString* str2 ) const
00231     {
00232         return( !((*this) == str2) );
00233     }
00234 
00235     /// \brief
00236     /// Less than or Equals comparison operator
00237     /// 
00238     /// \param str2 
00239     /// String to compare
00240     /// 
00241     /// \return
00242     /// Returns true if this string is lexically less than or equal to str2
00243     /// 
00244     FDO_API_COMMON bool operator<=( const FdoStringP str2 ) const
00245     {
00246         return( wcscmp( *this, str2 ) <= 0 );
00247     }
00248 
00249     /// \brief
00250     /// Less than  comparison operator
00251     /// 
00252     /// \param str2 
00253     /// String to compare
00254     /// 
00255     /// \return
00256     /// Returns true if this string is lexically less than str2
00257     /// 
00258     FDO_API_COMMON bool operator<( const FdoStringP str2 ) const
00259     {
00260         return( wcscmp( *this, str2 ) < 0 );
00261     }
00262 
00263     /// \brief
00264     /// Case-insensitive string comparison.
00265     /// 
00266     /// \param str2 
00267     /// String to compare.
00268     /// 
00269     /// \return
00270     /// Returns:
00271     /// <ul>
00272     ///      <li>-1 if this is less than str2
00273     ///      <li>0 if this is equal to str2
00274     ///       <li>1 if this is greater than str2
00275     /// </ul>
00276     /// 
00277     /// 
00278     FDO_API_COMMON int ICompare( const FdoStringP str2 ) const;
00279 
00280 
00281     /// \return
00282     /// Returns the Unicode version of this string that the caller does not have
00283     /// to destroy 
00284     /// 
00285     FDO_API_COMMON operator FdoString*( ) const;
00286 
00287 
00288 
00289     /// \return
00290     /// Returns the UTF8 version of this string that the caller does not have
00291     /// to destroy 
00292     /// 
00293     FDO_API_COMMON operator const char*( ) const;
00294 
00295     /// \return
00296     /// Returns the length (in wide characters) of the Unicode version of this string
00297     /// 
00298     FDO_API_COMMON size_t GetLength() const;
00299 
00300     /// \brief
00301     /// Gets the characters to the left of the given sub-string.
00302     /// 
00303     /// \param delimiter 
00304     /// The substring.
00305     /// 
00306     /// \return
00307     /// Returns all of the characters
00308     ///     to the left of the first occurance of the delimiter string.
00309     ///     All of this string is returned if the delimiter is
00310     ///     not in this string. An empty string(L"") is returned if the delimiter is
00311     /// is NULL or L"".
00312     /// 
00313 
00314     FDO_API_COMMON FdoStringP Left( FdoString* delimiter ) const;
00315 
00316     /// \brief
00317     /// Gets the characters to the right of the given sub-string.
00318     /// 
00319     /// \param delimiter 
00320     /// The substring.
00321     /// 
00322     /// \return
00323     /// Returns all of the characters
00324     ///     to the right of the first occurance of the delimiter string.
00325     ///     an empty string(L"") is returned if the delimiter is
00326     ///     not in this string. All of this string is returned if the delimiter is 
00327     /// NULL or L"".
00328     /// 
00329 
00330     FDO_API_COMMON FdoStringP Right( FdoString* delimiter ) const;
00331 
00332     /// \brief
00333     /// Extracts a sub-string of this string
00334     /// 
00335     /// \param first 
00336     /// the 0-based position of the first character to return.
00337     /// Negative values are treated as 0.
00338     /// \param count 
00339     /// the number of characters to return.
00340     /// If negative then all characters up to the end of this string are returned.
00341     /// \param useUTF8 
00342     /// true: perform Mid against the UTF8 representation of this string.
00343     /// false (default): perform it against the Unicode representation.
00344     /// 
00345     /// \return
00346     /// The extracted sub-string
00347     /// 
00348     FDO_API_COMMON FdoStringP Mid( size_t first, size_t count, bool useUTF8 = false );
00349 
00350     /// \brief
00351     /// Replaces sub-strings.
00352     /// 
00353     /// \param pOld 
00354     /// the sub-string to replace
00355     /// \param pNew 
00356     /// the string to replace pOld by
00357     /// 
00358     /// \return
00359     /// Returns a copy of this string, with all occurrences of pOld
00360     /// replaced by pNew. This string itself is not modified
00361     /// 
00362     FDO_API_COMMON FdoStringP Replace( FdoString* pOld, FdoString* pNew ) const;
00363 
00364     /// \return
00365     /// Returns a copy of this string with all characters in upper case.
00366     /// 
00367     FDO_API_COMMON FdoStringP Upper() const;
00368 
00369     /// \return
00370     /// Returns a copy of this string with all characters in lower case.
00371     /// 
00372     FDO_API_COMMON FdoStringP Lower() const;
00373 
00374     /// \brief
00375     /// Checks for a sub-string.
00376     /// 
00377     /// \param subString 
00378     /// the sub-string to check
00379     /// 
00380     /// \return
00381     /// Returns true if this string has at least 1 occurrence of subString
00382     /// 
00383     FDO_API_COMMON bool Contains( FdoString* subString ) const;
00384 
00385     /// \return
00386     /// Returns true if this string represents a number.
00387     /// 
00388     FDO_API_COMMON bool IsNumber() const;
00389 
00390     /// \brief
00391     /// Converts this string to a long integer.
00392     /// 
00393     /// \return
00394     /// Returns the long integer (0 if the string is not numeric).
00395     /// 
00396     FDO_API_COMMON long ToLong() const;
00397 
00398     /// \brief
00399     /// Converts this string to a double precision number.
00400     /// 
00401     /// \return
00402     /// Returns double (0 if the string is not numeric).
00403     /// 
00404     FDO_API_COMMON FdoDouble ToDouble() const;
00405 
00406     /// \brief
00407     /// Converts this string to a boolean.
00408     /// 
00409     /// \param defaultValue 
00410     /// value returned when string is not recognized as boolean
00411     /// 
00412     /// \return
00413     /// Returns true if the string in lower case is "t", "true", "y", "yes", or "1".
00414     /// Returns false if the string in lower case is "f", "false", "n", "no", or "0".
00415     /// Otherwise returns defaultValue.
00416     /// 
00417     FDO_API_COMMON FdoBoolean ToBoolean(FdoBoolean defaultValue=false ) const;
00418 
00419     /// \brief
00420     /// Create a formatted string.
00421     /// 
00422     /// \param wValue 
00423     /// the formatting template. Can contain 
00424     /// "sprintf" style formatting specs.
00425     /// <param name="...">
00426     /// substitution parms to format into string.
00427     ///     wValue must have one formatting spec per parm.
00428     /// </param>
00429     /// 
00430     /// \return
00431     /// Returns the formatted string.
00432     /// 
00433     FDO_API_COMMON static FdoStringP Format( FdoString* wValue, ... );
00434 
00435     /// \brief
00436     /// Constant representing a zero-length string.
00437     /// 
00438     FDO_API_COMMON static const wchar_t* mEmptyString;
00439 
00440     /// \brief
00441     /// Constant representing a null string.
00442     /// 
00443     FDO_API_COMMON static const wchar_t* mNullString;
00444 
00445 /// \cond DOXYGEN-IGNORE
00446 
00447     /// Utility function for converting from unicode to utf8.
00448     /// returned value is allocated and must be deleted by caller.
00449     FDO_API_COMMON static int Utf8FromUnicode(
00450         const wchar_t   *   Wtext,
00451         int         in_size,
00452         char    *       str_out,
00453         int         out_max_size,
00454         bool        thrown_exception = true
00455     );
00456 
00457     /// Utility function for converting from utf8 to unicode.
00458     /// returned value is allocated and must be deleted by caller.
00459     FDO_API_COMMON static int Utf8ToUnicode(
00460         const char  *   str_in,
00461         int         in_size,
00462         wchar_t *   Wtext,
00463         int         out_size,
00464         bool        thrown_exception = true
00465     );
00466 
00467     /// Utility function for converting from unicode to utf8.
00468     /// returned value is allocated and must be deleted by caller.
00469     FDO_API_COMMON static int Utf8FromUnicode(
00470         const wchar_t   *   Wtext,
00471         char    *       str_out,
00472         int         out_max_size,
00473         bool        thrown_exception = true
00474     );
00475 
00476     /// Utility function for converting from utf8 to unicode.
00477     /// returned value is allocated and must be deleted by caller.
00478     FDO_API_COMMON static int Utf8ToUnicode(
00479         const char  *   str_in,
00480         wchar_t *   Wtext,
00481         int         out_size,
00482         bool        thrown_exception = true
00483     );
00484 
00485     /// Return the length (in Unicode characters) of a UTF8 string
00486     static int Utf8Len(const char *utf8String);
00487 /// \endcond
00488 
00489 private:
00490 
00491     // Creates an FdoStringP from a null-terminated list of strings.
00492     // The strings are concatenated together
00493     FdoStringP( FdoString** values );
00494 
00495     /// structure used to convert between Unicode and UTF8
00496     typedef struct
00497     {
00498     int     cmask;
00499     int     cval;
00500     int     shift;
00501     long    lmask;
00502     long    lval;
00503     } Tab;
00504 
00505     // Descriptor containing refcount and size for the string buffer
00506     typedef struct
00507     {
00508         long mRefCount;
00509         size_t mBufSize;    // size in # of wide characters
00510     } Descriptor;
00511 
00512     /// General functions to set this object's string value.
00513     void SetString(const FdoStringP& oValue);
00514     void SetString(FdoString* wValue, FdoBoolean bAttach = false);
00515     void SetString(const char* sValue);
00516     void SetString(FdoString** values);
00517 
00518     void SetSingle() const;
00519 
00520     /// Caller is responsible for deleting the returned string
00521     wchar_t* _copyAsWChar( ) const;
00522     char* _copyAsChar( ) const;
00523 
00524     /// Refcount functions. Refcount is the number of 
00525     /// FdoStringP objects that point to a particular
00526     /// string buffer.
00527     void AddRef();
00528     void Release();
00529     
00530     // Allocate a fresh buffer big enough to hold the given number of characters.
00531     // Current buffer is re-used if big enough and not referenced by any other FdoStringP
00532     void AllocateBuffer( size_t bufSize );
00533 
00534     // Refcount setter and getter
00535     void SetRefCount( long refCount );
00536     long GetRefCount();
00537 
00538     // Buffer size (in characters) setter and getter.
00539     void SetBufSize( size_t bufSize );
00540     size_t GetBufSize();
00541 
00542     /// String buffer 
00543 
00544     /// wide-char string
00545     wchar_t* mwString;
00546     /// utf8 string
00547     char* msString;
00548     /// Buffer - descriptor + wide-char string
00549     Descriptor* mBuffer;
00550 
00551     /// table for converting between UTF8 and Unicode.
00552     static Tab tab[];
00553 };
00554 
00555 #endif
00556 
00557 
Please send us your comment about this page