xercesc/dom/DOMCharacterData.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_DOMCHARACTERDATA_HPP)
0023 #define XERCESC_INCLUDE_GUARD_DOMCHARACTERDATA_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026 #include <xercesc/dom/DOMNode.hpp>
0027
0028 XERCES_CPP_NAMESPACE_BEGIN
0029
0030
0031 /**
0032  * The <code>DOMCharacterData</code> interface extends DOMNode with a set of
0033  * attributes and methods for accessing character data in the DOM. For
0034  * clarity this set is defined here rather than on each object that uses
0035  * these attributes and methods. No DOM objects correspond directly to
0036  * <code>DOMCharacterData</code>, though <code>DOMText</code> and others do
0037  * inherit the interface from it. All <code>offsets</code> in this interface
0038  * start from <code>0</code>.
0039  * <p>As explained in the DOM spec, text strings in
0040  * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In
0041  * the following, the term 16-bit units is used whenever necessary to
0042  * indicate that indexing on DOMCharacterData is done in 16-bit units.
0043  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
0044  * @since DOM Level 1
0045  */
0046 class CDOM_EXPORT DOMCharacterData: public DOMNode {
0047 protected:
0048     // -----------------------------------------------------------------------
0049     //  Hidden constructors
0050     // -----------------------------------------------------------------------
0051     /** @name Hidden constructors */
0052     //@{
0053     DOMCharacterData() {}
0054     DOMCharacterData(const DOMCharacterData &other) : DOMNode(other) {}
0055     //@}
0056
0057 private:
0058     // -----------------------------------------------------------------------
0059     // Unimplemented constructors and operators
0060     // -----------------------------------------------------------------------
0061     /** @name Unimplemented operators */
0062     //@{
0063     DOMCharacterData & operator = (const DOMCharacterData &);
0064     //@}
0065
0066 public:
0067     // -----------------------------------------------------------------------
0068     //  All constructors are hidden, just the destructor is available
0069     // -----------------------------------------------------------------------
0070     /** @name Destructor */
0071     //@{
0072     /**
0073      * Destructor
0074      *
0075      */
0076     virtual ~DOMCharacterData() {};
0077     //@}
0078
0079     // -----------------------------------------------------------------------
0080     //  Virtual DOMCharacterData interface
0081     // -----------------------------------------------------------------------
0082     /** @name Functions introduced in DOM Level 1 */
0083     //@{
0084     // -----------------------------------------------------------------------
0085     //  Getter methods
0086     // -----------------------------------------------------------------------
0087     /**
0088      * Returns the character data of the node that implements this interface.
0089      *
0090      * The DOM implementation may not put arbitrary limits on the amount of data that
0091      * may be stored in a  <code>DOMCharacterData</code> node. However,
0092      * implementation limits may  mean that the entirety of a node's data may
0093      * not fit into a single <code>XMLCh* String</code>. In such cases, the user
0094      * may call <code>substringData</code> to retrieve the data in
0095      * appropriately sized pieces.
0096      * @exception DOMException
0097      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
0098      * @since DOM Level 1
0099      */
0100     virtual const XMLCh *     getData() const = 0;
0101
0102     /**
0103      * Returns the number of characters that are available through <code>data</code> and
0104      * the <code>substringData</code> method below.
0105      *
0106      * This may have the value
0107      * zero, i.e., <code>CharacterData</code> nodes may be empty.
0108      * @since DOM Level 1
0109      */
0110     virtual XMLSize_t       getLength() const = 0;
0111
0112     /**
0113      * Extracts a range of data from the node.
0114      *
0115      * @param offset Start offset of substring to extract.
0116      * @param count The number of characters to extract.
0117      * @return The specified substring. If the sum of <code>offset</code> and
0118      *   <code>count</code> exceeds the <code>length</code>, then all
0119      *   characters to the end of the data are returned.
0120      * @exception DOMException
0121      *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
0122      *   than the number of characters in <code>data</code>, or if the
0123      *   specified <code>count</code> is negative.
0124      * @since DOM Level 1
0125      */
0126     virtual const XMLCh *     substringData(XMLSize_t offset,
0127                                      XMLSize_t count) const = 0;
0128
0129     // -----------------------------------------------------------------------
0130     //  String methods
0131     // -----------------------------------------------------------------------
0132     /**
0133      * Append the string to the end of the character data of the node.
0134      *
0135      * Upon success, <code>data</code> provides access to the concatenation of
0136      * <code>data</code> and the <code>XMLCh* String</code> specified.
0137      * @param arg The <code>XMLCh* String</code> to append.
0138      * @exception DOMException
0139      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0140      * @since DOM Level 1
0141      */
0142     virtual void               appendData(const XMLCh *arg) = 0;
0143
0144     /**
0145      * Insert a string at the specified character offset.
0146      *
0147      * @param offset The character offset at which to insert.
0148      * @param arg The <code>XMLCh* String</code> to insert.
0149      * @exception DOMException
0150      *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
0151      *   than the number of characters in <code>data</code>.
0152      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0153      * @since DOM Level 1
0154      */
0155     virtual void               insertData(XMLSize_t offset, const  XMLCh *arg) = 0;
0156
0157     /**
0158      * Remove a range of characters from the node.
0159      *
0160      * Upon success,
0161      * <code>data</code> and <code>length</code> reflect the change.
0162      * @param offset The offset from which to remove characters.
0163      * @param count The number of characters to delete. If the sum of
0164      *   <code>offset</code> and <code>count</code> exceeds <code>length</code>
0165      *   then all characters from <code>offset</code> to the end of the data
0166      *   are deleted.
0167      * @exception DOMException
0168      *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
0169      *   than the number of characters in <code>data</code>, or if the
0170      *   specified <code>count</code> is negative.
0171      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0172      * @since DOM Level 1
0173      */
0174     virtual void               deleteData(XMLSize_t offset,
0175                                   XMLSize_t count) = 0;
0176
0177     /**
0178      * Replace the characters starting at the specified character offset with
0179      * the specified string.
0180      *
0181      * @param offset The offset from which to start replacing.
0182      * @param count The number of characters to replace. If the sum of
0183      *   <code>offset</code> and <code>count</code> exceeds <code>length</code>
0184      *   , then all characters to the end of the data are replaced (i.e., the
0185      *   effect is the same as a <code>remove</code> method call with the same
0186      *   range, followed by an <code>append</code> method invocation).
0187      * @param arg The <code>XMLCh* String</code> with which the range must be
0188      *   replaced.
0189      * @exception DOMException
0190      *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater
0191      *   than the number of characters in <code>data</code>, or if the
0192      *   specified <code>count</code> is negative.
0193      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
0194      * @since DOM Level 1
0195      */
0196     virtual void               replaceData(XMLSize_t offset,
0197                                    XMLSize_t count,
0198                                    const XMLCh *arg) = 0;
0199
0200     /**
0201      * Sets the character data of the node that implements this interface.
0202      *
0203      * @param data The <code>XMLCh* String</code> to set.
0204      * @since DOM Level 1
0205      */
0206     virtual void               setData(const XMLCh *data) = 0;
0207     //@}
0208
0209 };
0210
0211 XERCES_CPP_NAMESPACE_END
0212
0213 #endif
0214
0215