DOMString.hpp
上传用户:zhuqijet
上传日期:2013-06-25
资源大小:10074k
文件大小:16k
源码类别:

词法分析

开发平台:

Visual C++

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Xerces" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation, and was
  51.  * originally based on software copyright (c) 1999, International
  52.  * Business Machines, Inc., http://www.ibm.com .  For more information
  53.  * on the Apache Software Foundation, please see
  54.  * <http://www.apache.org/>.
  55.  */
  56. /*
  57.  * $Id: DOMString.hpp,v 1.5 2003/05/22 02:26:50 knoaman Exp $
  58.  */
  59. #ifndef DOMString_HEADER_GUARD_
  60. #define DOMString_HEADER_GUARD_
  61. #include <xercesc/util/XMemory.hpp>
  62. #ifdef XML_DEBUG
  63. #include "DOMStringImpl.hpp"
  64. XERCES_CPP_NAMESPACE_BEGIN
  65. #else
  66. XERCES_CPP_NAMESPACE_BEGIN
  67. class DOMStringHandle;
  68. #endif
  69. class DOM_NullPtr;
  70. /**
  71.  * <code>DOMString</code> is the generic string class that stores all strings
  72.  * used in the DOM C++ API.
  73.  *
  74.  * Though this class supports most of the common string operations to manipulate
  75.  * strings, it is not meant to be a comphrehensive string class.
  76.  */
  77. class CDOM_EXPORT DOMString : public XMemory{
  78. public:
  79.     /** @name Constructors and assignment operator */
  80.     //@{
  81.     /**
  82.       * Default constructor for DOMString.  The resulting DOMString
  83.       * object refers to no string at all; it will compare == 0.
  84.       *
  85.       */
  86.     DOMString();
  87.     /**
  88.       * Copy constructor.
  89.       *
  90.       * @param other The object to be copied.
  91.       */
  92.     DOMString(const DOMString &other);
  93.     /**
  94.       * Constructor to build a DOMString from an XML character array.
  95.       * (XMLCh is a 16 bit UNICODE character).
  96.       *
  97.       * @param other The null-terminated character array to be
  98.       *   that provides the initial value for the DOMString.
  99.       */
  100.     DOMString(const XMLCh *other);
  101.     /**
  102.       * Constructor to build a DOMString from a character array of given length.
  103.       *
  104.       * @param other The character array to be imported into the <code>DOMString</code>
  105.       * @param length The length of the character array to be imported
  106.       */
  107.     DOMString(const XMLCh *other, unsigned int length);
  108.     /**
  109.       * Constructor to build a DOMString from an 8 bit character array.
  110.       * The char * string will be transcoded to UNICODE using the default
  111.       * code page on the system where the code is running.
  112.       *
  113.       * @param other The character array to be imported into the <code>DOMString</code>
  114.       */
  115.     DOMString(const char *other);
  116.     /**
  117.       * Construct a null DOMString.
  118.       */
  119.     DOMString(int nullPointerValue);
  120.     /**
  121.       * Assignment operator.  Make destination DOMString refer to the same
  122.       *      underlying string in memory as the source string.
  123.       *
  124.       * @param other the source DOMString.
  125.       */
  126.     DOMString &        operator = (const DOMString &other);
  127.     DOMString &        operator = (DOM_NullPtr *other);
  128.     //@}
  129.     /** @name Destructor. */
  130.     //@{
  131.  /**
  132.   * Destructor for DOMString
  133.   *
  134.   */
  135.     ~DOMString();
  136.     //@}
  137.     /** @name Operators for string manipulation. */
  138.     //@{
  139.     /**
  140.       * Concatenate a DOMString to another.
  141.       *
  142.       * @param other The string to be concatenated.
  143.       * @return The concatenated object
  144.       */
  145.     // DOMString   operator + (const DOMString &other);
  146.     //@}
  147.     /** @name Equality and Inequality operators. */
  148.     //@{
  149.     /**
  150.       * Equality operator.
  151.       *
  152.       * @param other The object to be compared with.
  153.       * @return True if the two DOMStrings refer to the same underlying string
  154.       *  in memory.
  155.       *  <p>
  156.       *  WARNING:  operator == does NOT compare the contents of
  157.       *  the two  strings.  To do this, use the <code>DOMString::equals()</code>
  158.       *  This behavior is modelled after the String operations in Java, and
  159.       *  is also similar to operator == on the other DOM_* classes.
  160.       */
  161.     bool        operator == (const DOMString &other) const;
  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.       * Equality operator.  Test for a null DOMString, which is one that does
  177.       *   not refer to any string at all; similar to a null object reference
  178.       *   variable in Java.
  179.       *
  180.       * @param other must be 0 or null.
  181.       * @return
  182.       */
  183.     bool        operator == (const DOM_NullPtr *other) const;
  184.     /**
  185.       * Inequality operator, for null test.
  186.       *
  187.       * @param other must be 0 or null.
  188.       * @return True if the two strings are different, false otherwise
  189.       */
  190.     bool        operator != (const DOM_NullPtr *other) const;
  191.     //@}
  192.     /** @name Functions to change the string. */
  193.     //@{
  194.     /**
  195.       * Preallocate storage in the string to hold a given number of characters.
  196.       * A DOMString will grow its buffer on demand, as characters are added,
  197.       * but it can be more efficient to allocate once in advance, if the size is known.
  198.       *
  199.       * @param size The number of 16 bit characters to reserve.
  200.       */
  201.     void reserve(unsigned int size);
  202.     /**
  203.       * Appends the content of another <code>DOMString</code> to this string.
  204.       *
  205.       * @param other The object to be appended
  206.       */
  207.     void        appendData(const DOMString &other);
  208.     /**
  209.       * Append a single Unicode character to this string.
  210.       *
  211.       * @param ch The single character to be appended
  212.       */
  213.     void        appendData(XMLCh ch);
  214.      /**
  215.       * Append a null-terminated XMLCh * (Unicode) string to this string.
  216.       *
  217.       * @param other The object to be appended
  218.       */
  219.     void        appendData(const XMLCh *other);
  220.     /**
  221.       * Appends the content of another <code>DOMString</code> to this string.
  222.       *
  223.       * @param other The object to be appended
  224.       */
  225. DOMString& operator +=(const DOMString &other);
  226.     /**
  227.       * Appends the content of a c-style string to this string.
  228.       *
  229.       * @param other The string to be appended
  230.       */
  231.     DOMString& operator +=(const XMLCh* other);
  232.     /**
  233.       * Appends a character to this string.
  234.       *
  235.       * @param ch The character to be appended
  236.       */
  237. DOMString& operator +=(XMLCh ch);
  238.     /**
  239.       * Clears the data of this <code>DOMString</code>.
  240.       *
  241.       * @param offset The position from the beginning from which the data must be deleted
  242.       * @param count The count of characters from the offset that must be deleted
  243.       */
  244.     void        deleteData(unsigned int offset, unsigned int count);
  245.     /**
  246.       * Inserts a string within the existing <code>DOMString</code> at an arbitrary position.
  247.       *
  248.       * @param offset The offset from the beginning at which the insertion needs to be done
  249.       *               in <code>this</code> object
  250.       * @param data The <code>DOMString</code> containing the data that needs to be inserted
  251.       * @return The object to be returned.
  252.       */
  253.     void        insertData(unsigned int offset, const DOMString &data);
  254.     //@}
  255.     /** @name Functions to get properties of the string. */
  256.     //@{
  257.     /**
  258.       * Returns the character at the specified position.
  259.       *
  260.       * @param index The position at which the character is being requested
  261.       * @return Returns the character at the specified position.
  262.       */
  263.     XMLCh       charAt(unsigned int index) const;
  264.     /**
  265.       * Returns a handle to the raw buffer in the <code>DOMString</code>.
  266.       *
  267.       * @return The pointer inside the <code>DOMString</code> containg the string data.
  268.       *         Note: the data is not always null terminated.  Do not rely on
  269.       *         a null being there, and do not add one, as several DOMStrings
  270.       *         with different lengths may share the same raw buffer.
  271.       */
  272.     const XMLCh *rawBuffer() const;
  273.     /**
  274.       * Returns a copy of the string, transcoded to the local code page. The
  275.       * caller owns the (char *) string that is returned, and is responsible
  276.       * for deleting it.
  277.       *
  278.       * Note: The buffer returned is allocated using the global operator new
  279.       *       and users need to make sure to use the corresponding delete [].
  280.       *       This method will be deprecated in later versions, as we move
  281.       *       towards using a memory manager for allocation and deallocation.
  282.       *
  283.       * @return A pointer to a newly allocated buffer of char elements, which
  284.       *         represents the original string, but in the local encoding.
  285.       */
  286.     char        *transcode() const;
  287.     /**
  288.       * Returns a copy of the string, transcoded to the local code page. The
  289.       * caller owns the (char *) string that is returned, and is responsible
  290.       * for deleting it.
  291.       *
  292.       * @param  manager the memory manager to use for allocating returned
  293.       *         returned buffer.
  294.       *
  295.       * @return A pointer to a newly allocated buffer of char elements, which
  296.       *         represents the original string, but in the local encoding.
  297.       */
  298.     char        *transcode(MemoryManager* const manager) const;
  299.     /**
  300.       * Creates a DOMString, transcoded from an input 8 bit char * string
  301.       * in the local code page.
  302.       *
  303.       * @param str The string to be transcoded
  304.       * @return A new DOMString object
  305.       */
  306.     static DOMString transcode(const char* str);
  307.     /**
  308.       * Returns a sub-string of the <code>DOMString</code> starting at a specified position.
  309.       *
  310.       * @param offset The offset from the beginning from which the sub-string is being requested.
  311.       * @param count The count of characters in the requested sub-string
  312.       * @return The sub-string of the <code>DOMString</code> being requested
  313.       */
  314.     DOMString   substringData(unsigned int offset, unsigned int count) const;
  315.     /**
  316.       * Returns the length of the DOMString.
  317.       *
  318.       * @return The length of the string
  319.       */
  320.     unsigned int length() const;
  321.     //@}
  322.     /** @name Cloning function. */
  323.     //@{
  324.     /**
  325.       * Makes a clone of a the DOMString.
  326.       *
  327.       * @return The object to be cloned.
  328.       */
  329.     DOMString   clone() const;
  330.     //@}
  331.     /** @name Print functions. */
  332.     //@{
  333.     /**
  334.       * Dumps the <code>DOMString</code> on the console.
  335.       *
  336.       */
  337.     void        print() const;
  338.     /**
  339.       * Dumps the <code>DOMString</code> on the console with a line feed at the end.
  340.       *
  341.       */
  342.     void        println() const;
  343.     //@}
  344.     /** @name Functions to compare a string with another. */
  345.     //@{
  346.     /**
  347.       * Compares a DOMString with another.
  348.       *
  349.       * This compareString does not match the semantics of the standard C strcmp.
  350.       * All it needs to do is define some less than - equals - greater than
  351.       * ordering of strings.  How doesn't matter.
  352.       *
  353.       *
  354.       * @param other The object to be compared with
  355.       * @return Either -1, 0, or 1 based on the comparison.
  356.       */
  357.     int         compareString(const DOMString &other) const;
  358.     /**
  359.       * Tells if a <code>DOMString</code> contains the same character data
  360.       * as another.
  361.       *
  362.       * @param other The DOMString to be compared with.
  363.       * @return True if the two <code>DOMString</code>s are same, false otherwise.
  364.       */
  365.     bool        equals(const DOMString &other) const;
  366.       /**
  367.       * Compare a DOMString with a null-terminated raw 16-bit character
  368.       * string.
  369.       *
  370.       * @param other The character string to be compared with.
  371.       * @return True if the strings are the same, false otherwise.
  372.       */
  373.     bool        equals(const XMLCh  *other) const;
  374.     //@}
  375.     friend      class DOMStringData;
  376.     friend      class DOMStringHandle;
  377.     friend      class DomMemDebug;
  378. private:
  379.     DOMStringHandle         *fHandle;
  380.     static int              gLiveStringHandleCount;
  381.     static int              gTotalStringHandleCount;
  382.     static int              gLiveStringDataCount;
  383.     static int              gTotalStringDataCount;
  384. };
  385. /****** Global Helper Functions ******/
  386. /**
  387.   * Concatenate two DOMString's.
  388.   *
  389.   * @param lhs the first string
  390.   * @param rhs the second string
  391.   * @return The concatenated object
  392.   */
  393. DOMString CDOM_EXPORT operator + (const DOMString &lhs, const DOMString &rhs);
  394. /**
  395.   * Concatenate a null terminated Unicode string to a DOMString.
  396.   *
  397.   * @param lhs the DOMString
  398.   * @param rhs the XMLCh * string
  399.   * @return The concatenated object
  400.   */
  401. DOMString CDOM_EXPORT operator + (const DOMString &lhs, const XMLCh* rhs);
  402. /**
  403.   * Concatenate a DOMString to a null terminated Unicode string
  404.   *
  405.   * @param lhs the null-terminated Unicode string
  406.   * @param rhs the DOMString
  407.   * @return The concatenated object
  408.   */
  409. DOMString CDOM_EXPORT operator + (const XMLCh* lhs, const DOMString &rhs);
  410. /**
  411.   * Concatenate a single Unicode character to a DOMString.
  412.   *
  413.   * @param lhs the DOMString
  414.   * @param rhs the character
  415.   * @return The concatenated object
  416.   */
  417. DOMString CDOM_EXPORT operator + (const DOMString &lhs, XMLCh rhs);
  418. /**
  419.   * Concatenate a DOMString to a single Unicode character.
  420.   *
  421.   * @param lhs the character
  422.   * @param rhs the DOMString
  423.   * @return The concatenated object
  424.   */
  425. DOMString CDOM_EXPORT operator + (XMLCh lhs, const DOMString &rhs);
  426. XERCES_CPP_NAMESPACE_END
  427. #endif