bb5d990fec4a97c344270962b2b7e150f9db2480
[pinentry.git] / qt / secqstring.cpp
1 /* secqstring.cpp - Secure version of QString.
2    Copyright (C) 1992-2002 Trolltech AS.  All rights reserved.
3    Copyright (C) 2003 g10 Code GmbH
4
5    The license of the original qstring.cpp file from which this file
6    is derived can be found below.  Modified by Marcus Brinkmann
7    <marcus@g10code.de>.  All modifications are licensed as follows, so
8    that the intersection of the two licenses is then the GNU General
9    Public License version 2.
10
11    This program is free software; you can redistribute it and/or
12    modify it under the terms of the GNU General Public License as
13    published by the Free Software Foundation; either version 2 of the
14    License, or (at your option) any later version.
15  
16    This program is distributed in the hope that it will be useful, but
17    WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    General Public License for more details.
20  
21    You should have received a copy of the GNU General Public License
22    along with this program; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24    02111-1307, USA  */
25
26 /****************************************************************************
27 ** $Id$
28 **
29 ** Implementation of the SecQString class and related Unicode functions
30 **
31 ** Created : 920722
32 **
33 ** Copyright (C) 1992-2002 Trolltech AS.  All rights reserved.
34 **
35 ** This file is part of the tools module of the Qt GUI Toolkit.
36 **
37 ** This file may be distributed under the terms of the Q Public License
38 ** as defined by Trolltech AS of Norway and appearing in the file
39 ** LICENSE.QPL included in the packaging of this file.
40 **
41 ** This file may be distributed and/or modified under the terms of the
42 ** GNU General Public License version 2 as published by the Free Software
43 ** Foundation and appearing in the file LICENSE.GPL included in the
44 ** packaging of this file.
45 **
46 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
47 ** licenses may use this file in accordance with the Qt Commercial License
48 ** Agreement provided with the Software.
49 **
50 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
51 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
52 **
53 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
54 **   information about Qt Commercial License Agreements.
55 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
56 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
57 **
58 ** Contact info@trolltech.com if any conditions of this licensing are
59 ** not clear to you.
60 **
61 **********************************************************************/
62
63 // Don't define it while compiling this module, or USERS of Qt will
64 // not be able to link.
65
66 #include "secqstring.h"
67
68 #include "private/qunicodetables_p.h"
69
70 static uint computeNewMax( uint len )
71 {
72     uint newMax = 4;
73     while ( newMax < len )
74         newMax *= 2;
75     // try to save some memory
76     if ( newMax >= 1024 * 1024 && len <= newMax - (newMax >> 2) )
77         newMax -= newMax >> 2;
78     return newMax;
79 }
80
81 // These macros are used for efficient allocation of QChar strings.
82 // IMPORTANT! If you change these, make sure you also change the
83 // "delete unicode" statement in ~SecQStringData() in SecQString.h correspondingly!
84
85 #define QT_ALLOC_SECQCHAR_VEC(N) (QChar*) ::secmem_malloc (sizeof(QChar) * (N))
86 #define QT_DELETE_SECQCHAR_VEC(P) ::secmem_free (P)
87
88
89 /*****************************************************************************
90   SecQString member functions
91  *****************************************************************************/
92
93 /*!
94     \class SecQString SecQString.h
95     \reentrant
96
97     \brief The SecQString class provides an abstraction of Unicode text
98     and the classic C '\0'-terminated char array.
99
100     \ingroup tools
101     \ingroup shared
102     \ingroup text
103     \mainclass
104
105     SecQString uses \link shclass.html implicit sharing\endlink, which
106     makes it very efficient and easy to use.
107
108     In all of the SecQString methods that take \c {const char *}
109     parameters, the \c {const char *} is interpreted as a classic
110     C-style '\0'-terminated ASCII string. It is legal for the \c
111     {const char *} parameter to be 0. If the \c {const char *} is not
112     '\0'-terminated, the results are undefined. Functions that copy
113     classic C strings into a SecQString will not copy the terminating
114     '\0' character. The QChar array of the SecQString (as returned by
115     unicode()) is generally not terminated by a '\0'. If you need to
116     pass a SecQString to a function that requires a C '\0'-terminated
117     string use latin1().
118
119     \keyword SecQString::null
120     A SecQString that has not been assigned to anything is \e null, i.e.
121     both the length and data pointer is 0. A SecQString that references
122     the empty string ("", a single '\0' char) is \e empty. Both null
123     and empty SecQStrings are legal parameters to the methods. Assigning
124     \c{(const char *) 0} to SecQString gives a null SecQString. For
125     convenience, \c SecQString::null is a null SecQString. When sorting,
126     empty strings come first, followed by non-empty strings, followed
127     by null strings. We recommend using \c{if ( !str.isNull() )} to
128     check for a non-null string rather than \c{if ( !str )}; see \l
129     operator!() for an explanation.
130
131     Note that if you find that you are mixing usage of \l QCString,
132     SecQString, and \l QByteArray, this causes lots of unnecessary
133     copying and might indicate that the true nature of the data you
134     are dealing with is uncertain. If the data is '\0'-terminated 8-bit
135     data, use \l QCString; if it is unterminated (i.e. contains '\0's)
136     8-bit data, use \l QByteArray; if it is text, use SecQString.
137
138     Lists of strings are handled by the SecQStringList class. You can
139     split a string into a list of strings using SecQStringList::split(),
140     and join a list of strings into a single string with an optional
141     separator using SecQStringList::join(). You can obtain a list of
142     strings from a string list that contain a particular substring or
143     that match a particular \link qregexp.html regex\endlink using
144     SecQStringList::grep().
145
146     <b>Note for C programmers</b>
147
148     Due to C++'s type system and the fact that SecQString is implicitly
149     shared, SecQStrings may be treated like ints or other simple base
150     types. For example:
151
152     \code
153     SecQString boolToString( bool b )
154     {
155         SecQString result;
156         if ( b )
157             result = "True";
158         else
159             result = "False";
160         return result;
161     }
162     \endcode
163
164     The variable, result, is an auto variable allocated on the stack.
165     When return is called, because we're returning by value, The copy
166     constructor is called and a copy of the string is returned. (No
167     actual copying takes place thanks to the implicit sharing, see
168     below.)
169
170     Throughout Qt's source code you will encounter SecQString usages like
171     this:
172     \code
173     SecQString func( const SecQString& input )
174     {
175         SecQString output = input;
176         // process output
177         return output;
178     }
179     \endcode
180
181     The 'copying' of input to output is almost as fast as copying a
182     pointer because behind the scenes copying is achieved by
183     incrementing a reference count. SecQString (like all Qt's implicitly
184     shared classes) operates on a copy-on-write basis, only copying if
185     an instance is actually changed.
186
187     If you wish to create a deep copy of a SecQString without losing any
188     Unicode information then you should use QDeepCopy.
189
190     \sa QChar QCString QByteArray SecQConstString
191 */
192
193 Q_EXPORT SecQStringData *SecQString::shared_null = 0;
194 QT_STATIC_CONST_IMPL SecQString SecQString::null;
195 QT_STATIC_CONST_IMPL QChar QChar::null;
196 QT_STATIC_CONST_IMPL QChar QChar::replacement((ushort)0xfffd);
197 QT_STATIC_CONST_IMPL QChar QChar::byteOrderMark((ushort)0xfeff);
198 QT_STATIC_CONST_IMPL QChar QChar::byteOrderSwapped((ushort)0xfffe);
199 QT_STATIC_CONST_IMPL QChar QChar::nbsp((ushort)0x00a0);
200
201 SecQStringData* SecQString::makeSharedNull()
202 {
203     SecQString::shared_null = new SecQStringData;
204 #if defined( Q_OS_MAC )
205     SecQString *that = const_cast<SecQString *>(&SecQString::null);
206     that->d = SecQString::shared_null;
207 #endif
208     return SecQString::shared_null;
209 }
210
211 /*!
212     \fn SecQString::SecQString()
213
214     Constructs a null string, i.e. both the length and data pointer
215     are 0.
216
217     \sa isNull()
218 */
219
220 /*!
221     Constructs a string of length one, containing the character \a ch.
222 */
223 SecQString::SecQString( QChar ch )
224 {
225     d = new SecQStringData( QT_ALLOC_SECQCHAR_VEC( 1 ), 1, 1 );
226     d->unicode[0] = ch;
227 }
228
229 /*!
230     Constructs an implicitly shared copy of \a s. This is very fast
231     since it only involves incrementing a reference count.
232 */
233 SecQString::SecQString( const SecQString &s ) :
234     d(s.d)
235 {
236     d->ref();
237 }
238
239
240 SecQString::SecQString( int size, bool /*dummy*/ )
241 {
242     if ( size ) {
243         int l = size;
244         QChar* uc = QT_ALLOC_SECQCHAR_VEC( l );
245         d = new SecQStringData( uc, 0, l );
246     } else {
247         d = shared_null ? shared_null : (shared_null=new SecQStringData);
248         d->ref();
249     }
250 }
251
252
253 /* Deep copy of STR.  */
254 SecQString::SecQString( const QString &str )
255 {
256     const QChar *unicode = str.unicode ();
257     uint length = str.length ();
258
259     if ( !unicode && !length ) {
260         d = shared_null ? shared_null : makeSharedNull();
261         d->ref();
262     } else {
263         QChar* uc = QT_ALLOC_SECQCHAR_VEC( length );
264         if ( unicode )
265             memcpy(uc, unicode, length*sizeof(QChar));
266         d = new SecQStringData(uc,unicode ? length : 0,length);
267     }  
268 }
269
270
271 /*!
272     Constructs a string that is a deep copy of the first \a length
273     characters in the QChar array.
274
275     If \a unicode and \a length are 0, then a null string is created.
276
277     If only \a unicode is 0, the string is empty but has \a length
278     characters of space preallocated: SecQString expands automatically
279     anyway, but this may speed up some cases a little. We recommend
280     using the plain constructor and setLength() for this purpose since
281     it will result in more readable code.
282
283     \sa isNull() setLength()
284 */
285
286 SecQString::SecQString( const QChar* unicode, uint length )
287 {
288     if ( !unicode && !length ) {
289         d = shared_null ? shared_null : makeSharedNull();
290         d->ref();
291     } else {
292         QChar* uc = QT_ALLOC_SECQCHAR_VEC( length );
293         if ( unicode )
294             memcpy(uc, unicode, length*sizeof(QChar));
295         d = new SecQStringData(uc,unicode ? length : 0,length);
296     }
297 }
298
299 /*!
300     \fn SecQString::~SecQString()
301
302     Destroys the string and frees the string's data if this is the
303     last reference to the string.
304 */
305
306
307 /*!
308     Deallocates any space reserved solely by this SecQString.
309
310     If the string does not share its data with another SecQString
311     instance, nothing happens; otherwise the function creates a new,
312     unique copy of this string. This function is called whenever the
313     string is modified.
314 */
315
316 void SecQString::real_detach()
317 {
318     setLength( length() );
319 }
320
321 void SecQString::deref()
322 {
323     if ( d && d->deref() ) {
324         if ( d != shared_null )
325             delete d;
326         d = 0;
327     }
328 }
329
330 void SecQStringData::deleteSelf()
331 {
332     delete this;
333 }
334
335 /*!
336     \fn SecQString& SecQString::operator=( QChar c )
337
338     Sets the string to contain just the single character \a c.
339 */
340
341
342 /*!
343     \overload
344
345     Assigns a shallow copy of \a s to this string and returns a
346     reference to this string. This is very fast because the string
347     isn't actually copied.
348 */
349 SecQString &SecQString::operator=( const SecQString &s )
350 {
351     s.d->ref();
352     deref();
353     d = s.d;
354     return *this;
355 }
356
357
358 /*!
359     \fn bool SecQString::isNull() const
360
361     Returns TRUE if the string is null; otherwise returns FALSE. A
362     null string is always empty.
363
364     \code
365         SecQString a;          // a.unicode() == 0, a.length() == 0
366         a.isNull();         // TRUE, because a.unicode() == 0
367         a.isEmpty();        // TRUE, because a.length() == 0
368     \endcode
369
370     \sa isEmpty(), length()
371 */
372
373 /*!
374     \fn bool SecQString::isEmpty() const
375
376     Returns TRUE if the string is empty, i.e. if length() == 0;
377     otherwise returns FALSE. Null strings are also empty.
378
379     \code
380         SecQString a( "" );
381         a.isEmpty();        // TRUE
382         a.isNull();         // FALSE
383
384         SecQString b;
385         b.isEmpty();        // TRUE
386         b.isNull();         // TRUE
387     \endcode
388
389     \sa isNull(), length()
390 */
391
392 /*!
393     \fn uint SecQString::length() const
394
395     Returns the length of the string.
396
397     Null strings and empty strings have zero length.
398
399     \sa isNull(), isEmpty()
400 */
401
402 /*!
403     If \a newLen is less than the length of the string, then the
404     string is truncated at position \a newLen. Otherwise nothing
405     happens.
406
407     \code
408         SecQString s = "truncate me";
409         s.truncate( 5 );            // s == "trunc"
410     \endcode
411
412     \sa setLength()
413 */
414
415 void SecQString::truncate( uint newLen )
416 {
417     if ( newLen < d->len )
418         setLength( newLen );
419 }
420
421 /*!
422     Ensures that at least \a newLen characters are allocated to the
423     string, and sets the length of the string to \a newLen. Any new
424     space allocated contains arbitrary data.
425
426     \sa reserve(), truncate()
427 */
428 void SecQString::setLength( uint newLen )
429 {
430     if ( d->count != 1 || newLen > d->maxl ||
431          ( newLen * 4 < d->maxl && d->maxl > 4 ) ) {
432         // detach, grow or shrink
433         uint newMax = computeNewMax( newLen );
434         QChar* nd = QT_ALLOC_SECQCHAR_VEC( newMax );
435         if ( nd ) {
436             uint len = QMIN( d->len, newLen );
437             memcpy( nd, d->unicode, sizeof(QChar) * len );
438             deref();
439             d = new SecQStringData( nd, newLen, newMax );
440         }
441     } else {
442         d->len = newLen;
443     }
444 }
445
446
447 /*!
448     \internal
449
450     Like setLength, but doesn't shrink the allocated memory.
451 */
452 void SecQString::grow( uint newLen )
453 {
454     if ( d->count != 1 || newLen > d->maxl ) {
455         setLength( newLen );
456     } else {
457         d->len = newLen;
458     }
459 }
460
461
462 /*!
463     Returns a substring that contains the \a len leftmost characters
464     of the string.
465
466     The whole string is returned if \a len exceeds the length of the
467     string.
468
469     \code
470         SecQString s = "Pineapple";
471         SecQString t = s.left( 4 );    // t == "Pine"
472     \endcode
473
474     \sa right(), mid(), isEmpty()
475 */
476
477 SecQString SecQString::left( uint len ) const
478 {
479     if ( isEmpty() ) {
480         return SecQString();
481     } else if ( len == 0 ) {                    // ## just for 1.x compat:
482         return SecQString ("");
483     } else if ( len >= length() ) {
484         return *this;
485     } else {
486         SecQString s( len, TRUE );
487         memcpy( s.d->unicode, d->unicode, len * sizeof(QChar) );
488         s.d->len = len;
489         return s;
490     }
491 }
492
493 /*!
494     Returns a string that contains the \a len rightmost characters of
495     the string.
496
497     If \a len is greater than the length of the string then the whole
498     string is returned.
499
500     \code
501         SecQString string( "Pineapple" );
502         SecQString t = string.right( 5 );   // t == "apple"
503     \endcode
504
505     \sa left(), mid(), isEmpty()
506 */
507
508 SecQString SecQString::right( uint len ) const
509 {
510     if ( isEmpty() ) {
511         return SecQString();
512     } else if ( len == 0 ) {                    // ## just for 1.x compat:
513         return SecQString ("");
514     } else {
515         uint l = length();
516         if ( len >= l )
517             return *this;
518         SecQString s( len, TRUE );
519         memcpy( s.d->unicode, d->unicode+(l-len), len*sizeof(QChar) );
520         s.d->len = len;
521         return s;
522     }
523 }
524
525 /*!
526     Returns a string that contains the \a len characters of this
527     string, starting at position \a index.
528
529     Returns a null string if the string is empty or \a index is out of
530     range. Returns the whole string from \a index if \a index + \a len
531     exceeds the length of the string.
532
533     \code
534         SecQString s( "Five pineapples" );
535         SecQString t = s.mid( 5, 4 );                  // t == "pine"
536     \endcode
537
538     \sa left(), right()
539 */
540
541 SecQString SecQString::mid( uint index, uint len ) const
542 {
543     uint slen = length();
544     if ( isEmpty() || index >= slen ) {
545         return SecQString();
546     } else if ( len == 0 ) {                    // ## just for 1.x compat:
547         return SecQString ("");
548     } else {
549         if ( len > slen-index )
550             len = slen - index;
551         if ( index == 0 && len == slen )
552             return *this;
553         register const QChar *p = unicode()+index;
554         SecQString s( len, TRUE );
555         memcpy( s.d->unicode, p, len * sizeof(QChar) );
556         s.d->len = len;
557         return s;
558     }
559 }
560
561 /*!
562     Inserts \a s into the string at position \a index.
563
564     If \a index is beyond the end of the string, the string is
565     extended with spaces to length \a index and \a s is then appended
566     and returns a reference to the string.
567
568     \code
569         SecQString string( "I like fish" );
570         str = string.insert( 2, "don't " );
571         // str == "I don't like fish"
572     \endcode
573
574     \sa remove(), replace()
575 */
576
577 SecQString &SecQString::insert( uint index, const SecQString &s )
578 {
579     // the sub function takes care of &s == this case.
580     return insert( index, s.unicode(), s.length() );
581 }
582
583 /*!
584     \overload
585
586     Inserts the first \a len characters in \a s into the string at
587     position \a index and returns a reference to the string.
588 */
589
590 SecQString &SecQString::insert( uint index, const QChar* s, uint len )
591 {
592     if ( len == 0 )
593         return *this;
594     uint olen = length();
595     int nlen = olen + len;
596
597     if ( s >= d->unicode && (uint)(s - d->unicode) < d->maxl ) {
598         // Part of me - take a copy.
599         QChar *tmp = QT_ALLOC_SECQCHAR_VEC( len );
600         memcpy(tmp,s,len*sizeof(QChar));
601         insert(index,tmp,len);
602         QT_DELETE_SECQCHAR_VEC( tmp );
603         return *this;
604     }
605
606     if ( index >= olen ) {                      // insert after end of string
607         grow( len + index );
608         int n = index - olen;
609         QChar* uc = d->unicode+olen;
610         while (n--)
611             *uc++ = ' ';
612         memcpy( d->unicode+index, s, sizeof(QChar)*len );
613     } else {                                    // normal insert
614         grow( nlen );
615         memmove( d->unicode + index + len, unicode() + index,
616                  sizeof(QChar) * (olen - index) );
617         memcpy( d->unicode + index, s, sizeof(QChar) * len );
618     }
619     return *this;
620 }
621
622 /*!
623     Removes \a len characters from the string starting at position \a
624     index, and returns a reference to the string.
625
626     If \a index is beyond the length of the string, nothing happens.
627     If \a index is within the string, but \a index + \a len is beyond
628     the end of the string, the string is truncated at position \a
629     index.
630
631     \code
632         SecQString string( "Montreal" );
633         string.remove( 1, 4 );      // string == "Meal"
634     \endcode
635
636     \sa insert(), replace()
637 */
638
639 SecQString &SecQString::remove( uint index, uint len )
640 {
641     uint olen = length();
642     if ( index >= olen  ) {
643         // range problems
644     } else if ( index + len >= olen ) {  // index ok
645         setLength( index );
646     } else if ( len != 0 ) {
647         real_detach();
648         memmove( d->unicode+index, d->unicode+index+len,
649                  sizeof(QChar)*(olen-index-len) );
650         setLength( olen-len );
651     }
652     return *this;
653 }
654
655
656 /*!
657     \overload
658
659     Replaces \a len characters with \a slen characters of QChar data
660     from \a s, starting at position \a index, and returns a reference
661     to the string.
662
663     \sa insert(), remove()
664 */
665
666 SecQString &SecQString::replace( uint index, uint len, const QChar* s, uint slen )
667 {
668     real_detach();
669     if ( len == slen && index + len <= length() ) {
670         // Optimized common case: replace without size change
671         memcpy( d->unicode+index, s, len * sizeof(QChar) );
672     } else if ( s >= d->unicode && (uint)(s - d->unicode) < d->maxl ) {
673         // Part of me - take a copy.
674         QChar *tmp = QT_ALLOC_SECQCHAR_VEC( slen );
675         memcpy( tmp, s, slen * sizeof(QChar) );
676         replace( index, len, tmp, slen );
677         QT_DELETE_SECQCHAR_VEC( tmp );
678     } else {
679         remove( index, len );
680         insert( index, s, slen );
681     }
682     return *this;
683 }
684
685
686 /*!
687     Replaces \a len characters from the string with \a s, starting at
688     position \a index, and returns a reference to the string.
689
690     If \a index is beyond the length of the string, nothing is deleted
691     and \a s is appended at the end of the string. If \a index is
692     valid, but \a index + \a len is beyond the end of the string,
693     the string is truncated at position \a index, then \a s is
694     appended at the end.
695
696     \code
697         QString string( "Say yes!" );
698         string = string.replace( 4, 3, "NO" );
699         // string == "Say NO!"
700     \endcode
701
702     \sa insert(), remove()
703 */
704
705 SecQString &SecQString::replace( uint index, uint len, const SecQString &s )
706 {
707     return replace( index, len, s.unicode(), s.length() );
708 }
709
710
711 /*!
712     Appends \a str to the string and returns a reference to the string.
713 */
714 SecQString& SecQString::operator+=( const SecQString &str )
715 {
716     uint len1 = length();
717     uint len2 = str.length();
718     if ( len2 ) {
719         if ( isEmpty() ) {
720             operator=( str );
721         } else {
722             grow( len1+len2 );
723             memcpy( d->unicode+len1, str.unicode(), sizeof(QChar)*len2 );
724         }
725     } else if ( isNull() && !str.isNull() ) {   // ## just for 1.x compat:
726         *this = SecQString ("");
727     }
728     return *this;
729 }
730
731
732 /*!
733     Returns the string encoded in UTF-8 format.
734
735     See QTextCodec for more diverse coding/decoding of Unicode strings.
736
737     \sa fromUtf8(), ascii(), latin1(), local8Bit()
738 */
739 uchar *SecQString::utf8() const
740 {
741     int l = length();
742     int rlen = l*3+1;
743     uchar* rstr = (uchar*) ::secmem_malloc (rlen);
744     uchar* cursor = rstr;
745     const QChar *ch = d->unicode;
746     for (int i=0; i < l; i++) {
747         uint u = ch->unicode();
748         if ( u < 0x80 ) {
749             *cursor++ = (uchar)u;
750         } else {
751             if ( u < 0x0800 ) {
752                 *cursor++ = 0xc0 | ((uchar) (u >> 6));
753             } else {
754                 if (u >= 0xd800 && u < 0xdc00 && i < l-1) {
755                     unsigned short low = ch[1].unicode();
756                     if (low >= 0xdc00 && low < 0xe000) {
757                         ++ch;
758                         ++i;
759                         u = (u - 0xd800)*0x400 + (low - 0xdc00) + 0x10000;
760                     }
761                 }
762                 if (u > 0xffff) {
763                     // if people are working in utf8, but strings are encoded in eg. latin1, the resulting
764                     // name might be invalid utf8. This and the corresponding code in fromUtf8 takes care
765                     // we can handle this without loosing information. This can happen with latin filenames
766                     // and a utf8 locale under Unix.
767                     if (u > 0x10fe00 && u < 0x10ff00) {
768                         *cursor++ = (u - 0x10fe00);
769                         ++ch;
770                         continue;
771                     } else {
772                         *cursor++ = 0xf0 | ((uchar) (u >> 18));
773                         *cursor++ = 0x80 | ( ((uchar) (u >> 12)) & 0x3f);
774                     }
775                 } else {
776                     *cursor++ = 0xe0 | ((uchar) (u >> 12));
777                 }
778                 *cursor++ = 0x80 | ( ((uchar) (u >> 6)) & 0x3f);
779             }
780             *cursor++ = 0x80 | ((uchar) (u&0x3f));
781         }
782         ++ch;
783     }
784     /* FIXME: secmem_realloc doesn't release extra memory.  */
785     *cursor = '\0';
786     return rstr;
787 }
788
789
790 /*!
791   \fn QChar SecQString::at( uint ) const
792
793     Returns the character at index \a i, or 0 if \a i is beyond the
794     length of the string.
795
796     \code
797         const SecQString string( "abcdefgh" );
798         QChar ch = string.at( 4 );
799         // ch == 'e'
800     \endcode
801
802     If the SecQString is not const (i.e. const SecQString) or const& (i.e.
803     const SecQString &), then the non-const overload of at() will be used
804     instead.
805 */
806
807 /*!
808     \fn QChar SecQString::constref(uint i) const
809
810     Returns the QChar at index \a i by value.
811
812     Equivalent to at(\a i).
813
814     \sa ref()
815 */
816
817 /*!
818     \fn QChar& SecQString::ref(uint i)
819
820     Returns the QChar at index \a i by reference, expanding the string
821     with QChar::null if necessary. The resulting reference can be
822     assigned to, or otherwise used immediately, but becomes invalid
823     once furher modifications are made to the string.
824
825     \code
826         SecQString string("ABCDEF");
827         QChar ch = string.ref( 3 );         // ch == 'D'
828     \endcode
829
830     \sa constref()
831 */
832
833 /*!
834     \fn QChar SecQString::operator[]( int ) const
835
836     Returns the character at index \a i, or QChar::null if \a i is
837     beyond the length of the string.
838
839     If the SecQString is not const (i.e., const SecQString) or const\&
840     (i.e., const SecQString\&), then the non-const overload of operator[]
841     will be used instead.
842 */
843
844 /*!
845     \fn QCharRef SecQString::operator[]( int )
846
847     \overload
848
849     The function returns a reference to the character at index \a i.
850     The resulting reference can then be assigned to, or used
851     immediately, but it will become invalid once further modifications
852     are made to the original string.
853
854     If \a i is beyond the length of the string then the string is
855     expanded with QChar::nulls, so that the QCharRef references a
856     valid (null) character in the string.
857
858     The QCharRef internal class can be used much like a constant
859     QChar, but if you assign to it, you change the original string
860     (which will detach itself because of SecQString's copy-on-write
861     semantics). You will get compilation errors if you try to use the
862     result as anything but a QChar.
863 */
864
865 /*!
866     \fn QCharRef SecQString::at( uint i )
867
868     \overload
869
870     The function returns a reference to the character at index \a i.
871     The resulting reference can then be assigned to, or used
872     immediately, but it will become invalid once further modifications
873     are made to the original string.
874
875     If \a i is beyond the length of the string then the string is
876     expanded with QChar::null.
877 */
878
879 /*
880   Internal chunk of code to handle the
881   uncommon cases of at() above.
882 */
883 void SecQString::subat( uint i )
884 {
885     uint olen = d->len;
886     if ( i >= olen ) {
887         setLength( i+1 );               // i is index; i+1 is needed length
888         for ( uint j=olen; j<=i; j++ )
889             d->unicode[j] = QChar::null;
890     } else {
891         // Just be sure to detach
892         real_detach();
893     }
894 }
895
896
897 /*! \internal
898  */
899 bool SecQString::isRightToLeft() const
900 {
901     int len = length();
902     QChar *p = d->unicode;
903     while ( len-- ) {
904         switch( ::direction( *p ) )
905         {
906         case QChar::DirL:
907         case QChar::DirLRO:
908         case QChar::DirLRE:
909             return FALSE;
910         case QChar::DirR:
911         case QChar::DirAL:
912         case QChar::DirRLO:
913         case QChar::DirRLE:
914             return TRUE;
915         default:
916             break;
917         }
918         ++p;
919     }
920     return FALSE;
921 }
922
923
924 /*!
925     \fn const SecQString operator+( const SecQString &s1, const SecQString &s2 )
926
927     \relates SecQString
928
929     Returns a string which is the result of concatenating the string
930     \a s1 and the string \a s2.
931
932     Equivalent to \a {s1}.append(\a s2).
933 */
934
935
936 /*! \fn void SecQString::detach()
937   If the string does not share its data with another SecQString instance,
938   nothing happens; otherwise the function creates a new, unique copy of
939   this string. This function is called whenever the string is modified. The
940   implicit sharing mechanism is implemented this way.
941 */
942