/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/*

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

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

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

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

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

 * 

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

 * 

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

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

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

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

/*

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

 */

#if !defined(XMLSTRING_HPP)

#define XMLSTRING_HPP

#include <xercesc/util/BaseRefVectorOf.hpp>

#include <xercesc/framework/XMLBuffer.hpp>

#include <xercesc/framework/MemoryManager.hpp>

#include <string.h>

#include <assert.h>

XERCES_CPP_NAMESPACE_BEGIN

class XMLLCPTranscoder;

/**

  * Class for representing native character strings and handling common string

  * operations

  *

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

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

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

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

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

  *

  */

class XMLUTIL_EXPORT XMLString

{

public:

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

    /** @name String concatenation functions */

    //@{

    /** Concatenates two strings.

      *

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

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

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

      * </code>.

      *

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

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

      * destination strings overlap.

      *

      * @param target Null-terminated destination string

      * @param src Null-terminated source string

      */

    static void catString

    (

                char* const     target

        , const char* const     src

    );

    /** Concatenates two strings.

      *

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

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

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

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

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

      * strings overlap.

      *

      * @param target Null-terminated destination string

      * @param src Null-terminated source string

      */

    static void catString

    (

                XMLCh* const    target

        , const XMLCh* const    src

    );

    //@}

    /** @name String comparison functions */

    //@{

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

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

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      *

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareIString

    (

        const   char* const     str1

        , const char* const     str2

    );

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

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

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareIString

    (

        const   XMLCh* const    str1

        , const XMLCh* const    str2

    );

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

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

      * The routine only lowercases A to Z.

      * @param str1 Null-terminated ASCII string to compare

      * @param str2 Null-terminated ASCII string to compare

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareIStringASCII

    (

        const   XMLCh* const    str1

        , const XMLCh* const    str2

    );

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

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

      * relationship between the substrings.

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      * @param count The number of characters to compare

      *

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareNString

    (

        const   char* const     str1

        , const char* const     str2

        , const unsigned int    count

    );

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

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

      * the relationship between the substrings.

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      * @param count The number of characters to compare

      *

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareNString

    (

        const   XMLCh* const    str1

        , const XMLCh* const    str2

        , const unsigned int    count

    );

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

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

      * returns a value indicating the relationship between the substrings.

      *

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      * @param count The number of characters to compare

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareNIString

    (

        const   char* const     str1

        , const char* const     str2

        , const unsigned int    count

    );

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

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

      * returns a value indicating the relationship between the substrings.

      *

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      * @param count The number of characters to compare

      *

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareNIString

    (

        const   XMLCh* const    str1

        , const XMLCh* const    str2

        , const unsigned int    count

    );

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

      * returns a value indicating their relationship.

      *

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

      *

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareString

    (

        const   char* const     str1

        , const char* const     str2

    );

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

      * returns a value indicating their relationship.

      *

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

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

      * <code>str2</code> as follows

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

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

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

      */

    static int compareString

    (

        const   XMLCh* const    str1

        , const XMLCh* const    str2

    );

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

      *

      * @param str1 Null-terminated string to compare

      * @param str2 Null-terminated string to compare

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

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

      *  it is considered as equal.

      */

    static bool equals

    (

          const XMLCh* const    str1

        , const XMLCh* const    str2

    );

    static bool equals

    (

          const char* const    str1

        , const char* const    str2

    );

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

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

	  *

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

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

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

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

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

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

      * one of the following is true:

      *   offset1 is negative.

      *   offset2 is negative.

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

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

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

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

      *

      * @param str1 Null-terminated string to compare

	  * @param offset1 Starting offset of str1

      * @param str2 Null-terminated string to compare

	  * @param offset2 Starting offset of str2

	  * @param charCount The number of characters to compare

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

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

	  *  otherwise.

      */

    static bool regionMatches

    (

        const   XMLCh* const    str1

		, const	int				offset1

        , const XMLCh* const    str2

		, const int				offset2

		, const unsigned int	charCount

    );

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

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

	  * otherwise false.

	  *

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

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

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

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

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

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

      * one of the following is true:

      *   offset1 is negative.

      *   offset2 is negative.

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

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

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

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

      *

      * @param str1 Null-terminated string to compare

	  * @param offset1 Starting offset of str1

      * @param str2 Null-terminated string to compare

	  * @param offset2 Starting offset of str2

	  * @param charCount The number of characters to compare

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

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

	  *  otherwise.

      */

    static bool regionIMatches

    (

        const   XMLCh* const    str1

		, const	int				offset1

        , const XMLCh* const    str2

		, const int				offset2

		, const unsigned int	charCount

    );

    //@}

    /** @name String copy functions */

    //@{

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

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

      *

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

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

      * overlap.

      *

      * @param target Destination string

      * @param src Null-terminated source string

      */

    static void copyString

    (

                char* const     target

        , const char* const     src

    );

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

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

      *

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

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

      * destination strings overlap.

      *

      * @param target Destination string

      * @param src Null-terminated source string

      */

    static void copyString

    (

                XMLCh* const    target

        , const XMLCh* const    src

    );

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

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

      *

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

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

      * destination strings overlap.

      *

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

      *        atleast be 'maxChars + 1'.

      * @param src Null-terminated source string

      * @param maxChars The maximum number of characters to copy

      */

    static bool copyNString

    (

                XMLCh* const    target

        , const XMLCh* const    src

        , const unsigned int    maxChars

    );

    //@}

    /** @name Hash functions */

    //@{

    /** Hashes a string given a modulus

      *

      * @param toHash The string to hash

      * @param hashModulus The divisor to be used for hashing

      * @param manager The MemoryManager to use to allocate objects

      * @return Returns the hash value

      */

    static unsigned int hash

    (

        const   char* const     toHash

        , const unsigned int    hashModulus

        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

    );

    /** Hashes a string given a modulus

      *

      * @param toHash The string to hash

      * @param hashModulus The divisor to be used for hashing

      * @param manager The MemoryManager to use to allocate objects

      * @return Returns the hash value

      */

    static unsigned int hash

    (

        const   XMLCh* const    toHash

        , const unsigned int    hashModulus

        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

    );

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

      * as the limit

      *

      * @param toHash The string to hash

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

      * @param hashModulus The divisor to be used for hashing

      * @param manager The MemoryManager to use to allocate objects

      * @return Returns the hash value

      */

    static unsigned int hashN

    (

        const   XMLCh* const    toHash

        , const unsigned int    numChars

        , const unsigned int    hashModulus

        , MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager

    );

    //@}

    /** @name Search functions */

    //@{

    /**

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

      *

      * @param toSearch The string to search

      * @param ch The character to search within the string

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

      * else returns -1.

      */

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

    /**

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

      *

      * @param toSearch The string to search

      * @param ch The character to search within the string

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

      * else returns -1.

      */

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

	    /**

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

      * starting from a given index

      *

      * @param toSearch The string to search

      * @param chToFind The character to search within the string

      * @param fromIndex The index to start searching from

      * @param manager The MemoryManager to use to allocate objects

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

      * else returns -1.

      */

    static int indexOf

    (

        const   char* const     toSearch

        , const char            chToFind

        , const unsigned int    fromIndex

        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

    );

    /**

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

      * starting from a given index

      *

      * @param toSearch The string to search

      * @param chToFind The character to search within the string

      * @param fromIndex The index to start searching from

      * @param manager The MemoryManager to use to allocate objects

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

      * else returns -1.

      */

    static int indexOf

    (

        const   XMLCh* const    toSearch