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