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 implementation

    15 *

    16 */

    17 

    18 #ifndef USTRING_IMPL_H

    19 #define USTRING_IMPL_H

    20 

    21 #include <gstring.h>

    22 #include <osn/ustring.h>

    23 

    24 #define MAX_STR_LEN 24

    25 

    26 namespace osncore

    27 {

    28     

    29 class SString;

    30 

    31 /**

    32  *  Glib string wrapper.

    33  *  @see ustring.h for description of ustring

    34  *  @lib osncore.lib

    35  *  @since S60 5.0

    36  */

    37 class UStringImpl

    38 	{

    39 public:

    40     /**

    41      * Default constructor.

    42      */

    43     UStringImpl();

    44     /**

    45       * Construct a string as a copy of given null terminated string.

    46       *

    47       * @since S60 5.0

    48       * @exception std:bad_alloc is thrown if string cannot be allocated from heap

    49       * @param aStr Utf-8 encoded string

    50       */

    51     explicit UStringImpl(const Utf8* aStr);

    52     /**

    53      * Construct a string as a copy of given string

    54      * with byte length of the source buffer.

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

    56      *

    57      * @since S60 5.0

    58      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

    59      * @param aStr Utf-8 encoded string

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

    61      */

    62     explicit UStringImpl(const Utf8* aStr, int aLen);

    63     /**

    64       * Construct a string from unicode code point. If Unicode is invalid,

    65       * @exception std:bad_alloc is thrown if string cannot be allocated from heap

    66       * @since S60 5.0

    67       * @param aCodePoint Unicode code point

    68       */

    69     explicit UStringImpl(Unicode aCodePoint);

    70     

    71     /**

    72      * UStringImpl copy constructor

    73      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

    74      * @since S60 5.0

    75      * @param aUString Copy source

    76      */

    77     UStringImpl(const UStringImpl& aUStringImpl);

    78    

    79     // Destructor

    80    ~UStringImpl();

    81    

    82     // Utilities

    83    /**

    84     * Checks whether string is empty.

    85     *

    86     * @since S60 5.0

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

    88     */

    89    	bool empty()const;

    90     /**

    91      * Checks whether string is null.

    92      *

    93      * @since S60 5.0

    94      * @return True if string is null.

    95      */

    96    	bool null()const;

    97     /**

    98      * Returns the length of the string in characters.

    99      *

   100      * @since S60 5.0

   101      * @return Length

   102      */

   103    	long length()const;

   104     /**

   105      * Returns the length of the string in bytes

   106      *

   107      * @since S60 5.0

   108      * @return Bytes

   109      */

   110    	long bytes()const;

   111    	

   112     /**

   113      * Returns utf8 type string

   114      *

   115      * @since S60 5.0

   116      * @return utf8 type string

   117      */

   118    	const Utf8* utf8()const;

   119  

   120     /**

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

   122      *

   123      * @since S60 5.0

   124      * @param aUStringImpl UStringImpl object to compare

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

   126      */

   127     int compare(const UStringImpl& aUStringImpl)const;

   128     /**

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

   130      *

   131      * @since S60 5.0

   132      * @param aStr String to compare

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

   134      */

   135     int compare(const Utf8* aStr)const;

   136     /**

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

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

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

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

   141      *

   142      * @since S60 5.0

   143      * @param aUStringImpl UStringImpl object to compare

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

   145      */

   146     int compareC(const UStringImpl& aUStringImpl)const;

   147     /**

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

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

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

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

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

   153      *

   154      *

   155      * @since S60 5.0

   156      * @param aStr String to compare

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

   158      */

   159     int compareC(const Utf8* aStr)const;

   160     

   161     /**

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

   163      *

   164      * @since S60 5.0

   165      * @param aUStringImpl String object to append

   166      */

   167     void append(const UStringImpl& aUStringImpl);

   168     /**

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

   170      *

   171      * @since S60 5.0

   172      * @param aStr String to append

   173      */

   174     void append(const Utf8* aStr);

   175     

   176     /**

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

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

   179      *

   180      * @since S60 5.0

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

   182      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

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

   184      * @param aStr The string to insert

   185      */

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

   187     /**

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

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

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

   191      *

   192      * @since S60 5.0

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

   194      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

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

   196      * @param aStr The string to insert

   197      * @param aCharCount Character count.

   198      */

   199     void insert(long aPos, const Utf8* aStr, long aLength);

   200     /**

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

   202      *

   203      * @since S60 5.0

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

   205      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

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

   207      * @param aStr The string to insert

   208      */

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

   210     /**

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

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

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

   214      *

   215      * @since S60 5.0

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

   217      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

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

   219      * @param aStr The string to insert

   220      * @param aCharCount Character count.

   221      */

   222     void replace(long aPos, const Utf8* aStr, long aLength);

   223     /**

   224      * Erase a substring

   225      *

   226      * @since S60 5.0

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

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

   229      * @param aCharCount number of characters to erase.

   230      */

   231     void erase(long aPosOffset, long aLength);

   232     

   233     /**

   234      * Returns unicode at given position in string

   235      *

   236      * @since S60 5.0

   237      * @exception std:out_of_range is thrown if requested index is invalid

   238      * @param aPos The requested position

   239      */

   240     Unicode operator[](long aIndex);

   241     

   242 private:

   243     /**

   244      * Initialises internal string

   245      * @since S60 5.0

   246      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

   247      * @param aStr The string used for initialising

   248      */

   249     void initialize(const Utf8* aStr);

   250     /**

   251      * Allocates memory from heap if needed for internal string, throws if allocation fail

   252      * @since S60 5.0

   253      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

   254      * @param aLength length of bytes to allocate

   255      */

   256     void checkBuffer(unsigned int aLength);

   257     /**

   258      * Implements the insertion functionality

   259      * @since S60 5.0

   260      * @exception std:bad_alloc is thrown if string cannot be allocated from heap

   261      * @param aIndex The character position to insert the copy of the string

   262      * @param aInsertChars The string to insert

   263      * @param aInsertLength The amount of characters to insert

   264      */

   265     void insertImpl(unsigned int aIndex, const char* aInsertChars, unsigned int aInsertLength);

   266     /**

   267      * Implements the append functionality

   268      * @since S60 5.0

   269      * @param aStr The string to append

   270      * @param aLength The amount of characters to append

   271      */

   272     void appendImpl(const char* aStr, unsigned int aLength);

   273     /**

   274      * Implements the erase functionality

   275      * @since S60 5.0

   276      * @exception std:out_of_range is thrown if given index is invalid

   277      * @param aIndex The character position to start erasing from

   278      * @param aLength The amount of characters to erase

   279      */

   280     void eraseImpl(unsigned int aIndex, unsigned int aLength);

   281 private:

   282     /**

   283      * Internal buffer, allocated from heap.

   284      * Long strings are allocated from heap 

   285      */

   286 	gchar* 	str;

   287     /**

   288      * Internal buffer, allocated from stack.

   289      * Short strings are allocated from stack for performance reason, 

   290      */

   291 	gchar 	internalStr[MAX_STR_LEN];

   292     /**

   293      * length of string

   294      */

   295 	gsize   len;    

   296     /**

   297      * length of allocated bytes

   298      */

   299 	gsize   allocated_len;

   300     /**

   301      * Identifies if string is allocated from heap or not

   302      */

   303 	bool    isInHeap;

   304 	};

   305 }	

   306 

   307 #endif