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: DOMString.hpp 568078 2007-08-21 11:43:25Z amassari $

    36  */

    37 

    38 #ifndef DOMString_HEADER_GUARD_

    39 #define DOMString_HEADER_GUARD_

    40 

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

    42 

    43 #ifdef XML_DEBUG

    44 #include "DOMStringImpl.hpp"

    45 XERCES_CPP_NAMESPACE_BEGIN

    46 #else

    47 XERCES_CPP_NAMESPACE_BEGIN

    48 class DOMStringHandle;

    49 #endif

    50 

    51 class DOM_NullPtr;

    52 

    53 /**

    54  * <code>DOMString</code> is the generic string class that stores all strings

    55  * used in the DOM C++ API.

    56  *

    57  * Though this class supports most of the common string operations to manipulate

    58  * strings, it is not meant to be a comphrehensive string class.

    59  */

    60 

    61 class DEPRECATED_DOM_EXPORT DOMString : public XMemory{

    62 public:

    63     /** @name Constructors and assignment operator */

    64     //@{

    65     /**

    66       * Default constructor for DOMString.  The resulting DOMString

    67       * object refers to no string at all; it will compare == 0.

    68       *

    69       */

    70     DOMString();

    71 

    72     /**

    73       * Copy constructor.

    74       *

    75       * @param other The object to be copied.

    76       */

    77     DOMString(const DOMString &other);

    78 

    79     /**

    80       * Constructor to build a DOMString from an XML character array.

    81       * (XMLCh is a 16 bit UNICODE character).

    82       *

    83       * @param other The null-terminated character array to be

    84       *   that provides the initial value for the DOMString.

    85       */

    86     DOMString(const XMLCh *other);

    87 

    88     /**

    89       * Constructor to build a DOMString from a character array of given length.

    90       *

    91       * @param other The character array to be imported into the <code>DOMString</code>

    92       * @param length The length of the character array to be imported

    93       */

    94     DOMString(const XMLCh *other, unsigned int length);

    95 

    96     /**

    97       * Constructor to build a DOMString from an 8 bit character array.

    98       * The char * string will be transcoded to UNICODE using the default

    99       * code page on the system where the code is running.

   100       *

   101       * @param other The character array to be imported into the <code>DOMString</code>

   102       */

   103     DOMString(const char *other);

   104 

   105     /**

   106       * Construct a null DOMString.

   107       */

   108     DOMString(int nullPointerValue);

   109 

   110     /**

   111       * Assignment operator.  Make destination DOMString refer to the same

   112       *      underlying string in memory as the source string.

   113       *

   114       * @param other the source DOMString.

   115       */

   116     DOMString &        operator = (const DOMString &other);

   117 

   118 

   119 

   120     DOMString &        operator = (DOM_NullPtr *other);

   121 

   122     //@}

   123     /** @name Destructor. */

   124     //@{

   125 

   126 	 /**

   127 	  * Destructor for DOMString

   128 	  *

   129 	  */

   130     ~DOMString();

   131 

   132     //@}

   133     /** @name Operators for string manipulation. */

   134     //@{

   135 

   136     /**

   137       * Concatenate a DOMString to another.

   138       *

   139       * @param other The string to be concatenated.

   140       * @return The concatenated object

   141       */

   142     // DOMString   operator + (const DOMString &other);

   143 

   144     //@}

   145     /** @name Equality and Inequality operators. */

   146     //@{

   147 

   148     /**

   149       * Equality operator.

   150       *

   151       * @param other The object to be compared with.

   152       * @return True if the two DOMStrings refer to the same underlying string

   153       *  in memory.

   154       *  <p>

   155       *  WARNING:  operator == does NOT compare the contents of

   156       *  the two  strings.  To do this, use the <code>DOMString::equals()</code>

   157       *  This behavior is modelled after the String operations in Java, and

   158       *  is also similar to operator == on the other DOM_* classes.

   159       */

   160     bool        operator == (const DOMString &other) const;

   161 

   162     /**

   163       * Inequality operator.

   164       *

   165       * @param other The object to be compared with.

   166       * @return True if the two DOMStrings refer to different underlying strings in

   167       *    memory.

   168       * <p>

   169       *  WARNING:  operator == does NOT compare the contents of

   170       *  the two  strings.  To do this, use the <code>DOMString::equals()</code>

   171       *  This behavior is modelled after the String operations in Java, and

   172       *  is also similar to operator == on the other DOM_* classes.

   173       */

   174     bool        operator != (const DOMString &other) const;

   175 

   176     /**

   177       * Equality operator.  Test for a null DOMString, which is one that does

   178       *   not refer to any string at all; similar to a null object reference

   179       *   variable in Java.

   180       *

   181       * @param other must be 0 or null.

   182       * @return

   183       */

   184     bool        operator == (const DOM_NullPtr *other) const;

   185 

   186     /**

   187       * Inequality operator, for null test.

   188       *

   189       * @param other must be 0 or null.

   190       * @return True if the two strings are different, false otherwise

   191       */

   192     bool        operator != (const DOM_NullPtr *other) const;

   193 

   194     //@}

   195     /** @name Functions to change the string. */

   196     //@{

   197 

   198 

   199     /**

   200       * Preallocate storage in the string to hold a given number of characters.

   201       * A DOMString will grow its buffer on demand, as characters are added,

   202       * but it can be more efficient to allocate once in advance, if the size is known.

   203       *

   204       * @param size The number of 16 bit characters to reserve.

   205       */

   206     void reserve(unsigned int size);

   207 

   208 

   209     /**

   210       * Appends the content of another <code>DOMString</code> to this string.

   211       *

   212       * @param other The object to be appended

   213       */

   214     void        appendData(const DOMString &other);

   215 

   216     /**

   217       * Append a single Unicode character to this string.

   218       *

   219       * @param ch The single character to be appended

   220       */

   221     void        appendData(XMLCh ch);

   222 

   223      /**

   224       * Append a null-terminated XMLCh * (Unicode) string to this string.

   225       *

   226       * @param other The object to be appended

   227       */

   228     void        appendData(const XMLCh *other);

   229 

   230 

   231     /**

   232       * Appends the content of another <code>DOMString</code> to this string.

   233       *

   234       * @param other The object to be appended

   235       */

   236 	DOMString& operator +=(const DOMString &other);

   237 

   238 

   239     /**

   240       * Appends the content of a c-style string to this string.

   241       *

   242       * @param other The string to be appended

   243       */

   244     DOMString& operator +=(const XMLCh* other);

   245 

   246 

   247     /**

   248       * Appends a character to this string.

   249       *

   250       * @param ch The character to be appended

   251       */

   252 	DOMString& operator +=(XMLCh ch);

   253 

   254 

   255     /**

   256       * Clears the data of this <code>DOMString</code>.

   257       *

   258       * @param offset The position from the beginning from which the data must be deleted

   259       * @param count The count of characters from the offset that must be deleted

   260       */

   261     void        deleteData(unsigned int offset, unsigned int count);

   262 

   263     /**

   264       * Inserts a string within the existing <code>DOMString</code> at an arbitrary position.

   265       *

   266       * @param offset The offset from the beginning at which the insertion needs to be done

   267       *               in <code>this</code> object

   268       * @param data The <code>DOMString</code> containing the data that needs to be inserted

   269       * @return The object to be returned.

   270       */

   271     void        insertData(unsigned int offset, const DOMString &data);

   272 

   273     //@}

   274     /** @name Functions to get properties of the string. */

   275     //@{

   276 

   277     /**

   278       * Returns the character at the specified position.

   279       *

   280       * @param index The position at which the character is being requested

   281       * @return Returns the character at the specified position.

   282       */

   283     XMLCh       charAt(unsigned int index) const;

   284 

   285     /**

   286       * Returns a handle to the raw buffer in the <code>DOMString</code>.

   287       *

   288       * @return The pointer inside the <code>DOMString</code> containg the string data.

   289       *         Note: the data is not always null terminated.  Do not rely on

   290       *         a null being there, and do not add one, as several DOMStrings

   291       *         with different lengths may share the same raw buffer.

   292       */

   293     const XMLCh *rawBuffer() const;

   294 

   295     /**

   296       * Returns a copy of the string, transcoded to the local code page. The

   297       * caller owns the (char *) string that is returned, and is responsible

   298       * for deleting it.

   299       *

   300       * Note: The buffer returned is allocated using the global operator new

   301       *       and users need to make sure to use the corresponding delete [].

   302       *       This method will be deprecated in later versions, as we move

   303       *       towards using a memory manager for allocation and deallocation.

   304       *

   305       * @return A pointer to a newly allocated buffer of char elements, which

   306       *         represents the original string, but in the local encoding.

   307       */

   308     char        *transcode() const;

   309 

   310     /**

   311       * Returns a copy of the string, transcoded to the local code page. The

   312       * caller owns the (char *) string that is returned, and is responsible

   313       * for deleting it.

   314       *

   315       * @param  manager the memory manager to use for allocating returned

   316       *         returned buffer.

   317       *

   318       * @return A pointer to a newly allocated buffer of char elements, which

   319       *         represents the original string, but in the local encoding.

   320       */

   321     char        *transcode(MemoryManager* const manager) const;

   322 

   323 

   324     /**

   325       * Creates a DOMString, transcoded from an input 8 bit char * string

   326       * in the local code page.

   327       *

   328       * @param str The string to be transcoded

   329       * @return A new DOMString object

   330       */

   331     static DOMString transcode(const char* str);

   332 

   333 

   334 

   335     /**

   336       * Returns a sub-string of the <code>DOMString</code> starting at a specified position.

   337       *

   338       * @param offset The offset from the beginning from which the sub-string is being requested.

   339       * @param count The count of characters in the requested sub-string

   340       * @return The sub-string of the <code>DOMString</code> being requested

   341       */

   342     DOMString   substringData(unsigned int offset, unsigned int count) const;

   343 

   344     /**

   345       * Returns the length of the DOMString.

   346       *

   347       * @return The length of the string

   348       */

   349     unsigned int length() const;

   350 

   351     //@}

   352     /** @name Cloning function. */

   353     //@{

   354 

   355     /**

   356       * Makes a clone of a the DOMString.

   357       *

   358       * @return The object to be cloned.

   359       */

   360     DOMString   clone() const;

   361 

   362     //@}

   363     /** @name Print functions. */

   364     //@{

   365 

   366     /**

   367       * Dumps the <code>DOMString</code> on the console.

   368       *

   369       */

   370     void        print() const;

   371 

   372     /**

   373       * Dumps the <code>DOMString</code> on the console with a line feed at the end.

   374       *

   375       */

   376     void        println() const;

   377 

   378     //@}

   379     /** @name Functions to compare a string with another. */

   380     //@{

   381 

   382     /**

   383       * Compares a DOMString with another.

   384       *

   385       * This compareString does not match the semantics of the standard C strcmp.

   386       * All it needs to do is define some less than - equals - greater than

   387       * ordering of strings.  How doesn't matter.

   388       *

   389       *

   390       * @param other The object to be compared with

   391       * @return Either -1, 0, or 1 based on the comparison.

   392       */

   393     int         compareString(const DOMString &other) const;

   394 

   395     /**

   396       * Less than operator. It is a helper operator for compareString.

   397       *

   398       * @param other The object to be compared with.

   399       * @return True if this DOMString is lexically less than the other DOMString.

   400       */

   401     bool        operator < (const DOMString &other) const;

   402 

   403     /**

   404       * Tells if a <code>DOMString</code> contains the same character data

   405       * as another.

   406       *

   407       * @param other The DOMString to be compared with.

   408       * @return True if the two <code>DOMString</code>s are same, false otherwise.

   409       */

   410     bool        equals(const DOMString &other) const;

   411 

   412 

   413       /**

   414       * Compare a DOMString with a null-terminated raw 16-bit character

   415       * string.

   416       *

   417       * @param other The character string to be compared with.

   418       * @return True if the strings are the same, false otherwise.

   419       */

   420     bool        equals(const XMLCh  *other) const;

   421 

   422 

   423     //@}

   424     friend      class DOMStringData;

   425     friend      class DOMStringHandle;

   426     friend      class DomMemDebug;

   427 private:

   428 

   429     DOMStringHandle         *fHandle;

   430     static int              gLiveStringHandleCount;

   431     static int              gTotalStringHandleCount;

   432     static int              gLiveStringDataCount;

   433     static int              gTotalStringDataCount;

   434 };

   435 

   436 

   437 /****** Global Helper Functions ******/

   438 

   439 /**

   440   * Concatenate two DOMString's.

   441   *

   442   * @param lhs the first string

   443   * @param rhs the second string

   444   * @return The concatenated object

   445   */

   446 DOMString DEPRECATED_DOM_EXPORT operator + (const DOMString &lhs, const DOMString &rhs);

   447 

   448 /**

   449   * Concatenate a null terminated Unicode string to a DOMString.

   450   *

   451   * @param lhs the DOMString

   452   * @param rhs the XMLCh * string

   453   * @return The concatenated object

   454   */

   455 DOMString DEPRECATED_DOM_EXPORT operator + (const DOMString &lhs, const XMLCh* rhs);

   456 

   457 

   458 /**

   459   * Concatenate a DOMString to a null terminated Unicode string

   460   *

   461   * @param lhs the null-terminated Unicode string

   462   * @param rhs the DOMString

   463   * @return The concatenated object

   464   */

   465 DOMString DEPRECATED_DOM_EXPORT operator + (const XMLCh* lhs, const DOMString &rhs);

   466 

   467 

   468 /**

   469   * Concatenate a single Unicode character to a DOMString.

   470   *

   471   * @param lhs the DOMString

   472   * @param rhs the character

   473   * @return The concatenated object

   474   */

   475 DOMString DEPRECATED_DOM_EXPORT operator + (const DOMString &lhs, XMLCh rhs);

   476 

   477 

   478 /**

   479   * Concatenate a DOMString to a single Unicode character.

   480   *

   481   * @param lhs the character

   482   * @param rhs the DOMString

   483   * @return The concatenated object

   484   */

   485 DOMString DEPRECATED_DOM_EXPORT operator + (XMLCh lhs, const DOMString &rhs);

   486 

   487 XERCES_CPP_NAMESPACE_END

   488 

   489 #endif