- Main Page
- Related Pages
- Classes
- Files
- Examples

- File List
- File Members

# skype-string.h

Go to the documentation of this file.

    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

All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

(c) Skype Technologies S.A. Confidential/Proprietary

Last updated: Fri Mar 16 2012