JavaScriptCore/kjs/ustring.h

   1 // -*- c-basic-offset: 2 -*-
   2 /*
   3  *  This file is part of the KDE libraries
   4  *  Copyright (C) 1999-2000 Harri Porten (porten@kde.org)
   5  *  Copyright (C) 2004 Apple Computer, Inc.
   6  *
   7  *  This library is free software; you can redistribute it and/or
   8  *  modify it under the terms of the GNU Library General Public
   9  *  License as published by the Free Software Foundation; either
  10  *  version 2 of the License, or (at your option) any later version.
  11  *
  12  *  This library is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  *  Library General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU Library General Public License
  18  *  along with this library; see the file COPYING.LIB.  If not, write to
  19  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20  *  Boston, MA 02110-1301, USA.
  21  *
  22  */
  23
  24 #ifndef _KJS_USTRING_H_
  25 #define _KJS_USTRING_H_
  26
  27 #include <kxmlcore/FastMalloc.h>
  28 #include <kxmlcore/RefPtr.h>
  29 #include <kxmlcore/PassRefPtr.h>
  30
  31 #include <stdint.h>
  32
  33 /**
  34  * @internal
  35  */
  36 namespace DOM {
  37   class DOMString;
  38   class AtomicString;
  39 }
  40 class KJScript;
  41 class QString;
  42 class QConstString;
  43
  44 namespace KJS {
  45
  46   class UCharReference;
  47   class UString;
  48
  49   /**
  50    * @short Unicode character.
  51    *
  52    * UChar represents a 16 bit Unicode character. It's internal data
  53    * representation is compatible to XChar2b and QChar. It's therefore
  54    * possible to exchange data with X and Qt with shallow copies.
  55    */
  56   struct UChar {
  57     /**
  58      * Construct a character with uninitialized value.
  59      */
  60     UChar();
  61     /**
  62      * Construct a character with the value denoted by the arguments.
  63      * @param h higher byte
  64      * @param l lower byte
  65      */
  66     UChar(unsigned char h , unsigned char l);
  67     /**
  68      * Construct a character with the given value.
  69      * @param u 16 bit Unicode value
  70      */
  71     UChar(char u);
  72     UChar(unsigned char u);
  73     UChar(unsigned short u);
  74     UChar(const UCharReference &c);
  75     /**
  76      * @return The higher byte of the character.
  77      */
  78     unsigned char high() const { return uc >> 8; }
  79     /**
  80      * @return The lower byte of the character.
  81      */
  82     unsigned char low() const { return uc; }
  83     /**
  84      * @return the 16 bit Unicode value of the character
  85      */
  86     unsigned short unicode() const { return uc; }
  87   public:
  88     /**
  89      * @return The character converted to lower case.
  90      */
  91     UChar toLower() const;
  92     /**
  93      * @return The character converted to upper case.
  94      */
  95     UChar toUpper() const;
  96
  97     unsigned short uc;
  98   };
  99
 100   inline UChar::UChar() { }
 101   inline UChar::UChar(unsigned char h , unsigned char l) : uc(h << 8 | l) { }
 102   inline UChar::UChar(char u) : uc((unsigned char)u) { }
 103   inline UChar::UChar(unsigned char u) : uc(u) { }
 104   inline UChar::UChar(unsigned short u) : uc(u) { }
 105
 106   /**
 107    * @short Dynamic reference to a string character.
 108    *
 109    * UCharReference is the dynamic counterpart of UChar. It's used when
 110    * characters retrieved via index from a UString are used in an
 111    * assignment expression (and therefore can't be treated as being const):
 112    * \code
 113    * UString s("hello world");
 114    * s[0] = 'H';
 115    * \endcode
 116    *
 117    * If that sounds confusing your best bet is to simply forget about the
 118    * existence of this class and treat is as being identical to UChar.
 119    */
 120   class UCharReference {
 121     friend class UString;
 122     UCharReference(UString *s, unsigned int off) : str(s), offset(off) { }
 123   public:
 124     /**
 125      * Set the referenced character to c.
 126      */
 127     UCharReference& operator=(UChar c);
 128     /**
 129      * Same operator as above except the argument that it takes.
 130      */
 131     UCharReference& operator=(char c) { return operator=(UChar(c)); }
 132     /**
 133      * @return Unicode value.
 134      */
 135     unsigned short unicode() const { return ref().uc; }
 136     /**
 137      * @return Lower byte.
 138      */
 139     unsigned char low() const { return ref().uc; }
 140     /**
 141      * @return Higher byte.
 142      */
 143     unsigned char high() const { return ref().uc >> 8; }
 144     /**
 145      * @return Character converted to lower case.
 146      */
 147     UChar toLower() const { return ref().toLower(); }
 148     /**
 149      * @return Character converted to upper case.
 150      */
 151     UChar toUpper() const  { return ref().toUpper(); }
 152   private:
 153     // not implemented, can only be constructed from UString
 154     UCharReference();
 155
 156     UChar& ref() const;
 157     UString *str;
 158     int offset;
 159   };
 160
 161   inline UChar::UChar(const UCharReference &c) : uc(c.unicode()) { }
 162
 163   /**
 164    * @short 8 bit char based string class
 165    */
 166   class CString {
 167   public:
 168     CString() : data(0), length(0) { }
 169     CString(const char *c);
 170     CString(const char *c, int len);
 171     CString(const CString &);
 172
 173     ~CString();
 174
 175     CString &append(const CString &);
 176     CString &operator=(const char *c);
 177     CString &operator=(const CString &);
 178     CString &operator+=(const CString &c) { return append(c); }
 179
 180     int size() const { return length; }
 181     const char *c_str() const { return data; }
 182   private:
 183     char *data;
 184     int length;
 185   };
 186
 187   /**
 188    * @short Unicode string class
 189    */
 190   class UString {
 191     friend bool operator==(const UString&, const UString&);
 192
 193   public:
 194     /**
 195      * @internal
 196      */
 197     struct Rep {
 198
 199       static PassRefPtr<Rep> create(UChar *d, int l);
 200       static PassRefPtr<Rep> createCopying(const UChar *d, int l);
 201       static PassRefPtr<Rep> create(PassRefPtr<Rep> base, int offset, int length);
 202
 203       void destroy();
 204
 205       UChar *data() const { return baseString ? (baseString->buf + baseString->preCapacity + offset) : (buf + preCapacity + offset); }
 206       int size() const { return len; }
 207
 208       unsigned hash() const { if (_hash == 0) _hash = computeHash(data(), len); return _hash; }
 209       static unsigned computeHash(const UChar *, int length);
 210       static unsigned computeHash(const char *);
 211
 212       void ref() { ++rc; }
 213       void deref() { if (--rc == 0) destroy(); }
 214
 215       // unshared data
 216       int offset;
 217       int len;
 218       int rc;
 219       mutable unsigned _hash;
 220       bool isIdentifier;
 221       UString::Rep *baseString;
 222
 223       // potentially shared data
 224       UChar *buf;
 225       int usedCapacity;
 226       int capacity;
 227       int usedPreCapacity;
 228       int preCapacity;
 229
 230       static Rep null;
 231       static Rep empty;
 232     };
 233
 234   public:
 235     /**
 236      * Constructs a null string.
 237      */
 238     UString();
 239     /**
 240      * Constructs a string from the single character c.
 241      */
 242     explicit UString(char c);
 243     /**
 244      * Constructs a string from a classical zero determined char string.
 245      */
 246     UString(const char *c);
 247     /**
 248      * Constructs a string from an array of Unicode characters of the specified
 249      * length.
 250      */
 251     UString(const UChar *c, int length);
 252     /**
 253      * If copy is false the string data will be adopted.
 254      * That means that the data will NOT be copied and the pointer will
 255      * be deleted when the UString object is modified or destroyed.
 256      * Behaviour defaults to a deep copy if copy is true.
 257      */
 258     UString(UChar *c, int length, bool copy);
 259     /**
 260      * Copy constructor. Makes a shallow copy only.
 261      */
 262     UString(const UString &s) : m_rep(s.m_rep) {}
 263     /**
 264      * Convenience declaration only ! You'll be on your own to write the
 265      * implementation for a construction from QString.
 266      *
 267      * Note: feel free to contact me if you want to see a dummy header for
 268      * your favorite FooString class here !
 269      */
 270     UString(const QString&);
 271     /**
 272      * Convenience declaration only ! See UString(const QString&).
 273      */
 274     UString(const DOM::DOMString&);
 275     /**
 276      * Convenience declaration only ! See UString(const QString&).
 277      */
 278     UString(const DOM::AtomicString&);
 279
 280     /**
 281      * Concatenation constructor. Makes operator+ more efficient.
 282      */
 283     UString(const UString &, const UString &);
 284     /**
 285      * Destructor.
 286      */
 287     ~UString() {}
 288
 289     /**
 290      * Constructs a string from an int.
 291      */
 292     static UString from(int i);
 293     /**
 294      * Constructs a string from an unsigned int.
 295      */
 296     static UString from(unsigned int u);
 297     /**
 298      * Constructs a string from a long int.
 299      */
 300     static UString from(long u);
 301     /**
 302      * Constructs a string from a double.
 303      */
 304     static UString from(double d);
 305
 306     struct Range {
 307     public:
 308       Range(int pos, int len) : position(pos), length(len) {}
 309       Range() {}
 310       int position;
 311       int length;
 312     };
 313
 314     UString spliceSubstringsWithSeparators(const Range *substringRanges, int rangeCount, const UString *separators, int separatorCount) const;
 315
 316     /**
 317      * Append another string.
 318      */
 319     UString &append(const UString &);
 320     UString &append(const char *);
 321     UString &append(unsigned short);
 322     UString &append(char c) { return append(static_cast<unsigned short>(static_cast<unsigned char>(c))); }
 323     UString &append(UChar c) { return append(c.uc); }
 324
 325     /**
 326      * @return The string converted to the 8-bit string type CString().
 327      */
 328     CString cstring() const;
 329     /**
 330      * Convert the Unicode string to plain ASCII chars chopping of any higher
 331      * bytes. This method should only be used for *debugging* purposes as it
 332      * is neither Unicode safe nor free from side effects. In order not to
 333      * waste any memory the char buffer is static and *shared* by all UString
 334      * instances.
 335      */
 336     char *ascii() const;
 337
 338     /**
 339      * Convert the string to UTF-8, assuming it is UTF-16 encoded.
 340      * Since this function is tolerant of badly formed UTF-16, it can create UTF-8
 341      * strings that are invalid because they have characters in the range
 342      * U+D800-U+DDFF, U+FFFE, or U+FFFF, but the UTF-8 string is guaranteed to
 343      * be otherwise valid.
 344      */
 345     CString UTF8String() const;
 346
 347     /**
 348      * @see UString(const QString&).
 349      */
 350     DOM::DOMString domString() const;
 351     /**
 352      * @see UString(const QString&).
 353      */
 354     QString qstring() const;
 355     /**
 356      * @see UString(const QString&).
 357      */
 358     QConstString qconststring() const;
 359
 360     /**
 361      * Assignment operator.
 362      */
 363     UString &operator=(const char *c);
 364     /**
 365      * Appends the specified string.
 366      */
 367     UString &operator+=(const UString &s) { return append(s); }
 368     UString &operator+=(const char *s) { return append(s); }
 369
 370     /**
 371      * @return A pointer to the internal Unicode data.
 372      */
 373     const UChar* data() const { return m_rep->data(); }
 374     /**
 375      * @return True if null.
 376      */
 377     bool isNull() const { return (m_rep == &Rep::null); }
 378     /**
 379      * @return True if null or zero length.
 380      */
 381     bool isEmpty() const { return (!m_rep->len); }
 382     /**
 383      * Use this if you want to make sure that this string is a plain ASCII
 384      * string. For example, if you don't want to lose any information when
 385      * using cstring() or ascii().
 386      *
 387      * @return True if the string doesn't contain any non-ASCII characters.
 388      */
 389     bool is8Bit() const;
 390     /**
 391      * @return The length of the string.
 392      */
 393     int size() const { return m_rep->size(); }
 394     /**
 395      * Const character at specified position.
 396      */
 397     UChar operator[](int pos) const;
 398     /**
 399      * Writable reference to character at specified position.
 400      */
 401     UCharReference operator[](int pos);
 402
 403     /**
 404      * Attempts an conversion to a number. Apart from floating point numbers,
 405      * the algorithm will recognize hexadecimal representations (as
 406      * indicated by a 0x or 0X prefix) and +/- Infinity.
 407      * Returns NaN if the conversion failed.
 408      * @param tolerateTrailingJunk if true, toDouble can tolerate garbage after the number.
 409      * @param tolerateEmptyString if false, toDouble will turn an empty string into NaN rather than 0.
 410      */
 411     double toDouble(bool tolerateTrailingJunk, bool tolerateEmptyString) const;
 412     double toDouble(bool tolerateTrailingJunk) const;
 413     double toDouble() const;
 414
 415     /**
 416      * Attempts an conversion to a 32-bit integer. ok will be set
 417      * according to the success.
 418      * @param tolerateEmptyString if false, toUInt32 will return false for *ok for an empty string.
 419      */
 420     uint32_t toUInt32(bool *ok = 0) const;
 421     uint32_t toUInt32(bool *ok, bool tolerateEmptyString) const;
 422     uint32_t toStrictUInt32(bool *ok = 0) const;
 423
 424     /**
 425      * Attempts an conversion to an array index. The "ok" boolean will be set
 426      * to true if it is a valid array index according to the rule from
 427      * ECMA 15.2 about what an array index is. It must exactly match the string
 428      * form of an unsigned integer, and be less than 2^32 - 1.
 429      */
 430     unsigned toArrayIndex(bool *ok = 0) const;
 431
 432     /**
 433      * @return Position of first occurrence of f starting at position pos.
 434      * -1 if the search was not successful.
 435      */
 436     int find(const UString &f, int pos = 0) const;
 437     int find(UChar, int pos = 0) const;
 438     /**
 439      * @return Position of first occurrence of f searching backwards from
 440      * position pos.
 441      * -1 if the search was not successful.
 442      */
 443     int rfind(const UString &f, int pos) const;
 444     int rfind(UChar, int pos) const;
 445     /**
 446      * @return The sub string starting at position pos and length len.
 447      */
 448     UString substr(int pos = 0, int len = -1) const;
 449     /**
 450      * Static instance of a null string.
 451      */
 452     static const UString &null();
 453 #ifdef KJS_DEBUG_MEM
 454     /**
 455      * Clear statically allocated resources.
 456      */
 457     static void globalClear();
 458 #endif
 459
 460     Rep *rep() const { return m_rep.get(); }
 461     UString(PassRefPtr<Rep> r) : m_rep(r) { }
 462
 463     void copyForWriting();
 464
 465   private:
 466     int expandedSize(int size, int otherSize) const;
 467     int usedCapacity() const;
 468     int usedPreCapacity() const;
 469     void expandCapacity(int requiredLength);
 470     void expandPreCapacity(int requiredPreCap);
 471
 472     RefPtr<Rep> m_rep;
 473   };
 474
 475   inline bool operator==(const UChar &c1, const UChar &c2) {
 476     return (c1.uc == c2.uc);
 477   }
 478   bool operator==(const UString& s1, const UString& s2);
 479   inline bool operator!=(const UString& s1, const UString& s2) {
 480     return !KJS::operator==(s1, s2);
 481   }
 482   bool operator<(const UString& s1, const UString& s2);
 483   bool operator==(const UString& s1, const char *s2);
 484   inline bool operator!=(const UString& s1, const char *s2) {
 485     return !KJS::operator==(s1, s2);
 486   }
 487   inline bool operator==(const char *s1, const UString& s2) {
 488     return operator==(s2, s1);
 489   }
 490   inline bool operator!=(const char *s1, const UString& s2) {
 491     return !KJS::operator==(s1, s2);
 492   }
 493   bool operator==(const CString& s1, const CString& s2);
 494   inline UString operator+(const UString& s1, const UString& s2) {
 495     return UString(s1, s2);
 496   }
 497
 498   int compare(const UString &, const UString &);
 499
 500   // Given a first byte, gives the length of the UTF-8 sequence it begins.
 501   // Returns 0 for bytes that are not legal starts of UTF-8 sequences.
 502   // Only allows sequences of up to 4 bytes, since that works for all Unicode characters (U-00000000 to U-0010FFFF).
 503   int UTF8SequenceLength(char);
 504
 505   // Takes a null-terminated C-style string with a UTF-8 sequence in it and converts it to a character.
 506   // Only allows Unicode characters (U-00000000 to U-0010FFFF).
 507   // Returns -1 if the sequence is not valid (including presence of extra bytes).
 508   int decodeUTF8Sequence(const char *);
 509
 510 inline UString::UString()
 511   : m_rep(&Rep::null)
 512 {
 513 }
 514
 515 // Rule from ECMA 15.2 about what an array index is.
 516 // Must exactly match string form of an unsigned integer, and be less than 2^32 - 1.
 517 inline unsigned UString::toArrayIndex(bool *ok) const
 518 {
 519     unsigned i = toStrictUInt32(ok);
 520     if (ok && i >= 0xFFFFFFFFU)
 521         *ok = false;
 522     return i;
 523 }
 524
 525 } // namespace
 526
 527 #endif