00001 00002 #ifndef __SKYPE_STRING_H 00003 #define __SKYPE_STRING_H 00004 00005 #include <stddef.h> 00006 #include <stdio.h> 00007 #include <stdarg.h> 00008 00009 #include <skype-thread.h> 00010 00011 /** 00012 * \class SEString 00013 * \brief SEString is basic char* based string class. 00014 * 00015 * SEString uses implicit sharing (i.e. reference counting). 00016 * In all of the SEString methods that take const char * parameters, the const char * is 00017 * interpreted as a classic C-style '\\0'-terminated ASCII string. 00018 * A SEString that has not been assigned to anything is null, i.e. both the length 00019 * and data pointer is 0. A SEString that references the empty string ("", a 00020 * single '\\0' char) is empty. 00021 * Use if ( !str.isNull() ) to check for a non-null string. 00022 * 00023 * This class is not thread-safe. Make sure to use deepCopy() when passing between threads. 00024 */ 00025 class SEString 00026 { 00027 public: 00028 /** Constructs a null string, i.e. both the length and data pointer are 0. 00029 * See also isNull(). 00030 */ 00031 inline SEString(); 00032 00033 /** Constructs a string that is a deep copy of str, interpreted as a classic C string. 00034 * If str is 0, then a null string is created. 00035 */ 00036 inline SEString(const char* str); 00037 00038 /** 00039 * Constructs an implicitly shared copy of str. 00040 * This is very fast since it only involves incrementing a reference count. 00041 * \param str is a string to copy 00042 */ 00043 inline SEString(const SEString& str); 00044 00045 /** Destroys the string and frees the string's data if this is the last reference to the string. */ 00046 inline ~SEString(); 00047 00048 /** \cond INTERNAL */ 00049 //protected: 00050 /** Allocates a string of the specified size */ 00051 SEString(size_t buf); 00052 00053 protected: 00054 class Data; 00055 Data* d; 00056 /** \endcond */ 00057 00058 public: 00059 /** \cond INTERNAL */ 00060 /** The wrapper calls this function when necessary, the UI should NOT use it. */ 00061 SEString escape() const; 00062 /** The wrapper calls this function when necessary, the UI should NOT use it. */ 00063 SEString unescape() const; 00064 /** The wrapper calls this function when necessary, the UI should NOT use it. */ 00065 static const SEString keyValue(const SEString& key, const SEString& value); 00066 /** Marks the string as binary one. Only used by wrapper internals. */ 00067 void markAsBinary(); 00068 /** \endcond */ 00069 00070 /** Returns a pointer to the string storing the data. 00071 * If the string is null (as defined by isNull() == true), returns an empty string. 00072 * 00073 * If you need to keep this string after the SEString object gets deleted, make a copy. 00074 * In other words, the char* pointer is valid ONLY AS LONG as the corresponding SEString 00075 * is valid. When the SEString gets deleted, the data get freed and the pointer is invalid. 00076 * 00077 * Some examples: 00078 * <PRE> 00079 * // Works: 00080 * SEString skypeName = me->GetProp(Contact::P_SKYPENAME); 00081 * printf("CONTACT %s\n", (const char*)skypeName); 00082 * 00083 * // Doesn't work, segmentation fault: 00084 * const char * skypeName = (const char *) me->GetProp(Contact::P_SKYPENAME); 00085 * printf("CONTACT %s\n", skypeName); 00086 * 00087 * // Doesn't work: 00088 * const char * skypeName; 00089 * if (1) { 00090 * SEString skypeName_1 = me->GetProp(Contact::P_SKYPENAME); 00091 * skypeName = (const char *) skypeName_1; 00092 * } // skypeName_1 deleted here 00093 * printf("CONTACT %s\n", skypeName); // skypeName_1 has been deleted and the correponding data too 00094 * 00095 * // Works: 00096 * SEString skypeName_1 = me->GetProp(Contact::P_SKYPENAME); 00097 * const char * skypeName = (const char *) skypeName_1; 00098 * printf("CONTACT %s\n", skypeName); 00099 * </PRE> 00100 * 00101 * NB: The example above uses SEObject::GetProp() but in UI it is strongly discouraged to use GetProp(). 00102 * SEObject::GetProps() or Skype::GetMultipleObjectsProps() should be used instead. 00103 */ 00104 operator const char*() const; 00105 const char* data() const { 00106 return operator const char*(); 00107 } 00108 00109 /** Returns the length of the string. 00110 * Null strings and empty strings have zero length. 00111 * See also isNull() and isEmpty(). 00112 */ 00113 size_t size() const { 00114 return length(); 00115 } 00116 /** Returns the length of the string. 00117 * Null strings and empty strings have zero length. 00118 * See also isNull() and isEmpty(). 00119 */ 00120 size_t length() const; 00121 /** Returns true if the string is null; otherwise returns false. 00122 * A null string is always empty. 00123 * See also isEmpty() and length(). 00124 */ 00125 inline bool isNull() const; 00126 /** Returns true if the string is empty, i.e. if length() == 0; 00127 * otherwise returns false. Null strings are also empty. 00128 * SEString a(""); 00129 * a.isEmpty(); // TRUE 00130 * a.isNull(); // FALSE 00131 * 00132 * SEString b; 00133 * b.isEmpty(); // TRUE 00134 * b.isNull(); // TRUE 00135 * 00136 * See also isNull() and length(). 00137 */ 00138 inline bool isEmpty() const; 00139 /** Checks if the string contains binary data */ 00140 bool isBinary() const; 00141 00142 /** Returns true if the string starts with str; otherwise returns false. */ 00143 bool startWith(const SEString& str) const; 00144 /** Returns a string that contains the len rightmost characters of the string. 00145 * If len is greater than the length of the string then the whole string is returned. 00146 */ 00147 SEString right(size_t len) const; 00148 /** Removes str from the string. */ 00149 SEString trim(const SEString& str) const; 00150 /** Returns a section of the string. 00151 * The returned string consists of the characters from position start to position 00152 * end inclusive. If end is not specified, all fields from position start to the 00153 * end of the string are included. 00154 */ 00155 SEString substr(int from, int to) const; 00156 /** Creates a copy of the string that can be passed between threads. */ 00157 SEString deepCopy() const; 00158 /** Returns a hashed value of the string. For internal use. */ 00159 unsigned int hash(unsigned int size = 1) const; 00160 /** Returns true if str is equal to the string; otherwise returns false. 00161 * Note that a null string is not equal to a not-null empty string. 00162 */ 00163 bool equals(const SEString& str) const; 00164 /** Returns true if str is equal to the string; otherwise returns false. 00165 * Note that a null string is not equal to a not-null empty string. 00166 */ 00167 bool equals(const char* str) const; 00168 /** Finds the first occurrence of the character. 00169 * \return Returns the position of c or -1 if c could not be found. 00170 */ 00171 int find(char c) const; 00172 int find(int startpos, char c) const; 00173 00174 /** Appends str to the string and returns a reference to the string. */ 00175 SEString& operator+=(const SEString &str); 00176 /** Appends str to the string and returns a reference to the string. */ 00177 SEString& operator+=(const char *str); 00178 /** Assigns a shallow copy of s to this string and returns a reference to this string. 00179 * This is very fast because the string isn't actually copied. 00180 */ 00181 SEString& operator=(const SEString& str); 00182 /** Assigns a deep copy of str, interpreted as a classic C string to 00183 * this string and returns a reference to this string. 00184 * If str is 0, then a null string is created. See also isNull(). */ 00185 SEString& operator=(const char* str); 00186 00187 typedef unsigned long long uint64; 00188 00189 /** Converts the string to a boolean (works like atoi). 00190 * Returns false on null strings. 00191 */ 00192 bool toBool() const; 00193 /** DEPRECATED: Use toUInt instead. 00194 */ 00195 int toInt() const; 00196 /** Converts the string to an unsigned integer (like strtoul(.. 10). 00197 * Returns 0 on null strings. 00198 */ 00199 unsigned int toUInt() const; 00200 /** Converts the string to an unsigned 64 bits integer (like strtoul(.. 10). 00201 * Returns 0 on null strings. 00202 */ 00203 uint64 toUInt64() const; 00204 /** Converts the string to a binary. 00205 * \param bin Initialized array to store the binary (use length() to get a big enough array) 00206 * \return Size of the binary (which is likely to be smaller than length()). 00207 * Returns 0 if the string is null. 00208 */ 00209 size_t toBinary(char *bin) const; 00210 /** For binaries returns a string with the hexa representation */ 00211 SEString getHexRepresentation() const; 00212 00213 void Format(const char *format, va_list arglist); 00214 void Format(const char *format, ...) { 00215 va_list args; 00216 va_start(args, format); 00217 Format(format, args); 00218 va_end(args); 00219 } 00220 public: 00221 /** Converts an integer into a SEString. */ 00222 static const SEString from(int n); 00223 /** Converts an integer into a SEString using the given base. Only base 10 and 16 are supported. */ 00224 static const SEString from(unsigned int u, unsigned int base = 10); 00225 /** Converts a boolean into a SEString. */ 00226 static const SEString from(bool b); 00227 /** Converts a binary into a SEString. */ 00228 static const SEString from(char *bin, unsigned int len); 00229 static const SEString from(unsigned char chr); 00230 00231 static const SEString Compose(const char *format, ...) { 00232 va_list args; 00233 va_start(args, format); 00234 SEString temp; 00235 temp.Format(format, args); 00236 va_end(args); 00237 return temp; 00238 } 00239 00240 /** \cond INTERNAL */ 00241 protected: 00242 Data* d_ref(); 00243 void d_unref(); 00244 void detach(); 00245 char* se_realloc(size_t new_size); 00246 SEMutex mutex; 00247 /** \endcond */ 00248 }; 00249 00250 /** Returns a string which is the result of concatenating the string s1 and the string s2. */ 00251 inline const SEString operator+(const SEString& s1, const SEString& s2) 00252 { 00253 SEString tmp(s1); 00254 tmp += s2; 00255 return tmp; 00256 } 00257 00258 /** Returns a string which is the result of concatenating the string s1 and the string s2. */ 00259 inline const SEString operator+(const SEString& s1, const char* s2) 00260 { 00261 SEString tmp(s1); 00262 tmp += s2; 00263 return tmp; 00264 } 00265 00266 /** Returns a string which is the result of concatenating the string s1 and the string s2. */ 00267 inline const SEString operator+(const char* s1, const SEString& s2) 00268 { 00269 SEString tmp(s1); 00270 tmp += s2; 00271 return tmp; 00272 } 00273 00274 /** Returns true if s1 is equal to s2; otherwise returns false. */ 00275 inline bool operator==(const SEString& s1, const SEString& s2) 00276 { 00277 return s1.equals(s2); 00278 } 00279 00280 /** Returns true if s1 is equal to s2; otherwise returns false. */ 00281 inline bool operator==(const SEString& s1, const char* s2) 00282 { 00283 return s1.equals(s2); 00284 } 00285 00286 /** Returns true if s1 is equal to s2; otherwise returns false. */ 00287 inline bool operator==(const char* s1, const SEString& s2) 00288 { 00289 return s2.equals(s1); 00290 } 00291 00292 /** Returns true if s1 is not equal to s2; otherwise returns false. */ 00293 inline bool operator!=(const SEString& s1, const SEString& s2) 00294 { 00295 return !s1.equals(s2); 00296 } 00297 00298 /** Returns true if s1 is not equal to s2; otherwise returns false. */ 00299 inline bool operator!=(const SEString& s1, const char* s2) 00300 { 00301 return !s1.equals(s2); 00302 } 00303 00304 /** Returns true if s1 is not equal to s2; otherwise returns false. */ 00305 inline bool operator!=(const char* s1, const SEString& s2) 00306 { 00307 return !s2.equals(s1); 00308 } 00309 00310 00311 SEString::SEString() 00312 :d(0) 00313 { 00314 00315 } 00316 00317 SEString::SEString(const char* str) 00318 :d(0) 00319 { 00320 *this = str; 00321 } 00322 00323 SEString::SEString(const SEString& str) 00324 :d(0) 00325 { 00326 *this = str; 00327 } 00328 00329 SEString::~SEString() 00330 { 00331 d_unref(); 00332 } 00333 00334 bool SEString::isNull() const 00335 { 00336 return (0 == d); 00337 } 00338 00339 bool SEString::isEmpty() const 00340 { 00341 return (0 == length()); 00342 } 00343 00344 #endif // __SKYPE_STRING_H
(c) Skype Technologies S.A. Confidential/Proprietary
Last updated: Fri Mar 16 2012