| FDO API Reference | Feature Data Objects |
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 oValue 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 sValue 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 sValue 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 /// 00111 /// \param str2 00112 /// Unicode string to concatenate 00113 /// 00114 /// \return 00115 /// Returns the concatenation of this string plus str2 00116 /// 00117 FDO_API_COMMON const FdoStringP operator+( FdoString* str2 ) const 00118 { 00119 return(FdoStringP::Format( L"%ls%ls", mwString, str2 ? str2 : L"") ); 00120 } 00121 00122 /// \brief 00123 /// Appends the contents of another string onto this string. 00124 /// 00125 /// \param str2 00126 /// string to concatenate 00127 /// 00128 /// \return 00129 /// Returns the concatenation of this string plus str2 00130 /// 00131 FDO_API_COMMON const FdoStringP operator+( const FdoStringP str2 ) const 00132 { 00133 return( (*this) + (FdoString*) str2 ); 00134 } 00135 00136 /// \brief 00137 /// Appends a unicode string onto this string. 00138 /// 00139 /// \param str2 00140 /// Unicode string to concatenate 00141 /// 00142 /// \return 00143 /// Returns the concatenation of this string plus str2 00144 /// 00145 FDO_API_COMMON FdoStringP operator+=( FdoString* str2 ) 00146 { 00147 (*this) = (*this) + str2; 00148 return( *this ); 00149 } 00150 00151 /// \brief 00152 /// Appends the contents of another string onto this string. 00153 /// 00154 /// \param str2 00155 /// string to concatenate 00156 /// 00157 /// \return 00158 /// Returns the concatenation of this string plus str2 00159 /// 00160 FDO_API_COMMON FdoStringP operator+=( const FdoStringP str2 ) 00161 { 00162 (*this) = (*this) + (FdoString*) str2; 00163 return( *this ); 00164 } 00165 00166 /// Various comparison operators. 00167 00168 /// \brief 00169 /// Greater than comparison operator 00170 /// 00171 /// \param str2 00172 /// string to compare 00173 /// 00174 /// \return 00175 /// Returns true if this string is lexically greater than str2 00176 /// 00177 FDO_API_COMMON bool operator>( const FdoStringP str2 ) const 00178 { 00179 return( wcscmp( *this, str2 ) > 0 ); 00180 } 00181 00182 /// \brief 00183 /// Greater than or equal comparison operator 00184 /// 00185 /// \param str2 00186 /// string to compare 00187 /// 00188 /// \return 00189 /// Returns true if this string is lexically greater or equal to str2 00190 /// 00191 FDO_API_COMMON bool operator>=( const FdoStringP str2 ) const 00192 { 00193 return( wcscmp( *this, str2 ) >= 0 ); 00194 } 00195 00196 /// \brief 00197 /// Equals comparison operator 00198 /// 00199 /// \param str2 00200 /// string to compare 00201 /// 00202 /// \return 00203 /// Returns true if this string is lexically equal to str2 00204 /// 00205 FDO_API_COMMON bool operator==( const FdoStringP str2 ) const 00206 { 00207 return( wcscmp( *this, str2 ) == 0 ); 00208 } 00209 00210 /// \brief 00211 /// Equals comparison operator 00212 /// 00213 /// \param str2 00214 /// Unicode string to compare 00215 /// 00216 /// \return 00217 /// Returns true if this string is lexically equal to str2 00218 /// 00219 FDO_API_COMMON bool operator==( const FdoString* str2 ) const 00220 { 00221 return( wcscmp( *this, str2 ? str2 : L"" ) == 0 ); 00222 } 00223 00224 /// \brief 00225 /// Not Equals comparison operator 00226 /// 00227 /// \param str2 00228 /// Unicode string to compare 00229 /// 00230 /// \return 00231 /// Returns true if this string is not lexically equal to str2 00232 /// 00233 FDO_API_COMMON bool operator!=( const FdoString* str2 ) const 00234 { 00235 return( !((*this) == str2) ); 00236 } 00237 00238 /// \brief 00239 /// Less than or Equals comparison operator 00240 /// 00241 /// \param str2 00242 /// String to compare 00243 /// 00244 /// \return 00245 /// Returns true if this string is lexically less than or equal to str2 00246 /// 00247 FDO_API_COMMON bool operator<=( const FdoStringP str2 ) const 00248 { 00249 return( wcscmp( *this, str2 ) <= 0 ); 00250 } 00251 00252 /// \brief 00253 /// Less than comparison operator 00254 /// 00255 /// \param str2 00256 /// String to compare 00257 /// 00258 /// \return 00259 /// Returns true if this string is lexically less than str2 00260 /// 00261 FDO_API_COMMON bool operator<( const FdoStringP str2 ) const 00262 { 00263 return( wcscmp( *this, str2 ) < 0 ); 00264 } 00265 00266 /// \brief 00267 /// Case-insensitive string comparison. 00268 /// 00269 /// \param str2 00270 /// String to compare. 00271 /// 00272 /// \return 00273 /// Returns: 00274 /// <ul> 00275 /// <li>-1 if this is less than str2 00276 /// <li>0 if this is equal to str2 00277 /// <li>1 if this is greater than str2 00278 /// </ul> 00279 /// 00280 /// 00281 FDO_API_COMMON int ICompare( const FdoStringP str2 ) const; 00282 00283 00284 /// \return 00285 /// Returns the Unicode version of this string that the caller does not have 00286 /// to destroy 00287 /// 00288 FDO_API_COMMON operator FdoString*( ) const; 00289 00290 00291 00292 /// \return 00293 /// Returns the UTF8 version of this string that the caller does not have 00294 /// to destroy 00295 /// 00296 FDO_API_COMMON operator const char*( ) const; 00297 00298 /// \return 00299 /// Returns the length (in wide characters) of the Unicode version of this string 00300 /// 00301 FDO_API_COMMON size_t GetLength() const; 00302 00303 /// \brief 00304 /// Gets the characters to the left of the given sub-string. 00305 /// 00306 /// \param delimeter 00307 /// The substring. 00308 /// 00309 /// \return 00310 /// Returns all of the characters 00311 /// to the left of the first occurance of the delimiter string. 00312 /// All of this string is returned if the delimiter is 00313 /// not in this string. An empty string(L"") is returned if the delimiter is 00314 /// is NULL or L"". 00315 /// 00316 00317 FDO_API_COMMON FdoStringP Left( FdoString* delimiter ) const; 00318 00319 /// \brief 00320 /// Gets the characters to the right of the given sub-string. 00321 /// 00322 /// \param delimeter 00323 /// The substring. 00324 /// 00325 /// \return 00326 /// Returns all of the characters 00327 /// to the right of the first occurance of the delimiter string. 00328 /// an empty string(L"") is returned if the delimiter is 00329 /// not in this string. All of this string is returned if the delimiter is 00330 /// NULL or L"". 00331 /// 00332 00333 FDO_API_COMMON FdoStringP Right( FdoString* delimiter ) const; 00334 00335 /// \brief 00336 /// Extracts a sub-string of this string 00337 /// 00338 /// \param first 00339 /// the 0-based position of the first character to return. 00340 /// Negative values are treated as 0. 00341 /// \param count 00342 /// the number of characters to return. 00343 /// If negative then all characters up to the end of this string are returned. 00344 /// \param useUTF8 00345 /// true: perform Mid against the UTF8 representation of this string. 00346 /// false (default): perform it against the Unicode representation. 00347 /// 00348 /// \return 00349 /// The extracted sub-string 00350 /// 00351 FDO_API_COMMON FdoStringP Mid( size_t first, size_t count, bool useUTF8 = false ); 00352 00353 /// \brief 00354 /// Replaces sub-strings. 00355 /// 00356 /// \param pOld 00357 /// the sub-string to replace 00358 /// \param pNew 00359 /// the string to replace pOld by 00360 /// 00361 /// \return 00362 /// Returns a copy of this string, with all occurrences of pOld 00363 /// replaced by pNew. This string itself is not modified 00364 /// 00365 FDO_API_COMMON FdoStringP Replace( FdoString* pOld, FdoString* pNew ) const; 00366 00367 /// \return 00368 /// Returns a copy of this string with all characters in upper case. 00369 /// 00370 FDO_API_COMMON FdoStringP Upper() const; 00371 00372 /// \return 00373 /// Returns a copy of this string with all characters in lower case. 00374 /// 00375 FDO_API_COMMON FdoStringP Lower() const; 00376 00377 /// \brief 00378 /// Checks for a sub-string. 00379 /// 00380 /// \param subString 00381 /// the sub-string to check 00382 /// 00383 /// \return 00384 /// Returns true if this string has at least 1 occurrence of subString 00385 /// 00386 FDO_API_COMMON bool Contains( FdoString* subString ) const; 00387 00388 /// \return 00389 /// Returns true if this string represents a number. 00390 /// 00391 FDO_API_COMMON bool IsNumber() const; 00392 00393 /// \brief 00394 /// Converts this string to a long integer. 00395 /// 00396 /// \return 00397 /// Returns the long integer (0 if the string is not numeric). 00398 /// 00399 FDO_API_COMMON long ToLong() const; 00400 00401 /// \brief 00402 /// Converts this string to a double precision number. 00403 /// 00404 /// \return 00405 /// Returns double (0 if the string is not numeric). 00406 /// 00407 FDO_API_COMMON FdoDouble ToDouble() const; 00408 00409 /// \brief 00410 /// Converts this string to a boolean. 00411 /// 00412 /// \param defaultValue 00413 /// value returned when string is not recognized as boolean 00414 /// 00415 /// \return 00416 /// Returns true if the string in lower case is "t", "true", "y", "yes", or "1". 00417 /// Returns false if the string in lower case is "f", "false", "n", "no", or "0". 00418 /// Otherwise returns defaultValue. 00419 /// 00420 FDO_API_COMMON FdoBoolean ToBoolean(FdoBoolean defaultValue=false ) const; 00421 00422 /// \brief 00423 /// Create a formatted string. 00424 /// 00425 /// \param wValue 00426 /// the formatting template. Can contain 00427 /// "sprintf" style formatting specs. 00428 /// <param name="..."> 00429 /// substitution parms to format into string. 00430 /// wValue must have one formatting spec per parm. 00431 /// </param> 00432 /// 00433 /// \return 00434 /// Returns the formatted string. 00435 /// 00436 FDO_API_COMMON static FdoStringP Format( FdoString* wValue, ... ); 00437 00438 /// \brief 00439 /// Constant representing a zero-length string. 00440 /// 00441 FDO_API_COMMON static const wchar_t* mEmptyString; 00442 00443 /// \cond DOXYGEN-IGNORE 00444 /// Utility function for converting from unicode to utf8. 00445 /// returned value is allocated and must be deleted by caller. 00446 FDO_API_COMMON static int Utf8FromUnicode( 00447 const wchar_t * Wtext, 00448 int in_size, 00449 char * str_out, 00450 int out_max_size, 00451 bool thrown_exception = true 00452 ); 00453 00454 /// Utility function for converting from utf8 to unicode. 00455 /// returned value is allocated and must be deleted by caller. 00456 FDO_API_COMMON static int Utf8ToUnicode( 00457 const char * str_in, 00458 int in_size, 00459 wchar_t * Wtext, 00460 int out_size, 00461 bool thrown_exception = true 00462 ); 00463 00464 /// Utility function for converting from unicode to utf8. 00465 /// returned value is allocated and must be deleted by caller. 00466 FDO_API_COMMON static int Utf8FromUnicode( 00467 const wchar_t * Wtext, 00468 char * str_out, 00469 int out_max_size, 00470 bool thrown_exception = true 00471 ); 00472 00473 /// Utility function for converting from utf8 to unicode. 00474 /// returned value is allocated and must be deleted by caller. 00475 FDO_API_COMMON static int Utf8ToUnicode( 00476 const char * str_in, 00477 wchar_t * Wtext, 00478 int out_size, 00479 bool thrown_exception = true 00480 ); 00481 00482 /// Return the length (in Unicode characters) of a UTF8 string 00483 static int Utf8Len(const char *utf8String); 00484 /// \endcond 00485 00486 private: 00487 /// structure used to convert between Unicode and UTF8 00488 typedef struct 00489 { 00490 int cmask; 00491 int cval; 00492 int shift; 00493 long lmask; 00494 long lval; 00495 } Tab; 00496 00497 /// General functions to set this object's string value. 00498 void SetString(const FdoStringP& oValue); 00499 void SetString(FdoString* wValue, FdoBoolean bAttach = false); 00500 void SetString(const char* sValue); 00501 00502 void SetSingle() const; 00503 00504 /// Caller is responsible for deleting the returned string 00505 wchar_t* _copyAsWChar( ) const; 00506 char* _copyAsChar( ) const; 00507 00508 /// Refcount functions. Refcount is the number of 00509 /// FdoStringP objects that point to a particular 00510 /// string buffer. 00511 void AddRef(); 00512 void Release(); 00513 00514 /// String buffer 00515 00516 /// unicode string 00517 wchar_t* mwString; 00518 /// utf8 string 00519 char* msString; 00520 /// associated ref counter. 00521 long* mRefCount; 00522 00523 /// table for converting between UTF8 and Unicode. 00524 static Tab tab[]; 00525 00526 /// General purpose refcounter for when pointing to a static string. 00527 static const long mAttachedRefCount; 00528 }; 00529 00530 #endif 00531 00532
| Comments or suggestions? Send us feedback. |