DOMString.hpp
上传用户:huihehuasu
上传日期:2007-01-10
资源大小:6948k
文件大小:17k
源码类别:

xml/soap/webservice

开发平台:

C/C++

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  * 
  4.  * Copyright (c) 1999-2000 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.  * $Log: DOMString.hpp,v $
  58.  * Revision 1.12  2000/06/02 00:45:42  andyh
  59.  * DOM Fixes:  DOMString::rawBuffer() now returns a const XMLCh * pointer.
  60.  * Two plain deletes changed to array deletes.
  61.  *
  62.  * Revision 1.11  2000/03/02 19:53:52  roddey
  63.  * This checkin includes many changes done while waiting for the
  64.  * 1.1.0 code to be finished. I can't list them all here, but a list is
  65.  * available elsewhere.
  66.  *
  67.  * Revision 1.10  2000/02/24 20:11:27  abagchi
  68.  * Swat for removing Log from API docs
  69.  *
  70.  * Revision 1.9  2000/02/16 22:54:56  abagchi
  71.  * Switched the order of CDOM_EXPORT DomString for operators, to make OS/390 happy
  72.  *
  73.  * Revision 1.8  2000/02/06 07:47:27  rahulj
  74.  * Year 2K copyright swat.
  75.  *
  76.  * Revision 1.7  2000/02/04 05:06:30  andyh
  77.  * Change all DOMString offsets and lengths form signed to unsigned
  78.  * Other misc. cleanups.
  79.  *
  80.  * Revision 1.6  2000/02/04 00:52:58  rahulj
  81.  * Changed size_t to int.
  82.  *
  83.  * Revision 1.5  2000/02/03 23:07:27  andyh
  84.  * Add several new functions from Robert Weir to DOMString.
  85.  *
  86.  * Revision 1.4  2000/01/05 22:16:26  robweir
  87.  * Move DOMString implementation class declarations into a new
  88.  * file: DOMStringImpl.hpp.  Include this header in DOMString.hpp
  89.  * for XML_DEBUG builds so the underlying character array will be
  90.  * visible in the debugger.  <robert_weir@lotus.com>
  91.  *
  92.  * Revision 1.3  1999/12/03 00:11:22  andyh
  93.  * Added DOMString.clone() to node parameters in and out of the DOM,
  94.  * where they had been missed.
  95.  *
  96.  * DOMString::rawBuffer, removed incorrect assumptions about it
  97.  * being null terminated.
  98.  *
  99.  * Revision 1.2  1999/11/30 21:16:25  roddey
  100.  * Changes to add the transcode() method to DOMString, which returns a transcoded
  101.  * version (to local code page) of the DOM string contents. And I changed all of the
  102.  * exception 'throw by pointer' to 'throw by value' style.
  103.  *
  104.  * Revision 1.1.1.1  1999/11/09 01:08:48  twl
  105.  * Initial checkin
  106.  *
  107.  * Revision 1.2  1999/11/08 20:44:12  rahul
  108.  * Swat for adding in Product name and CVS comment log variable.
  109.  *
  110.  */
  111. #ifndef DOMString_HEADER_GUARD_
  112. #define DOMString_HEADER_GUARD_
  113. #include <util/XercesDefs.hpp>
  114. #ifdef XML_DEBUG
  115. #include "DOMStringImpl.hpp"
  116. #else
  117. class DOMStringHandle;
  118. #endif
  119. class DOM_NullPtr;
  120. /**
  121.  * <code>DOMString</code> is the generic string class that stores all strings
  122.  * used in the DOM C++ API.
  123.  *
  124.  * Though this class supports most of the common string operations to manipulate
  125.  * strings, it is not meant to be a comphrehensive string class.
  126.  */
  127. class CDOM_EXPORT DOMString {
  128. public:
  129.     /** @name Constructors and assignment operator */
  130.     //@{
  131.     /**
  132.       * Default constructor for DOMString.  The resulting DOMString
  133.       * object refers to no string at all; it will compare == 0.
  134.       *
  135.       */
  136.     DOMString();
  137.     /**
  138.       * Copy constructor.
  139.       *
  140.       * @param other The object to be copied.
  141.       */
  142.     DOMString(const DOMString &other);
  143.     /**
  144.       * Constructor to build a DOMString from an XML character array.
  145.       * (XMLCh is a 16 bit UNICODE character).
  146.       *
  147.       * @param other The null-terminated character array to be 
  148.       *   that provides the initial value for the DOMString.
  149.       */
  150.     DOMString(const XMLCh *other);
  151.     /**
  152.       * Constructor to build a DOMString from a character array of given length.
  153.       *
  154.       * @param other The character array to be imported into the <code>DOMString</code>
  155.       * @param length The length of the character array to be imported
  156.       */
  157.     DOMString(const XMLCh *other, unsigned int length);
  158.     /**
  159.       * Constructor to build a DOMString from an 8 bit character array.
  160.       * The char * string will be transcoded to UNICODE using the default
  161.       * code page on the system where the code is running.
  162.       *
  163.       * @param other The character array to be imported into the <code>DOMString</code>
  164.       */
  165.     DOMString(const char *other);
  166.     /**
  167.       * Construct a null DOMString.
  168.       */
  169.     DOMString(int nullPointerValue);
  170.     /**
  171.       * Assignment operator.  Make destination DOMString refer to the same
  172.       *      underlying string in memory as the source string.
  173.       *
  174.       * @param the source DOMString.
  175.       */
  176.     DOMString &        operator = (const DOMString &other);
  177.     DOMString &        operator = (DOM_NullPtr *other);
  178.     //@}
  179.     /** @name Destructor. */
  180.     //@{
  181.  /**
  182.   * Destructor for DOMString
  183.   *
  184.   */
  185.     ~DOMString();
  186.     //@}
  187.     /** @name Operators for string manipulation. */
  188.     //@{
  189.     /**
  190.       * Concatenate a DOMString to another.
  191.       *
  192.       * @param other The string to be concatenated.
  193.       * @return The concatenated object
  194.       */
  195.     // DOMString   operator + (const DOMString &other);
  196.     //@}
  197.     /** @name Equality and Inequality operators. */
  198.     //@{
  199.     /**
  200.       * Equality operator.  
  201.       *
  202.       * @param other The object to be compared with.
  203.       * @return True if the two DOMStrings refer to the same underlying string
  204.       *  in memory.  
  205.       *  <p>
  206.       *  WARNING:  operator == does NOT compare the contents of
  207.       *  the two  strings.  To do this, use the <code>DOMString::equals()</code>
  208.       *  This behavior is modelled after the String operations in Java, and
  209.       *  is also similar to operator == on the other DOM_* classes.
  210.       */
  211.     bool        operator == (const DOMString &other) const;
  212.     /**
  213.       * Inequality operator.
  214.       *
  215.       * @param other The object to be compared with.
  216.       * @return True if the two DOMStrings refer to different underlying strings in
  217.       *    memory.
  218.       * <p>
  219.       *  WARNING:  operator == does NOT compare the contents of
  220.       *  the two  strings.  To do this, use the <code>DOMString::equals()</code>
  221.       *  This behavior is modelled after the String operations in Java, and
  222.       *  is also similar to operator == on the other DOM_* classes.
  223.       */
  224.     bool        operator != (const DOMString &other) const;
  225.     /**
  226.       * Equality operator.  Test for a null DOMString, which is one that does
  227.       *   not refer to any string at all; similar to a null object reference
  228.       *   variable in Java.
  229.       *
  230.       * @param other must be 0 or null.
  231.       * @return 
  232.       */
  233.     bool        operator == (const DOM_NullPtr *other) const;
  234.     /**
  235.       * Inequality operator, for null test.
  236.       *
  237.       * @param other must be 0 or null.
  238.       * @return True if the two strings are different, false otherwise
  239.       */
  240.     bool        operator != (const DOM_NullPtr *other) const;
  241.     //@}
  242.     /** @name Functions to change the string. */
  243.     //@{
  244.     /**
  245.       * Preallocate storage in the string to hold a given number of characters.
  246.       * A DOMString will grow its buffer on demand, as characters are added,
  247.       * but it can be more efficient to allocate once in advance, if the size is known.
  248.       *
  249.       * @param size The number of 16 bit characters to reserve.
  250.       */
  251.     void reserve(unsigned int size);
  252.     
  253.     /**
  254.       * Appends the content of another <code>DOMString</code> to this string.
  255.       *
  256.       * @param other The object to be appended
  257.       */
  258.     void        appendData(const DOMString &other);
  259.     /**
  260.       * Append a single Unicode character to this string.
  261.       *
  262.       * @param other The object to be appended
  263.       */
  264.     void        appendData(XMLCh ch);
  265.      /**
  266.       * Append a null-terminated XMLCh * (Unicode) string to this string.
  267.       *
  268.       * @param other The object to be appended
  269.       */
  270.     void        appendData(const XMLCh *other);
  271.     /**
  272.       * Appends the content of another <code>DOMString</code> to this string.
  273.       *
  274.       * @param other The object to be appended
  275.       */
  276. DOMString& operator +=(const DOMString &other);
  277.     /**
  278.       * Appends the content of a c-style string to this string.
  279.       *
  280.       * @param other The string to be appended
  281.       */
  282.     DOMString& operator +=(const XMLCh* other);
  283.     /**
  284.       * Appends a character to this string.
  285.       *
  286.       * @param ch The character to be appended
  287.       */
  288. DOMString& operator +=(XMLCh ch);
  289.     /**
  290.       * Clears the data of this <code>DOMString</code>.
  291.       *
  292.       * @param offset The position from the beginning from which the data must be deleted
  293.       * @param count The count of characters from the offset that must be deleted
  294.       */
  295.     void        deleteData(unsigned int offset, unsigned int count);
  296.     /**
  297.       * Inserts a string within the existing <code>DOMString</code> at an arbitrary position.
  298.       *
  299.       * @param offset The offset from the beginning at which the insertion needs to be done 
  300.       *               in <code>this</code> object
  301.       * @param data The <code>DOMString</code> containing the data that needs to be inserted
  302.       * @return The object to be returned.
  303.       */
  304.     void        insertData(unsigned int offset, const DOMString &data);
  305.     //@}
  306.     /** @name Functions to get properties of the string. */
  307.     //@{
  308.     /**
  309.       * Returns the character at the specified position.
  310.       *
  311.       * @param index The position at which the character is being requested
  312.       * @return Returns the character at the specified position.
  313.       */
  314.     XMLCh       charAt(unsigned int index) const;
  315.     /**
  316.       * Returns a handle to the raw buffer in the <code>DOMString</code>.
  317.       *
  318.       * @return The pointer inside the <code>DOMString</code> containg the string data.
  319.       *         Note: the data is not always null terminated.  Do not rely on
  320.       *         a null being there, and do not add one, as several DOMStrings
  321.       *         with different lengths may share the same raw buffer.
  322.       */
  323.     const XMLCh *rawBuffer() const;
  324.     /**
  325.       * Returns a copy of the string, transcoded to the local code page. The
  326.       * caller owns the (char *) string that is returned, and is responsible
  327.       * for deleting it.
  328.       *
  329.       * @return A pointer to a newly allocated buffer of char elements, which
  330.       *         represents the original string, but in the local encoding.
  331.       */
  332.     char        *transcode() const;
  333.     /**
  334.       * Creates a DOMString, transcoded from an input 8 bit char * string
  335.       * in the local code page.
  336.       *
  337.       * @param str The string to be transcoded
  338.       * @return A new DOMString object
  339.       */
  340.     static DOMString transcode(const char* str);
  341.     /**
  342.       * Returns a sub-string of the <code>DOMString</code> starting at a specified position.
  343.       *
  344.       * @param offset The offset from the beginning from which the sub-string is being requested.
  345.       * @param count The count of characters in the requested sub-string
  346.       * @return The sub-string of the <code>DOMString</code> being requested
  347.       */
  348.     DOMString   substringData(unsigned int offset, unsigned int count) const;
  349.     /**
  350.       * Returns the length of the DOMString.
  351.       *
  352.       * @return The length of the string
  353.       */
  354.     unsigned int length() const;
  355.     //@}
  356.     /** @name Cloning function. */
  357.     //@{
  358.     /**
  359.       * Makes a clone of a the DOMString.
  360.       *
  361.       * @return The object to be cloned.
  362.       */
  363.     DOMString   clone() const;
  364.     //@}
  365.     /** @name Print functions. */
  366.     //@{
  367.     /**
  368.       * Dumps the <code>DOMString</code> on the console.
  369.       *
  370.       */
  371.     void        print() const;
  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.     /** @name Functions to compare a string with another. */
  379.     //@{
  380.     /**
  381.       * Compares a DOMString with another.
  382.       *
  383.       * This compareString does not match the semantics of the standard C strcmp.  
  384.       * All it needs to do is define some less than - equals - greater than 
  385.       * ordering of strings.  How doesn't matter.
  386.       *
  387.       *
  388.       * @param other The object to be compared with
  389.       * @return Either -1, 0, or 1 based on the comparison. 
  390.       */
  391.     int         compareString(const DOMString &other) const;
  392.     /**
  393.       * Tells if a <code>DOMString</code> contains the same character data
  394.       * as another.
  395.       *
  396.       * @param other The DOMString to be compared with.
  397.       * @return True if the two <code>DOMString</code>s are same, false otherwise.
  398.       */
  399.     bool        equals(const DOMString &other) const;
  400.       /**
  401.       * Compare a DOMString with a null-terminated raw 16-bit character
  402.       * string.
  403.       *
  404.       * @param other The character string to be compared with.
  405.       * @return True if the strings are the same, false otherwise.
  406.       */
  407.     bool        equals(const XMLCh  *other) const;
  408.     //@}
  409.     friend      class DOMStringData;
  410.     friend      class DOMStringHandle;
  411.     friend      class DomMemDebug;
  412. private:
  413.     DOMStringHandle         *fHandle;
  414.     static int              gLiveStringHandleCount;
  415.     static int              gTotalStringHandleCount;
  416.     static int              gLiveStringDataCount;
  417.     static int              gTotalStringDataCount;
  418. };
  419. /****** Global Helper Functions ******/
  420. /**
  421.   * Concatenate two DOMString's.
  422.   *
  423.   * @param lhs the first string
  424.   * @param rhs the second string
  425.   * @return The concatenated object
  426.   */
  427. DOMString CDOM_EXPORT operator + (const DOMString &lhs, const DOMString &rhs);
  428. /**
  429.   * Concatenate a null terminated Unicode string to a DOMString.
  430.   *
  431.   * @param lhs the DOMString
  432.   * @param rhs the XMLCh * string
  433.   * @return The concatenated object
  434.   */
  435. DOMString CDOM_EXPORT operator + (const DOMString &lhs, const XMLCh* rhs);
  436. /**
  437.   * Concatenate a DOMString to a null terminated Unicode string
  438.   *
  439.   * @param lhs the null-terminated Unicode string
  440.   * @param rhs the DOMString
  441.   * @return The concatenated object
  442.   */
  443. DOMString CDOM_EXPORT operator + (const XMLCh* lhs, const DOMString &rhs);
  444. /**
  445.   * Concatenate a single Unicode character to a DOMString.
  446.   *
  447.   * @param lhs the DOMString
  448.   * @param rhs the character
  449.   * @return The concatenated object
  450.   */
  451. DOMString CDOM_EXPORT operator + (const DOMString &lhs, XMLCh rhs);
  452. /**
  453.   * Concatenate a DOMString to a single Unicode character.
  454.   *
  455.   * @param lhs the character
  456.   * @param rhs the DOMString
  457.   * @return The concatenated object
  458.   */
  459. DOMString CDOM_EXPORT operator + (XMLCh lhs, const DOMString &rhs);
  460. #endif