1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  String class

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef USTRING_H

    22 #define USTRING_H

    23 

    24 #include <osn/osndefines.h>

    25 #include <stdexcept>

    26 #include <memory>

    27 #include <string>

    28 

    29 using namespace std;

    30 

    31 namespace osncore

    32 {

    33 

    34 class UStringImpl;

    35 

    36 typedef char Utf8;

    37 typedef unsigned short Utf16;

    38 typedef unsigned long Unicode;

    39 

    40 /**

    41  *  @class UString ustring.h "osn/ustring.h"

    42  *  Class encapsulates utf-8 encoded string. UString has a character based API thus

    43  *  e.g length will return number of charaters. Unicode operations for utf8 encoded

    44  *  string can be done using glib unicode manipulation functions and/or using non-member functions for

    45  *  UString type.

    46  *

    47  *  @lib osncore.lib

    48  *  @since S60 5.0

    49  *  @status Draft

    50  *  @interfaces UString

    51  */

    52 class UString

    53     {

    54 public:

    55     /**

    56      * UString exception class

    57      * @since S60 5.0

    58      */

    59     class InvalidUtf8: public invalid_argument

    60         {

    61     public:

    62 

    63         InvalidUtf8(): invalid_argument("invalid"){}

    64         /**

    65          * Gets the invalid utf string

    66          * @since S60 5.0

    67          * @return the class name (InvalidUtf8) as a C-style string.

    68          */

    69         OSN_IMPORT virtual const char* what()const throw();

    70         };

    71 public:

    72     /**

    73      * Default constructor.

    74      */

    75     OSN_IMPORT UString();

    76 

    77     /**

    78      * Construct a UString as a copy of given null terminated string.

    79      *

    80      * @since S60 5.0

    81      * @exception std::bad_alloc

    82      * @param aStr Utf-8 encoded string

    83      */

    84     OSN_IMPORT explicit UString(const Utf8* aStr);

    85 

    86     /**

    87      * Construct a UString as a copy of given string

    88      * with byte length of the source buffer.

    89      * Because a length is provided, source doesn't need to be null terminated.

    90      *

    91      * @since S60 5.0

    92      * @exception std::bad_alloc

    93      * @param aStr Utf-8 encoded string

    94      * @param aByteCount Byte count of Utf-8 encoded string

    95      */

    96     OSN_IMPORT explicit UString(const Utf8* aStr, int aByteCount);

    97 

    98     /**

    99      * Construct a UString from unicode code point. If Unicode is invalid,

   100      * @since S60 5.0

   101      * @exception std::bad_alloc

   102      * @param aCodePoint Unicode code point

   103      */

   104     OSN_IMPORT explicit UString(Unicode aCodePoint);

   105 

   106     /**

   107      * UString copy constructor

   108      * @since S60 5.0

   109      * @exception std::bad_alloc

   110      * @param aUString Copy source

   111      */

   112     OSN_IMPORT UString(const UString& aUString);

   113 

   114     /**

   115      * Copy assignment

   116      *

   117      * @since S60 5.0

   118      * @param aRhs Assignment source

   119      */

   120     OSN_IMPORT UString& operator=(const UString& aRhs);

   121 

   122     /**

   123      * Copy assignment

   124      *

   125      * @since S60 5.0

   126      * @param aRhs Assignment source

   127      */

   128     OSN_IMPORT UString& operator=(const Utf8* aRhs);

   129 

   130     /**

   131      * Destructor.

   132      */

   133     OSN_IMPORT virtual ~UString();

   134 

   135     /**

   136      * Checks whether string is empty.

   137      *

   138      * @since S60 5.0

   139      * @return True if string doesn't have content.

   140      */

   141     OSN_IMPORT bool isEmpty()const;

   142 

   143     /**

   144      * Returns the length of the string in characters.

   145      *

   146      * @since S60 5.0

   147      * @return Length

   148      */

   149     OSN_IMPORT long getCharLength()const;

   150 

   151     /**

   152      * Returns the length of the string in bytes

   153      *

   154      * @since S60 5.0

   155      * @return Bytes

   156      */

   157     OSN_IMPORT long getByteLength()const;

   158 

   159     /**

   160      * Returns utf8 type string

   161      *

   162      * @since S60 5.0

   163      * @return utf8 type string

   164      */

   165     OSN_IMPORT const Utf8* getUtf8()const;

   166 

   167     /**

   168      * Compares two strings using strcmp(). Note that this is not linguistic comparison nor case insensitive.

   169      *

   170      * @since S60 5.0

   171      * @param aUString UString object to compare

   172      * @return < 0 if this compares before aRhs, 0 if they compare equal, > 0 if this compares after aRhs.

   173      */

   174     OSN_IMPORT int compare(const UString& aUString)const;

   175 

   176     /**

   177      * Compares two strings using strcmp(). Note that this is not linguistic comparison nor case insensitive.

   178      *

   179      * @since S60 5.0

   180      * @param aStr String to compare

   181      * @return < 0 if this compares before aRhs, 0 if they compare equal, > 0 if this compares after aRhs.

   182      */

   183     OSN_IMPORT int compare(const Utf8* aStr)const;

   184 

   185     /**

   186      * Compares two strings for ordering using the linguistically correct rules for the current locale.

   187      * When sorting a large number of strings, it will be significantly faster

   188      * to obtain collation keys with g_utf8_collate_key()from libglib and compare the keys

   189      * with strcmp() when sorting instead of sorting the original strings.

   190      *

   191      * @since S60 5.0

   192      * @param aUString UString object to compare

   193      * @return < 0 if this compares before aRhs, 0 if they compare equal, > 0 if this compares after aRhs.

   194      */

   195     OSN_IMPORT int compareC(const UString& aUString)const;

   196 

   197     /**

   198      * Compares two strings for ordering using the linguistically correct rules for the current locale.

   199      * When sorting a large number of strings, it will be significantly faster

   200      * to obtain collation keys with g_utf8_collate_key() from libglib and compare the keys

   201      * with strcmp() when sorting instead of sorting the original strings.

   202      * If aStr is invalid utf8, UString::InvalidUtf8 exception is thrown.

   203      *

   204      *

   205      * @since S60 5.0

   206      * @param aStr String to compare

   207      * @return < 0 if this compares before aRhs, 0 if they compare equal, > 0 if this compares after aRhs.

   208      */

   209     OSN_IMPORT int compareC(const Utf8* aStr)const;

   210 

   211 

   212     /**

   213      * Compares two strings using strcmp()

   214      *

   215      * @since S60 5.0

   216      * @param aRhs UString object to compare

   217      * @return true if they compare equal.

   218      */

   219     OSN_IMPORT bool operator==(const UString& aRhs)const;

   220 

   221     /**

   222      * Compares two strings using strcmp()

   223      *

   224      * @since S60 5.0

   225      * @param aRhs String to compare

   226      * @return true if they compare equal.

   227      */

   228     OSN_IMPORT bool operator==(const Utf8* aRhs) const;

   229 

   230     /**

   231      * Adds a string onto the end of string, expanding it if necessary.

   232      *

   233      * @since S60 5.0

   234      * @exception std::bad_alloc

   235      * @param aUString String object to append

   236      */

   237     OSN_IMPORT void append(const UString& aUString);

   238 

   239     /**

   240      * Adds a string onto the end of string, expanding it if necessary.

   241      *

   242      * @since S60 5.0

   243      * @exception std::bad_alloc

   244      * @param aStr String to append

   245      */

   246     OSN_IMPORT void append(const Utf8* aStr);

   247 

   248     /**

   249      * Inserts aStr into string, expanding it if necessary.

   250      * If aPos is -1, bytes are inserted at the end of the string.

   251      *

   252      * @since S60 5.0

   253      * @exception std::bad_alloc

   254      * @exception std:out_of_range is thrown if given position is invalid

   255      * @param aPos The character position to insert the copy of the string

   256      * @param aStr The string to insert

   257      */

   258     OSN_IMPORT void insert(long aPos, const Utf8* aStr);

   259 

   260     /**

   261      * Inserts aStr into string, expanding it if necessary. Because length is

   262      * provided, aStr may contain embedded nulls and need not be null terminated.

   263      * If aPos is -1, bytes are inserted at the end of the string.

   264      *

   265      * @since S60 5.0

   266      * @exception std::bad_alloc

   267      * @exception std:out_of_range is thrown if given position is invalid

   268      * @param aPos The character position to insert the copy of the string

   269      * @param aStr The string to insert

   270      * @param aCharCount Character count.

   271      */

   272     OSN_IMPORT void insert(long aPos, const Utf8* aStr, long aCharCount);

   273 

   274     /**

   275      * Replace a substring with a given string, expanding it if necessary

   276      *

   277      * @since S60 5.0

   278      * @exception std::bad_alloc

   279      * @exception std:out_of_range is thrown if given position is invalid

   280      * @param aPos The charater position to replace the string

   281      * @param aStr The string to insert

   282      */

   283     OSN_IMPORT void replace(long aPos, const Utf8* aStr);

   284 

   285     /**

   286      * Replace a substring with a given string, expanding it if necessary. Because length is

   287      * provided, aStr may contain embedded nulls and need not be null terminated.

   288      * If aLength is < 0, length is assumed to be aStr's length.

   289      *

   290      * @since S60 5.0

   291      * @exception std::bad_alloc

   292      * @exception std:out_of_range is thrown if given position is invalid

   293      * @param aPos The character position to replace the string

   294      * @param aStr The string to insert

   295      * @param aCharCount Character count.

   296      */

   297     OSN_IMPORT void replace(long aPos, const Utf8* aStr, long aCharCount);

   298 

   299     /**

   300      * Erase a substring

   301      *

   302      * @since S60 5.0

   303      * @exception std:out_of_range is thrown if given position is invalid

   304      * @param aPos The character position to start erasing from

   305      * @param aCharCount number of characters to erase.

   306      */

   307     OSN_IMPORT void erase(long aPos, long aCharCount);

   308 

   309     /**

   310      * Returns unicode at given position in string

   311      *

   312      * @since S60 5.0

   313      * @exception std:out_of_range is thrown if given position is invalid

   314      * @param aPos The requested position

   315      */

   316     OSN_IMPORT Unicode operator[](long aPos);

   317 

   318     /**

   319      * Checks whether string is null.

   320      *

   321      * @since S60 5.0

   322      * @return True if string is null.

   323      */

   324     OSN_IMPORT bool isNull()const;

   325 

   326 private: // data

   327 

   328     /**

   329      * Implementation.

   330      */

   331     auto_ptr<UStringImpl> mImpl;

   332     };

   333 

   334 

   335 /**

   336  *  @class UtfProxy ustring.h "osn/ustring.h"

   337  *  Proxy class to ease utf encoded string memory management.

   338  *

   339  *  @lib osncore.lib

   340  *  @since S60 5.0

   341  *  @status Draft

   342  */

   343 template<typename T>

   344 class UtfProxy

   345     {

   346 public:

   347     /**

   348      * Constructor for templated UtfProxy class

   349      */

   350     explicit UtfProxy(T* aString):iUtf(aString){}

   351 

   352     /**

   353      * Destructor

   354      */

   355     OSN_IMPORT ~UtfProxy();

   356  

   357     /**

   358      * Raw data

   359      *

   360      * @return const pointer to templated class

   361      * @since S60 5.0

   362      */

   363     const T* getUtf()const{return iUtf;}

   364 private:

   365     /**

   366      * Default constructor disabled

   367      */

   368     UtfProxy();

   369     /**

   370      * Copy constructor disabled

   371      */

   372     UtfProxy(const UtfProxy& a);

   373     /**

   374      * Assignment disabled

   375      */

   376     UtfProxy& operator=(const UtfProxy& a);

   377 

   378 private:

   379     /**

   380      * pointer to templated class

   381      */

   382     T* iUtf;

   383     };

   384 

   385 typedef UtfProxy<Utf16> Utf16Proxy;

   386 typedef UtfProxy<Utf8> Utf8Proxy;

   387 

   388 // Non member functions for UString type

   389 

   390 /**

   391  * Convert a string from UTF-8 to UTF-16. A 0 word will be added to the result after the converted text.

   392  *

   393  * @since S60 5.0

   394  * @param aSourceUtf8 Non empty string object.

   395  * @return auto_ptr to proxy object holding converted string.

   396  */

   397 OSN_IMPORT auto_ptr<Utf16Proxy> toUtf16(const UString& aSourceUtf8);

   398 

   399 /**

   400  * Converts a string to int.If no conversion could be performed, UString::InvalidUtf8 exception is returned.

   401  *

   402  * @since S60 5.0

   403  * @param aSource source string

   404  * @return integer

   405  */

   406 OSN_IMPORT int toInt(const UString& aSource);

   407 

   408 /**

   409  * Normalize a unnormalized text. Characters are decomposed by canonical equivalence e.g û -> u^

   410  *

   411  * @since S60 5.0

   412  * @param aSource source string

   413  * @return auto_ptr holding UString object.

   414  */

   415 OSN_IMPORT auto_ptr<UString> normalizeNFD(const UString& aSource);

   416 

   417 /**

   418  * Normalize a unnormalized text. Does canonical decomposition,followed by canonical composition.

   419  * Resulting text is to be a canonical equivalent to the original unnormalized text.

   420  *

   421  * @since S60 5.0

   422  * @param aSource source string

   423  * @return auto_ptr holding UString object.

   424  */

   425 OSN_IMPORT auto_ptr<UString> normalizeNFC(const UString& aSource);

   426 

   427 /**

   428  * Normalize a unnormalized text. Does compatibility decomposition.

   429  * Resulting text is to be a compatibility equivalent to the original unnormalized text.

   430  *

   431  * @since S60 5.0

   432  * @param aSource source string

   433  * @return auto_ptr holding UString object.

   434  */

   435 OSN_IMPORT auto_ptr<UString> normalizeNFKD(const UString& aSource);

   436 

   437 /**

   438  * Normalize a unnormalized text. Does compatibility decomposition,followed by compatibility composition.

   439  * Resulting text is to be a compatibility equivalent to the original unnormalized text.

   440  *

   441  * @since S60 5.0

   442  * @param aSource source string

   443  * @return auto_ptr holding UString object.

   444  */

   445 OSN_IMPORT auto_ptr<UString> normalizeNFKC(const UString& aSource);

   446 }

   447 

   448 

   449 #endif