1 /*

     2 * Copyright (c) 2009 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: 

    15 *

    16 */

    17 /*

    18  * Licensed to the Apache Software Foundation (ASF) under one or more

    19  * contributor license agreements.  See the NOTICE file distributed with

    20  * this work for additional information regarding copyright ownership.

    21  * The ASF licenses this file to You under the Apache License, Version 2.0

    22  * (the "License"); you may not use this file except in compliance with

    23  * the License.  You may obtain a copy of the License at

    24  * 

    25  *      http://www.apache.org/licenses/LICENSE-2.0

    26  * 

    27  * Unless required by applicable law or agreed to in writing, software

    28  * distributed under the License is distributed on an "AS IS" BASIS,

    29  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    30  * See the License for the specific language governing permissions and

    31  * limitations under the License.

    32  */

    33 

    34 /*

    35  * $Id: XMLString.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #if !defined(XMLSTRING_HPP)

    39 #define XMLSTRING_HPP

    40 

    41 #include <xercesc/util/BaseRefVectorOf.hpp>

    42 #include <xercesc/framework/XMLBuffer.hpp>

    43 #include <xercesc/framework/MemoryManager.hpp>

    44 #include <string.h>

    45 #include <assert.h>

    46 

    47 XERCES_CPP_NAMESPACE_BEGIN

    48 

    49 class XMLLCPTranscoder;

    50 /**

    51   * Class for representing native character strings and handling common string

    52   * operations

    53   *

    54   * This class is Unicode compliant. This class is designed primarily

    55   * for internal use, but due to popular demand, it is being made

    56   * publicly available. Users of this class must understand that this

    57   * is not an officially supported class. All public methods of this

    58   * class are <i>static functions</i>.

    59   *

    60   */

    61 class XMLUTIL_EXPORT XMLString

    62 {

    63 public:

    64     /* Static methods for native character mode string manipulation */

    65 

    66 

    67     /** @name String concatenation functions */

    68     //@{

    69     /** Concatenates two strings.

    70       *

    71       * <code>catString</code> appends <code>src</code> to <code>target</code> and

    72       * terminates the resulting string with a null character. The initial character

    73       * of <code>src</code> overwrites the terminating character of <code>target

    74       * </code>.

    75       *

    76       * No overflow checking is performed when strings are copied or appended.

    77       * The behavior of <code>catString</code> is undefined if source and

    78       * destination strings overlap.

    79       *

    80       * @param target Null-terminated destination string

    81       * @param src Null-terminated source string

    82       */

    83     static void catString

    84     (

    85                 char* const     target

    86         , const char* const     src

    87     );

    88 

    89     /** Concatenates two strings.

    90       *

    91       * <code>catString</code> appends <code>src</code> to <code>target</code> and

    92       * terminates the resulting string with a null character. The initial character of

    93       * <code>src</code> overwrites the terminating character of <code>target</code>.

    94       * No overflow checking is performed when strings are copied or appended.

    95       * The behavior of <code>catString</code> is undefined if source and destination

    96       * strings overlap.

    97       *

    98       * @param target Null-terminated destination string

    99       * @param src Null-terminated source string

   100       */

   101     static void catString

   102     (

   103                 XMLCh* const    target

   104         , const XMLCh* const    src

   105     );

   106     //@}

   107 

   108     /** @name String comparison functions */

   109     //@{

   110     /** Lexicographically compares lowercase versions of <code>str1</code> and

   111       * <code>str2</code> and returns a value indicating their relationship.

   112       * @param str1 Null-terminated string to compare

   113       * @param str2 Null-terminated string to compare

   114       *

   115       * @return The return value indicates the relation of <code>str1</code> to

   116       * <code>str2</code> as follows

   117       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   118       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   119       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   120       */

   121     static int compareIString

   122     (

   123         const   char* const     str1

   124         , const char* const     str2

   125     );

   126 

   127     /** Lexicographically compares lowercase versions of <code>str1</code> and

   128       * <code>str2</code> and returns a value indicating their relationship.

   129       * @param str1 Null-terminated string to compare

   130       * @param str2 Null-terminated string to compare

   131       * @return The return value indicates the relation of <code>str1</code> to

   132       * <code>str2</code> as follows

   133       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   134       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   135       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   136       */

   137     static int compareIString

   138     (

   139         const   XMLCh* const    str1

   140         , const XMLCh* const    str2

   141     );

   142 

   143     /** Lexicographically compares lowercase versions of <code>str1</code> and

   144       * <code>str2</code> and returns a value indicating their relationship.

   145       * The routine only lowercases A to Z.

   146       * @param str1 Null-terminated ASCII string to compare

   147       * @param str2 Null-terminated ASCII string to compare

   148       * @return The return value indicates the relation of <code>str1</code> to

   149       * <code>str2</code> as follows

   150       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   151       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   152       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   153       */

   154     static int compareIStringASCII

   155     (

   156         const   XMLCh* const    str1

   157         , const XMLCh* const    str2

   158     );

   159 

   160 

   161 

   162     /** Lexicographically compares, at most, the first count characters in

   163       * <code>str1</code> and <code>str2</code> and returns a value indicating the

   164       * relationship between the substrings.

   165       * @param str1 Null-terminated string to compare

   166       * @param str2 Null-terminated string to compare

   167       * @param count The number of characters to compare

   168       *

   169       * @return The return value indicates the relation of <code>str1</code> to

   170       * <code>str2</code> as follows

   171       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   172       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   173       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   174       */

   175     static int compareNString

   176     (

   177         const   char* const     str1

   178         , const char* const     str2

   179         , const unsigned int    count

   180     );

   181 

   182     /** Lexicographically compares, at most, the first count characters in

   183       * <code>str1</code> and <code>str2</code> and returns a value indicating

   184       * the relationship between the substrings.

   185       * @param str1 Null-terminated string to compare

   186       * @param str2 Null-terminated string to compare

   187       * @param count The number of characters to compare

   188       *

   189       * @return The return value indicates the relation of <code>str1</code> to

   190       * <code>str2</code> as follows

   191       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   192       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   193       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   194       */

   195     static int compareNString

   196     (

   197         const   XMLCh* const    str1

   198         , const XMLCh* const    str2

   199         , const unsigned int    count

   200     );

   201 

   202 

   203     /** Lexicographically compares, at most, the first count characters in

   204       * <code>str1</code> and <code>str2</code> without regard to case and

   205       * returns a value indicating the relationship between the substrings.

   206       *

   207       * @param str1 Null-terminated string to compare

   208       * @param str2 Null-terminated string to compare

   209       * @param count The number of characters to compare

   210       * @return The return value indicates the relation of <code>str1</code> to

   211       * <code>str2</code> as follows

   212       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   213       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   214       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   215       */

   216     static int compareNIString

   217     (

   218         const   char* const     str1

   219         , const char* const     str2

   220         , const unsigned int    count

   221     );

   222 

   223     /** Lexicographically compares, at most, the first count characters in

   224       * <code>str1</code> and <code>str2</code> without regard to case and

   225       * returns a value indicating the relationship between the substrings.

   226       *

   227       * @param str1 Null-terminated string to compare

   228       * @param str2 Null-terminated string to compare

   229       * @param count The number of characters to compare

   230       *

   231       * @return The return value indicates the relation of <code>str1</code> to

   232       * <code>str2</code> as follows

   233       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   234       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   235       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   236       */

   237     static int compareNIString

   238     (

   239         const   XMLCh* const    str1

   240         , const XMLCh* const    str2

   241         , const unsigned int    count

   242     );

   243 

   244     /** Lexicographically compares <code>str1</code> and <code>str2</code> and

   245       * returns a value indicating their relationship.

   246       *

   247       * @param str1 Null-terminated string to compare

   248       * @param str2 Null-terminated string to compare

   249       *

   250       * @return The return value indicates the relation of <code>str1</code> to

   251       * <code>str2</code> as follows

   252       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   253       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   254       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   255       */

   256     static int compareString

   257     (

   258         const   char* const     str1

   259         , const char* const     str2

   260     );

   261 

   262     /** Lexicographically compares <code>str1</code> and <code>str2</code> and

   263       * returns a value indicating their relationship.

   264       *

   265       * @param str1 Null-terminated string to compare

   266       * @param str2 Null-terminated string to compare

   267       * @return The return value indicates the relation of <code>str1</code> to

   268       * <code>str2</code> as follows

   269       *  Less than 0 means <code>str1</code> is less than <code>str2</code>

   270       *  Equal to 0 means <code>str1</code> is identical to <code>str2</code>

   271       *  Greater than 0 means <code>str1</code> is more than <code>str2</code>

   272       */

   273     static int compareString

   274     (

   275         const   XMLCh* const    str1

   276         , const XMLCh* const    str2

   277     );

   278 

   279     /** compares <code>str1</code> and <code>str2</code>

   280       *

   281       * @param str1 Null-terminated string to compare

   282       * @param str2 Null-terminated string to compare

   283       * @return true if two strings are equal, false if not

   284       *  If one string is null, while the other is zero-length string,

   285       *  it is considered as equal.

   286       */

   287     static bool equals

   288     (

   289           const XMLCh* const    str1

   290         , const XMLCh* const    str2

   291     );

   292 

   293     static bool equals

   294     (

   295           const char* const    str1

   296         , const char* const    str2

   297     );

   298 

   299 	/** Lexicographically compares <code>str1</code> and <code>str2</code>

   300 	  * regions and returns true if they are equal, otherwise false.

   301 	  *

   302       * A substring of <code>str1</code> is compared to a substring of

   303 	  * <code>str2</code>. The result is true if these substrings represent

   304 	  * identical character sequences. The substring of <code>str1</code>

   305       * to be compared begins at offset1 and has length charCount. The

   306 	  * substring of <code>str2</code> to be compared begins at offset2 and

   307 	  * has length charCount. The result is false if and only if at least

   308       * one of the following is true:

   309       *   offset1 is negative.

   310       *   offset2 is negative.

   311       *   offset1+charCount is greater than the length of str1.

   312       *   offset2+charCount is greater than the length of str2.

   313       *   There is some nonnegative integer k less than charCount such that:

   314       *   str1.charAt(offset1+k) != str2.charAt(offset2+k)

   315       *

   316       * @param str1 Null-terminated string to compare

   317 	  * @param offset1 Starting offset of str1

   318       * @param str2 Null-terminated string to compare

   319 	  * @param offset2 Starting offset of str2

   320 	  * @param charCount The number of characters to compare

   321       * @return true if the specified subregion of <code>str1</code> exactly

   322 	  *  matches the specified subregion of <code>str2></code>; false

   323 	  *  otherwise.

   324       */

   325     static bool regionMatches

   326     (

   327         const   XMLCh* const    str1

   328 		, const	int				offset1

   329         , const XMLCh* const    str2

   330 		, const int				offset2

   331 		, const unsigned int	charCount

   332     );

   333 

   334 	/** Lexicographically compares <code>str1</code> and <code>str2</code>

   335 	  * regions without regard to case and returns true if they are equal,

   336 	  * otherwise false.

   337 	  *

   338       * A substring of <code>str1</code> is compared to a substring of

   339 	  * <code>str2</code>. The result is true if these substrings represent

   340 	  * identical character sequences. The substring of <code>str1</code>

   341       * to be compared begins at offset1 and has length charCount. The

   342 	  * substring of <code>str2</code> to be compared begins at offset2 and

   343 	  * has length charCount. The result is false if and only if at least

   344       * one of the following is true:

   345       *   offset1 is negative.

   346       *   offset2 is negative.

   347       *   offset1+charCount is greater than the length of str1.

   348       *   offset2+charCount is greater than the length of str2.

   349       *   There is some nonnegative integer k less than charCount such that:

   350       *   str1.charAt(offset1+k) != str2.charAt(offset2+k)

   351       *

   352       * @param str1 Null-terminated string to compare

   353 	  * @param offset1 Starting offset of str1

   354       * @param str2 Null-terminated string to compare

   355 	  * @param offset2 Starting offset of str2

   356 	  * @param charCount The number of characters to compare

   357       * @return true if the specified subregion of <code>str1</code> exactly

   358 	  *  matches the specified subregion of <code>str2></code>; false

   359 	  *  otherwise.

   360       */

   361     static bool regionIMatches

   362     (

   363         const   XMLCh* const    str1

   364 		, const	int				offset1

   365         , const XMLCh* const    str2

   366 		, const int				offset2

   367 		, const unsigned int	charCount

   368     );

   369     //@}

   370 

   371     /** @name String copy functions */

   372     //@{

   373     /** Copies <code>src</code>, including the terminating null character, to the

   374       * location specified by <code>target</code>.

   375       *

   376       * No overflow checking is performed when strings are copied or appended.

   377       * The behavior of strcpy is undefined if the source and destination strings

   378       * overlap.

   379       *

   380       * @param target Destination string

   381       * @param src Null-terminated source string

   382       */

   383     static void copyString

   384     (

   385                 char* const     target

   386         , const char* const     src

   387     );

   388 

   389     /** Copies <code>src</code>, including the terminating null character, to

   390       *   the location specified by <code>target</code>.

   391       *

   392       * No overflow checking is performed when strings are copied or appended.

   393       * The behavior of <code>copyString</code> is undefined if the source and

   394       * destination strings overlap.

   395       *

   396       * @param target Destination string

   397       * @param src Null-terminated source string

   398       */

   399     static void copyString

   400     (

   401                 XMLCh* const    target

   402         , const XMLCh* const    src

   403     );

   404 

   405     /** Copies <code>src</code>, upto a fixed number of characters, to the

   406       * location specified by <code>target</code>.

   407       *

   408       * No overflow checking is performed when strings are copied or appended.

   409       * The behavior of <code>copyNString</code> is undefined if the source and

   410       * destination strings overlap.

   411       *

   412       * @param target Destination string. The size of the buffer should

   413       *        atleast be 'maxChars + 1'.

   414       * @param src Null-terminated source string

   415       * @param maxChars The maximum number of characters to copy

   416       */

   417     static bool copyNString

   418     (

   419                 XMLCh* const    target

   420         , const XMLCh* const    src

   421         , const unsigned int    maxChars

   422     );

   423     //@}

   424 

   425     /** @name Hash functions */

   426     //@{

   427     /** Hashes a string given a modulus

   428       *

   429       * @param toHash The string to hash

   430       * @param hashModulus The divisor to be used for hashing

   431       * @param manager The MemoryManager to use to allocate objects

   432       * @return Returns the hash value

   433       */

   434     static unsigned int hash

   435     (

   436         const   char* const     toHash

   437         , const unsigned int    hashModulus

   438         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   439     );

   440 

   441     /** Hashes a string given a modulus

   442       *

   443       * @param toHash The string to hash

   444       * @param hashModulus The divisor to be used for hashing

   445       * @param manager The MemoryManager to use to allocate objects

   446       * @return Returns the hash value

   447       */

   448     static unsigned int hash

   449     (

   450         const   XMLCh* const    toHash

   451         , const unsigned int    hashModulus

   452         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   453     );

   454 

   455     /** Hashes a string given a modulus taking a maximum number of characters

   456       * as the limit

   457       *

   458       * @param toHash The string to hash

   459       * @param numChars The maximum number of characters to consider for hashing

   460       * @param hashModulus The divisor to be used for hashing

   461       * @param manager The MemoryManager to use to allocate objects

   462       * @return Returns the hash value

   463       */

   464     static unsigned int hashN

   465     (

   466         const   XMLCh* const    toHash

   467         , const unsigned int    numChars

   468         , const unsigned int    hashModulus

   469         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager

   470     );

   471 

   472     //@}

   473 

   474     /** @name Search functions */

   475     //@{

   476     /**

   477       * Provides the index of the first occurance of a character within a string

   478       *

   479       * @param toSearch The string to search

   480       * @param ch The character to search within the string

   481       * @return If found, returns the index of the character within the string,

   482       * else returns -1.

   483       */

   484     static int indexOf(const char* const toSearch, const char ch);

   485 

   486     /**

   487       * Provides the index of the first occurance of a character within a string

   488       *

   489       * @param toSearch The string to search

   490       * @param ch The character to search within the string

   491       * @return If found, returns the index of the character within the string,

   492       * else returns -1.

   493       */

   494     static int indexOf(const XMLCh* const toSearch, const XMLCh ch);

   495 

   496 	    /**

   497       * Provides the index of the first occurance of a character within a string

   498       * starting from a given index

   499       *

   500       * @param toSearch The string to search

   501       * @param chToFind The character to search within the string

   502       * @param fromIndex The index to start searching from

   503       * @param manager The MemoryManager to use to allocate objects

   504       * @return If found, returns the index of the character within the string,

   505       * else returns -1.

   506       */

   507     static int indexOf

   508     (

   509         const   char* const     toSearch

   510         , const char            chToFind

   511         , const unsigned int    fromIndex

   512         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   513     );

   514 

   515     /**

   516       * Provides the index of the first occurance of a character within a string

   517       * starting from a given index

   518       *

   519       * @param toSearch The string to search

   520       * @param chToFind The character to search within the string

   521       * @param fromIndex The index to start searching from

   522       * @param manager The MemoryManager to use to allocate objects

   523       * @return If found, returns the index of the character within the string,

   524       * else returns -1.

   525       */

   526     static int indexOf

   527     (

   528         const   XMLCh* const    toSearch

   529         , const XMLCh           chToFind

   530         , const unsigned int    fromIndex

   531         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   532     );

   533 

   534     /**

   535       * Provides the index of the last occurance of a character within a string

   536       *

   537       * @param toSearch The string to search

   538       * @param ch The character to search within the string

   539       * @return If found, returns the index of the character within the string,

   540       * else returns -1.

   541       */

   542     static int lastIndexOf(const char* const toSearch, const char ch);

   543 

   544     /**

   545       * Provides the index of the last occurance of a character within a string

   546       *

   547       * @param toSearch The string to search

   548       * @param ch The character to search within the string

   549       * @return If found, returns the index of the character within the string,

   550       * else returns -1.

   551       */

   552     static int lastIndexOf(const XMLCh* const toSearch, const XMLCh ch);

   553 

   554     /**

   555       * Provides the index of the last occurance of a character within a string

   556       *

   557       * @param ch The character to search within the string

   558       * @param toSearch The string to search

   559       * @param toSearchLen The length of the string to search

   560       * @return If found, returns the index of the character within the string,

   561       * else returns -1.

   562       */

   563     static int lastIndexOf

   564     (

   565         const XMLCh ch

   566         , const XMLCh* const toSearch

   567         , const unsigned int toSearchLen

   568     );

   569 

   570     /**

   571       * Provides the index of the last occurance of a character within a string

   572       * starting backward from a given index

   573       *

   574       * @param toSearch The string to search

   575       * @param chToFind The character to search within the string

   576       * @param fromIndex The index to start backward search from

   577       * @param manager The MemoryManager to use to allocate objects

   578       * @return If found, returns the index of the character within the string,

   579       * else returns -1.

   580       */

   581     static int lastIndexOf

   582     (

   583         const   char* const     toSearch

   584         , const char            chToFind

   585         , const unsigned int    fromIndex

   586         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   587     );

   588 

   589     /**

   590       * Provides the index of the last occurance of a character within a string

   591       * starting backward from a given index

   592       *

   593       * @param toSearch The string to search

   594       * @param ch       The character to search within the string

   595       * @param fromIndex The index to start backward search from

   596       * @param manager The MemoryManager to use to allocate objects

   597       * @return If found, returns the index of the character within the string,

   598       * else returns -1.

   599       */

   600     static int lastIndexOf

   601     (

   602         const   XMLCh* const    toSearch

   603         , const XMLCh           ch

   604         , const unsigned int    fromIndex

   605         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   606     );

   607     //@}

   608 

   609     /** @name Fixed size string movement */

   610     //@{

   611     /** Moves X number of chars

   612       * @param targetStr The string to copy the chars to

   613       * @param srcStr The string to copy the chars from

   614       * @param count The number of chars to move

   615       */

   616     static void moveChars

   617     (

   618                 XMLCh* const    targetStr

   619         , const XMLCh* const    srcStr

   620         , const unsigned int    count

   621     );

   622 

   623     //@}

   624 

   625     /** @name Substring function */

   626     //@{

   627     /** Create a substring of a given string. The substring begins at the

   628       * specified beginIndex and extends to the character at index

   629       * endIndex - 1.

   630       * @param targetStr The string to copy the chars to

   631       * @param srcStr The string to copy the chars from

   632       * @param startIndex beginning index, inclusive.

   633       * @param endIndex the ending index, exclusive.

   634       * @param manager The MemoryManager to use to allocate objects

   635       */

   636     static void subString

   637     (

   638                 char* const    targetStr

   639         , const char* const    srcStr

   640         , const int            startIndex

   641         , const int            endIndex

   642         , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager

   643     );

   644 

   645     /** Create a substring of a given string. The substring begins at the

   646       * specified beginIndex and extends to the character at index

   647       * endIndex - 1.

   648       * @param targetStr The string to copy the chars to

   649       * @param srcStr The string to copy the chars from

   650       * @param startIndex beginning index, inclusive.

   651       * @param endIndex the ending index, exclusive.

   652       * @param manager The MemoryManager to use to allocate objects

   653       */

   654     static void subString

   655     (

   656                 XMLCh* const    targetStr

   657         , const XMLCh* const    srcStr

   658         , const int             startIndex

   659         , const int             endIndex

   660         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   661     );

   662 

   663     /** Create a substring of a given string. The substring begins at the

   664       * specified beginIndex and extends to the character at index

   665       * endIndex - 1.

   666       * @param targetStr The string to copy the chars to

   667       * @param srcStr The string to copy the chars from

   668       * @param startIndex beginning index, inclusive.

   669       * @param endIndex the ending index, exclusive.

   670       * @param srcStrLength the length of srcStr

   671       * @param manager The MemoryManager to use to allocate objects

   672       */

   673     static void subString

   674     (

   675                 XMLCh* const    targetStr

   676         , const XMLCh* const    srcStr

   677         , const int             startIndex

   678         , const int             endIndex

   679         , const int             srcStrLength

   680         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   681     );

   682 

   683     //@}

   684 

   685     /** @name Replication function */

   686     //@{

   687     /** Replicates a string

   688       * NOTE: The returned buffer is dynamically allocated and is the

   689       * responsibility of the caller to delete it when not longer needed.

   690       * You can call XMLString::release to release this returned buffer.

   691       *

   692       * @param toRep The string to replicate

   693       * @return Returns a pointer to the replicated string

   694       * @see   XMLString::release(char**)

   695       */

   696     static char* replicate(const char* const toRep);

   697 

   698     /** Replicates a string

   699       * NOTE: The returned buffer is allocated with the MemoryManager. It is the

   700       * responsibility of the caller to delete it when not longer needed.

   701       *

   702       * @param toRep The string to replicate

   703       * @param manager The MemoryManager to use to allocate the string

   704       * @return Returns a pointer to the replicated string

   705       */

   706     static char* replicate(const char* const toRep,

   707                            MemoryManager* const manager);

   708 

   709     /** Replicates a string

   710       * NOTE: The returned buffer is dynamically allocated and is the

   711       * responsibility of the caller to delete it when not longer needed.

   712       * You can call XMLString::release to release this returned buffer.

   713 

   714       * @param toRep The string to replicate

   715       * @return Returns a pointer to the replicated string

   716       * @see   XMLString::release(XMLCh**)

   717       */

   718     static XMLCh* replicate(const XMLCh* const toRep);

   719 

   720     /** Replicates a string

   721       * NOTE: The returned buffer is allocated with the MemoryManager. It is the

   722       * responsibility of the caller to delete it when not longer needed.

   723       *

   724       * @param toRep The string to replicate

   725       * @param manager The MemoryManager to use to allocate the string

   726       * @return Returns a pointer to the replicated string

   727       */

   728     static XMLCh* replicate(const XMLCh* const toRep,

   729                             MemoryManager* const manager);

   730 

   731     //@}

   732 

   733     /** @name String query function */

   734     //@{

   735     /** Tells if the sub-string appears within a string at the beginning

   736       * @param toTest The string to test

   737       * @param prefix The sub-string that needs to be checked

   738       * @return Returns true if the sub-string was found at the beginning of

   739       * <code>toTest</code>, else false

   740       */

   741     static bool startsWith

   742     (

   743         const   char* const     toTest

   744         , const char* const     prefix

   745     );

   746 

   747     /** Tells if the sub-string appears within a string at the beginning

   748       * @param toTest The string to test

   749       * @param prefix The sub-string that needs to be checked

   750       * @return Returns true if the sub-string was found at the beginning of

   751       * <code>toTest</code>, else false

   752       */

   753     static bool startsWith

   754     (

   755         const   XMLCh* const    toTest

   756         , const XMLCh* const    prefix

   757     );

   758 

   759     /** Tells if the sub-string appears within a string at the beginning

   760       * without regard to case

   761       *

   762       * @param toTest The string to test

   763       * @param prefix The sub-string that needs to be checked

   764       * @return Returns true if the sub-string was found at the beginning of

   765       * <code>toTest</code>, else false

   766       */

   767     static bool startsWithI

   768     (

   769         const   char* const     toTest

   770         , const char* const     prefix

   771     );

   772 

   773     /** Tells if the sub-string appears within a string at the beginning

   774       * without regard to case

   775       *

   776       * @param toTest The string to test

   777       * @param prefix The sub-string that needs to be checked

   778       *

   779       * @return Returns true if the sub-string was found at the beginning

   780       * of <code>toTest</code>, else false

   781       */

   782     static bool startsWithI

   783     (

   784         const   XMLCh* const    toTest

   785         , const XMLCh* const    prefix

   786     );

   787 

   788     /** Tells if the sub-string appears within a string at the end.

   789       * @param toTest The string to test

   790       * @param suffix The sub-string that needs to be checked

   791       * @return Returns true if the sub-string was found at the end of

   792       * <code>toTest</code>, else false

   793       */

   794     static bool endsWith

   795     (

   796         const   XMLCh* const    toTest

   797         , const XMLCh* const    suffix

   798     );

   799 

   800 

   801     /** Tells if a string has any occurance of any character of another 

   802       * string within itself

   803       * @param toSearch The string to be searched

   804       * @param searchList The string from which characters to be searched for are drawn 

   805       * @return Returns the pointer to the location where the first occurrence of any

   806       * character from searchList is found,

   807       * else returns 0

   808       */

   809     static const XMLCh* findAny

   810     (

   811         const   XMLCh* const    toSearch

   812         , const XMLCh* const    searchList

   813     );

   814 

   815     /** Tells if a string has any occurance of any character of another 

   816       * string within itself

   817       * @param toSearch The string to be searched

   818       * @param searchList The string from which characters to be searched for are drawn 

   819       * @return Returns the pointer to the location where the first occurrence of any

   820       * character from searchList is found,

   821       * else returns 0

   822       */

   823     static XMLCh* findAny

   824     (

   825                 XMLCh* const    toSearch

   826         , const XMLCh* const    searchList

   827     );

   828 

   829     /** Tells if a string has pattern within itself

   830       * @param toSearch The string to be searched

   831       * @param pattern The pattern to be located within the string

   832       * @return Returns index to the location where the pattern was

   833       * found, else returns -1

   834       */

   835     static int patternMatch

   836     (

   837           const XMLCh* const    toSearch

   838         , const XMLCh* const    pattern

   839     );

   840 

   841     /** Get the length of the string

   842       * @param src The string whose length is to be determined

   843       * @return Returns the length of the string

   844       */

   845     static unsigned int stringLen(const char* const src);

   846 

   847     /** Get the length of the string

   848       * @param src The string whose length is to be determined

   849       * @return Returns the length of the string

   850       */

   851     static unsigned int stringLen(const XMLCh* const src);

   852 

   853     /**

   854       *

   855       * Checks whether an name is a valid NOTATION according to XML 1.0

   856       * @param name    The string to check its NOTATION validity

   857       * @param manager The memory manager

   858       * @return Returns true if name is NOTATION valid, otherwise false

   859       */

   860     static bool isValidNOTATION(const XMLCh*         const name

   861                               ,       MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager);

   862 

   863     /**

   864       * Deprecated: please use XMLChar1_0::isValidNCName

   865       *

   866       * Checks whether an name is a valid NCName according to XML 1.0

   867       * @param name The string to check its NCName validity

   868       * @return Returns true if name is NCName valid, otherwise false

   869       */

   870     static bool isValidNCName(const XMLCh* const name);

   871 

   872     /**

   873       * Deprecated: please use XMLChar1_0::isValidName

   874       *

   875       * Checks whether an name is a valid Name according to XML 1.0

   876       * @param name The string to check its Name validity

   877       * @return Returns true if name is Name valid, otherwise false

   878       */

   879     static bool isValidName(const XMLCh* const name);

   880 

   881     /**

   882       * Checks whether an name is a valid EncName.

   883       * @param name The string to check its EncName validity

   884       * @return Returns true if name is EncName valid, otherwise false

   885       */

   886     static bool isValidEncName(const XMLCh* const name);

   887 

   888     /**

   889       * Deprecated: please use XMLChar1_0::isValidQName

   890       *

   891       * Checks whether an name is a valid QName according to XML 1.0

   892       * @param name The string to check its QName validity

   893       * @return Returns true if name is QName valid, otherwise false

   894       */

   895     static bool isValidQName(const XMLCh* const name);

   896 

   897     /**

   898       * Checks whether a character is within [a-zA-Z].

   899       * @param theChar the character to check

   900       * @return Returns true if within the range, otherwise false

   901       */

   902 

   903     static bool isAlpha(XMLCh const theChar);

   904 

   905     /**

   906       * Checks whether a character is within [0-9].

   907       * @param theChar the character to check

   908       * @return Returns true if within the range, otherwise false

   909       */

   910     static bool isDigit(XMLCh const theChar);

   911 

   912     /**

   913       * Checks whether a character is within [0-9a-zA-Z].

   914       * @param theChar the character to check

   915       * @return Returns true if within the range, otherwise false

   916       */

   917     static bool isAlphaNum(XMLCh const theChar);

   918 

   919     /**

   920       * Checks whether a character is within [0-9a-fA-F].

   921       * @param theChar the character to check

   922       * @return Returns true if within the range, otherwise false

   923       */

   924     static bool isHex(XMLCh const theChar);

   925 

   926     /**

   927       * Deprecated: please use XMLChar1_0::isAllWhiteSpace

   928       *

   929       * Checks whether aa string contains only whitespace according to XML 1.0

   930       * @param toCheck the string to check

   931       * @return Returns true if it is, otherwise false

   932       */

   933     static bool isAllWhiteSpace(const XMLCh* const toCheck);

   934 

   935     /** Find is the string appears in the enum list

   936       * @param toFind the string to be found

   937       * @param enumList the list

   938       * return true if found

   939       */

   940     static bool isInList(const XMLCh* const toFind, const XMLCh* const enumList);

   941 

   942     //@}

   943 

   944     /** @name Conversion functions */

   945     //@{

   946 

   947     /** Converts binary data to a text string based a given radix

   948       *

   949       * @param toFormat The number to convert

   950       * @param toFill The buffer that will hold the output on return. The

   951       *        size of this buffer should at least be 'maxChars + 1'.

   952       * @param maxChars The maximum number of output characters that can be

   953       *         accepted. If the result will not fit, it is an error.

   954       * @param radix The radix of the input data, based on which the conversion

   955       * @param manager The MemoryManager to use to allocate objects

   956       * will be done

   957       */

   958     static void binToText

   959     (

   960         const   unsigned int    toFormat

   961         ,       char* const     toFill

   962         , const unsigned int    maxChars

   963         , const unsigned int    radix

   964         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   965     );

   966 

   967     /** Converts binary data to a text string based a given radix

   968       *

   969       * @param toFormat The number to convert

   970       * @param toFill The buffer that will hold the output on return. The

   971       *        size of this buffer should at least be 'maxChars + 1'.

   972       * @param maxChars The maximum number of output characters that can be

   973       *         accepted. If the result will not fit, it is an error.

   974       * @param radix The radix of the input data, based on which the conversion

   975       * @param manager The MemoryManager to use to allocate objects

   976       * will be done

   977       */

   978     static void binToText

   979     (

   980         const   unsigned int    toFormat

   981         ,       XMLCh* const    toFill

   982         , const unsigned int    maxChars

   983         , const unsigned int    radix

   984         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

   985     );

   986 

   987     /** Converts binary data to a text string based a given radix

   988       *

   989       * @param toFormat The number to convert

   990       * @param toFill The buffer that will hold the output on return. The

   991       *        size of this buffer should at least be 'maxChars + 1'.

   992       * @param maxChars The maximum number of output characters that can be

   993       *         accepted. If the result will not fit, it is an error.

   994       * @param radix The radix of the input data, based on which the conversion

   995       * @param manager The MemoryManager to use to allocate objects

   996       * will be done

   997       */

   998     static void binToText

   999     (

  1000         const   unsigned long   toFormat

  1001         ,       char* const     toFill

  1002         , const unsigned int    maxChars

  1003         , const unsigned int    radix

  1004         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1005     );

  1006 

  1007     /** Converts binary data to a text string based a given radix

  1008       *

  1009       * @param toFormat The number to convert

  1010       * @param toFill The buffer that will hold the output on return. The

  1011       *        size of this buffer should at least be 'maxChars + 1'.

  1012       * @param maxChars The maximum number of output characters that can be

  1013       *         accepted. If the result will not fit, it is an error.

  1014       * @param radix The radix of the input data, based on which the conversion

  1015       * @param manager The MemoryManager to use to allocate objects

  1016       * will be done

  1017       */

  1018     static void binToText

  1019     (

  1020         const   unsigned long   toFormat

  1021         ,       XMLCh* const    toFill

  1022         , const unsigned int    maxChars

  1023         , const unsigned int    radix

  1024         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1025     );

  1026 

  1027     /** Converts binary data to a text string based a given radix

  1028       *

  1029       * @param toFormat The number to convert

  1030       * @param toFill The buffer that will hold the output on return. The

  1031       *        size of this buffer should at least be 'maxChars + 1'.

  1032       * @param maxChars The maximum number of output characters that can be

  1033       *         accepted. If the result will not fit, it is an error.

  1034       * @param radix The radix of the input data, based on which the conversion

  1035       * @param manager The MemoryManager to use to allocate objects

  1036       * will be done

  1037       */

  1038     static void binToText

  1039     (

  1040         const   long            toFormat

  1041         ,       char* const     toFill

  1042         , const unsigned int    maxChars

  1043         , const unsigned int    radix

  1044         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1045     );

  1046 

  1047     /** Converts binary data to a text string based a given radix

  1048       *

  1049       * @param toFormat The number to convert

  1050       * @param toFill The buffer that will hold the output on return. The

  1051       *        size of this buffer should at least be 'maxChars + 1'.

  1052       * @param maxChars The maximum number of output characters that can be

  1053       *         accepted. If the result will not fit, it is an error.

  1054       * @param radix The radix of the input data, based on which the conversion

  1055       * @param manager The MemoryManager to use to allocate objects

  1056       * will be done

  1057       */

  1058     static void binToText

  1059     (

  1060         const   long            toFormat

  1061         ,       XMLCh* const    toFill

  1062         , const unsigned int    maxChars

  1063         , const unsigned int    radix

  1064         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1065     );

  1066 

  1067     /** Converts binary data to a text string based a given radix

  1068       *

  1069       * @param toFormat The number to convert

  1070       * @param toFill The buffer that will hold the output on return. The

  1071       *        size of this buffer should at least be 'maxChars + 1'.

  1072       * @param maxChars The maximum number of output characters that can be

  1073       *         accepted. If the result will not fit, it is an error.

  1074       * @param radix The radix of the input data, based on which the conversion

  1075       * @param manager The MemoryManager to use to allocate objects

  1076       * will be done

  1077       */

  1078     static void binToText

  1079     (

  1080         const   int             toFormat

  1081         ,       char* const     toFill

  1082         , const unsigned int    maxChars

  1083         , const unsigned int    radix

  1084         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1085     );

  1086 

  1087     /** Converts binary data to a text string based a given radix

  1088       *

  1089       * @param toFormat The number to convert

  1090       * @param toFill The buffer that will hold the output on return. The

  1091       *        size of this buffer should at least be 'maxChars + 1'.

  1092       * @param maxChars The maximum number of output characters that can be

  1093       *         accepted. If the result will not fit, it is an error.

  1094       * @param radix The radix of the input data, based on which the conversion

  1095       * @param manager The MemoryManager to use to allocate objects

  1096       * will be done

  1097       */

  1098     static void binToText

  1099     (

  1100         const   int             toFormat

  1101         ,       XMLCh* const    toFill

  1102         , const unsigned int    maxChars

  1103         , const unsigned int    radix

  1104         , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

  1105     );

  1106 

  1107     /**

  1108       * Converts a string of decimal chars to a binary value

  1109       *

  1110       * Note that leading and trailng whitespace is legal and will be ignored

  1111       * but the remainder must be all decimal digits.

  1112       *

  1113       * @param toConvert The string of digits to convert

  1114       * @param toFill    The unsigned int value to fill with the converted

  1115       *                  value.

  1116       * @param manager The MemoryManager to use to allocate objects

  1117       */

  1118     static bool textToBin

  1119     (

  1120         const   XMLCh* const    toConvert

  1121         ,       unsigned int&   toFill

  1122         ,       MemoryManager*  const manager = XMLPlatformUtils::fgMemoryManager

  1123     );

  1124 

  1125     /**

  1126       * Converts a string of decimal chars to a binary value

  1127       *

  1128       * Note that leading and trailng whitespace is legal and will be ignored,

  1129       *

  1130       * Only one and either of (+,-) after the leading whitespace, before

  1131       * any other characters are allowed.

  1132       *

  1133       * but the remainder must be all decimal digits.

  1134       *