12e61e83400ecd0016da6372d440f121446586c3
[WebKit-https.git] / 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