|
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 #ifndef DOMCharacterData_HEADER_GUARD_ |
|
18 #define DOMCharacterData_HEADER_GUARD_ |
|
19 |
|
20 /* |
|
21 * Licensed to the Apache Software Foundation (ASF) under one or more |
|
22 * contributor license agreements. See the NOTICE file distributed with |
|
23 * this work for additional information regarding copyright ownership. |
|
24 * The ASF licenses this file to You under the Apache License, Version 2.0 |
|
25 * (the "License"); you may not use this file except in compliance with |
|
26 * the License. You may obtain a copy of the License at |
|
27 * |
|
28 * http://www.apache.org/licenses/LICENSE-2.0 |
|
29 * |
|
30 * Unless required by applicable law or agreed to in writing, software |
|
31 * distributed under the License is distributed on an "AS IS" BASIS, |
|
32 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
33 * See the License for the specific language governing permissions and |
|
34 * limitations under the License. |
|
35 */ |
|
36 |
|
37 /* |
|
38 * $Id: DOMCharacterData.hpp 568078 2007-08-21 11:43:25Z amassari $ |
|
39 */ |
|
40 |
|
41 #include <xercesc/util/XercesDefs.hpp> |
|
42 #include <xercesc/dom/DOMNode.hpp> |
|
43 |
|
44 XERCES_CPP_NAMESPACE_BEGIN |
|
45 |
|
46 |
|
47 /** |
|
48 * The <code>DOMCharacterData</code> interface extends DOMNode with a set of |
|
49 * attributes and methods for accessing character data in the DOM. For |
|
50 * clarity this set is defined here rather than on each object that uses |
|
51 * these attributes and methods. No DOM objects correspond directly to |
|
52 * <code>DOMCharacterData</code>, though <code>DOMText</code> and others do |
|
53 * inherit the interface from it. All <code>offsets</code> in this interface |
|
54 * start from <code>0</code>. |
|
55 * <p>As explained in the DOM spec, text strings in |
|
56 * the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In |
|
57 * the following, the term 16-bit units is used whenever necessary to |
|
58 * indicate that indexing on DOMCharacterData is done in 16-bit units. |
|
59 * <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>. |
|
60 * @since DOM Level 1 |
|
61 */ |
|
62 class CDOM_EXPORT DOMCharacterData: public DOMNode { |
|
63 protected: |
|
64 // ----------------------------------------------------------------------- |
|
65 // Hidden constructors |
|
66 // ----------------------------------------------------------------------- |
|
67 /** @name Hidden constructors */ |
|
68 //@{ |
|
69 DOMCharacterData() {} |
|
70 DOMCharacterData(const DOMCharacterData &other) : DOMNode(other) {} |
|
71 //@} |
|
72 |
|
73 private: |
|
74 // ----------------------------------------------------------------------- |
|
75 // Unimplemented constructors and operators |
|
76 // ----------------------------------------------------------------------- |
|
77 /** @name Unimplemented operators */ |
|
78 //@{ |
|
79 DOMCharacterData & operator = (const DOMCharacterData &); |
|
80 //@} |
|
81 |
|
82 public: |
|
83 // ----------------------------------------------------------------------- |
|
84 // All constructors are hidden, just the destructor is available |
|
85 // ----------------------------------------------------------------------- |
|
86 /** @name Destructor */ |
|
87 //@{ |
|
88 /** |
|
89 * Destructor |
|
90 * |
|
91 */ |
|
92 virtual ~DOMCharacterData() {}; |
|
93 //@} |
|
94 |
|
95 // ----------------------------------------------------------------------- |
|
96 // Virtual DOMCharacterData interface |
|
97 // ----------------------------------------------------------------------- |
|
98 /** @name Functions introduced in DOM Level 1 */ |
|
99 //@{ |
|
100 // ----------------------------------------------------------------------- |
|
101 // Getter methods |
|
102 // ----------------------------------------------------------------------- |
|
103 /** |
|
104 * Returns the character data of the node that implements this interface. |
|
105 * |
|
106 * The DOM implementation may not put arbitrary limits on the amount of data that |
|
107 * may be stored in a <code>DOMCharacterData</code> node. However, |
|
108 * implementation limits may mean that the entirety of a node's data may |
|
109 * not fit into a single <code>XMLCh* String</code>. In such cases, the user |
|
110 * may call <code>substringData</code> to retrieve the data in |
|
111 * appropriately sized pieces. |
|
112 * @exception DOMException |
|
113 * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly. |
|
114 * @since DOM Level 1 |
|
115 */ |
|
116 virtual const XMLCh * getData() const = 0; |
|
117 |
|
118 /** |
|
119 * Returns the number of characters that are available through <code>data</code> and |
|
120 * the <code>substringData</code> method below. |
|
121 * |
|
122 * This may have the value |
|
123 * zero, i.e., <code>CharacterData</code> nodes may be empty. |
|
124 * @since DOM Level 1 |
|
125 */ |
|
126 virtual XMLSize_t getLength() const = 0; |
|
127 |
|
128 /** |
|
129 * Extracts a range of data from the node. |
|
130 * |
|
131 * @param offset Start offset of substring to extract. |
|
132 * @param count The number of characters to extract. |
|
133 * @return The specified substring. If the sum of <code>offset</code> and |
|
134 * <code>count</code> exceeds the <code>length</code>, then all |
|
135 * characters to the end of the data are returned. |
|
136 * @exception DOMException |
|
137 * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater |
|
138 * than the number of characters in <code>data</code>, or if the |
|
139 * specified <code>count</code> is negative. |
|
140 * @since DOM Level 1 |
|
141 */ |
|
142 virtual const XMLCh * substringData(XMLSize_t offset, |
|
143 XMLSize_t count) const = 0; |
|
144 |
|
145 // ----------------------------------------------------------------------- |
|
146 // String methods |
|
147 // ----------------------------------------------------------------------- |
|
148 /** |
|
149 * Append the string to the end of the character data of the node. |
|
150 * |
|
151 * Upon success, <code>data</code> provides access to the concatenation of |
|
152 * <code>data</code> and the <code>XMLCh* String</code> specified. |
|
153 * @param arg The <code>XMLCh* String</code> to append. |
|
154 * @exception DOMException |
|
155 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. |
|
156 * @since DOM Level 1 |
|
157 */ |
|
158 virtual void appendData(const XMLCh *arg) = 0; |
|
159 |
|
160 /** |
|
161 * Insert a string at the specified character offset. |
|
162 * |
|
163 * @param offset The character offset at which to insert. |
|
164 * @param arg The <code>XMLCh* String</code> to insert. |
|
165 * @exception DOMException |
|
166 * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater |
|
167 * than the number of characters in <code>data</code>. |
|
168 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. |
|
169 * @since DOM Level 1 |
|
170 */ |
|
171 virtual void insertData(XMLSize_t offset, const XMLCh *arg) = 0; |
|
172 |
|
173 /** |
|
174 * Remove a range of characters from the node. |
|
175 * |
|
176 * Upon success, |
|
177 * <code>data</code> and <code>length</code> reflect the change. |
|
178 * @param offset The offset from which to remove characters. |
|
179 * @param count The number of characters to delete. If the sum of |
|
180 * <code>offset</code> and <code>count</code> exceeds <code>length</code> |
|
181 * then all characters from <code>offset</code> to the end of the data |
|
182 * are deleted. |
|
183 * @exception DOMException |
|
184 * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater |
|
185 * than the number of characters in <code>data</code>, or if the |
|
186 * specified <code>count</code> is negative. |
|
187 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. |
|
188 * @since DOM Level 1 |
|
189 */ |
|
190 virtual void deleteData(XMLSize_t offset, |
|
191 XMLSize_t count) = 0; |
|
192 |
|
193 /** |
|
194 * Replace the characters starting at the specified character offset with |
|
195 * the specified string. |
|
196 * |
|
197 * @param offset The offset from which to start replacing. |
|
198 * @param count The number of characters to replace. If the sum of |
|
199 * <code>offset</code> and <code>count</code> exceeds <code>length</code> |
|
200 * , then all characters to the end of the data are replaced (i.e., the |
|
201 * effect is the same as a <code>remove</code> method call with the same |
|
202 * range, followed by an <code>append</code> method invocation). |
|
203 * @param arg The <code>XMLCh* String</code> with which the range must be |
|
204 * replaced. |
|
205 * @exception DOMException |
|
206 * INDEX_SIZE_ERR: Raised if the specified offset is negative or greater |
|
207 * than the number of characters in <code>data</code>, or if the |
|
208 * specified <code>count</code> is negative. |
|
209 * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. |
|
210 * @since DOM Level 1 |
|
211 */ |
|
212 virtual void replaceData(XMLSize_t offset, |
|
213 XMLSize_t count, |
|
214 const XMLCh *arg) = 0; |
|
215 |
|
216 /** |
|
217 * Sets the character data of the node that implements this interface. |
|
218 * |
|
219 * @param data The <code>XMLCh* String</code> to set. |
|
220 * @since DOM Level 1 |
|
221 */ |
|
222 virtual void setData(const XMLCh *data) = 0; |
|
223 //@} |
|
224 |
|
225 }; |
|
226 |
|
227 XERCES_CPP_NAMESPACE_END |
|
228 |
|
229 #endif |
|
230 |
|
231 |