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