Item.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef API_ITEM_H
18 #define API_ITEM_H
19 
20 /** \brief The Zorba Item interface.
21  *
22  * This class is the Zorba representation of an Item as defined in the
23  * XQuery 1.0 and XPath 2.0 Data Model (XDM); see http://www.w3.org/TR/xpath-datamodel/.
24  *
25  * Instances of the XDM are a sequence, i.e. an ordered collection of zero or more items.
26  * In the Zorba API, a sequence is represented by the ItemSequence class.
27  *
28  * The Item class is the union of all XQuery node and atomic types.
29  * The class provides functions to access the information of an Item. Note that not
30  * all functions are defined on every Item kind. If a function is called on an Item that
31  * does not provide the called function, an ZXQP0024_FUNCTION_NOT_IMPLEMENTED_FOR_ITEMTYPE error
32  * is raised.
33  *
34  * Instances of the Item class are always passed by copy. To check whether a given Item is valid
35  * isNull() can be called which returns true if the given Item is not valid and false otherwise.
36  * A new atomic Item can be created using the ItemFactory. A new node Item should be created
37  * by the result of a query.
38  */
39 class Item
40 {
41  friend class Iterator;
42  friend class StaticContext;
43  friend class DocumentManager;
44  friend class SingletonIterator;
45  friend class DynamicContext;
46  friend class ItemFactory;
47  friend class Collection;
48  friend class CollectionManager;
50  friend class ItemSequence;
51 private:
52  zorba::Item theItem;
53 
54 public:
55  /** \brief Default constructor
56  */
57  Item() {}
58  /** \brief Copy constructor
59  */
60  Item(const Item& aItem) : theItem(aItem.theItem) {}
61  /** \brief Constructor that is used to construct Items in the Zorba engine itself.
62  *
63  * This constructor is for internal use only.
64  */
65  Item(const zorba::Item& aZItem) : theItem(aZItem) {}
66 
67  /** \brief Static constructor
68  */
69  static Item createEmptyItem();
70 
71  /** \brief Get the string value of the Item.
72  *
73  * The string value is the string that is extracted by calling the fn:string function
74  * on the Item (see http://www.w3.org/TR/xpath-functions/#func-string).
75  * Note that this function is available for all types of Items.
76  *
77  * @return Item the string value of the Item.
78  * @throw ZorbaException if an error occured.
79  */
80  std::string getStringValue() const;
81 
82  /** \brief Serializes the object
83  *
84  * Returns a string with the value of the object serialized
85  *
86  * @return The string value of the Item.
87  * @throw ZorbaException if an error occured.
88  */
89  std::string serialize() const;
90 
91  /** \brief Serializes the object
92  *
93  * Returns a string with the value of the object serialized
94  *
95  * @param serOptions The serialization options for this Item
96  * @return The string value of the Item.
97  * @throw ZorbaException if an error occured.
98  */
99  std::string serialize(SerializationOptions serOptions) const;
100 
101  /** \brief Get the atomization value of the Item.
102  *
103  * The atomization value is the value that is returned by atomization
104  * (see http://www.w3.org/TR/xquery/#id-atomization).
105  * Note that this function is available for all types of Items.
106  *
107  * @return Item the atomization value of the Item.
108  * @throw ZorbaException if an error occured.
109  */
110  Iterator getAtomizationValue () const;
111 
112  /** \brief Get an iterator for the attributes of this (node) Item.
113  *
114  * Note that this function is only available for node Items.
115  *
116  * @return Iterator over the attributes of this node.
117  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
118  */
119  Iterator getAttributes () const;
120 
121  /** \brief Get the bool value of the boolean Item.
122  *
123  * Note that this function is only available for Items of type boolean.
124  *
125  * @return true if the boolean value is true, false otherwise.
126  * @throw ZorbaException if an error occured, e.g. the Item is not of type boolean.
127  */
128  bool getBooleanValue () const;
129 
130  /** \brief Get an iterator for the children of this (node) Item.
131  *
132  * Note that this function is only available for node Items.
133  *
134  * @return Iterator over the children of this node.
135  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
136  */
137  Iterator getChildren () const;
138 
139  /** \brief Get the effective boolean value of the Item.
140  *
141  * The effective boolean value is the result of applying the fn:boolean function on
142  * the Item (see http://www.w3.org/TR/xpath-functions/#func-boolean).
143  * Note that this function is available for all types of Items.
144  *
145  * @return Item the effective boolean value of the Item
146  * @throw ZorbaException if an error occured.
147  */
148  Item getEBV () const;
149 
150  /** \brief Get the int value of the Item.
151  *
152  * @return Item the int value of the Item.
153  * @throw ZorbaException if an error occured.
154  */
155  int getIntValue () const;
156 
157  /** \brief Get the int value of the Item.
158  *
159  * @return Item the int value of the Item.
160  * @throw ZorbaException if an error occured.
161  */
162  double getDoubleValue () const;
163 
164  /** \brief Get the long value of the Item.
165  *
166  * @return Item the long value of the Item.
167  * @throw ZorbaException if an error occured.
168  */
169  long long getLongValue () const;
170 
171  /** \brief Get the value of a QName's local name.
172  *
173  * Note that this function is only available for Items of type QName.
174  *
175  * @return String the local name of the QName.
176  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
177  */
178  std::string getLocalName () const;
179 
180  /** \brief Get the (optional) value of a QName's namespace.
181  *
182  * Note that this function is only available for Items of type QName.
183  *
184  * @return String the namespace URI of the QName.
185  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
186  */
187  std::string getNamespace () const;
188 
189  /** \brief Get a vector for the namespace bindings of this (element) Item.
190  *
191  * Note that this function is only available for element Items.
192  *
193  * @throw ZorbaException if an error occured, e.g. the Item is not of type element.
194  */
195  std::vector< std::pair< std::string, std::string > > getNamespaceBindings ();
196 
197  /** \brief Get the name of this (node) Item.
198  *
199  * Note that this function is only available for node Items.
200  *
201  * @return bool if the name of the node was retrieved successfully
202  * @param aNodeName the name of the node
203  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
204  */
205  bool getNodeName (Item &aNodeName) const;
206 
207  /** \brief Get parent of this (node) Item.
208  *
209  * Note that this function is only available for node Items.
210  *
211  * @return element or document parent node of this node.
212  * @throw ZorbaException if an error occured, e.g. the Item is not of type node.
213  */
214  Item getParent () const;
215 
216  /** \brief Get the (optional) value of a QName's prefix.
217  *
218  * Note that this function is only available for Items of type QName.
219  *
220  * @return String the prefix of the QName.
221  * @throw ZorbaException if an error occured, e.g. the Item is not a QName.
222  */
223  std::string getPrefix () const;
224 
225  /** \brief Get the type of the Item.
226  *
227  * See http://www.w3.org/TR/xpath-datamodel/#types.
228  * Note that this function is available for all types of Items.
229  *
230  * @return Item the type of the Item as a QName Item
231  * @throw ZorbaException if an error occured.
232  */
233  Item getType () const;
234  unsigned int getUnsignedIntValue () const;
235 
236  /** \brief Get the type of this (node) Item.
237  *
238  * Note that this function is only available for node Items.
239  *
240  * @return int the kind of this node (the avaialble kinds can be found in the store::StoreConsts class)
241  * @throw ZorbaException if an error occured (e.g. the Item is not of type node).
242  */
243  int getNodeKind() const;
244 
245  /** \brief Check if the Item is an atomic Item.
246  *
247  * Note that this function is available for all types of Items.
248  *
249  * @return true if the Item is an atomic Item, false otherwise.
250  */
251  bool isAtomic () const;
252 
253  /** \brief Check if the value of the Item is not a number (NaN).
254  *
255  * Note that this function is only available for numeric Items (e.g. Double or Float).
256  *
257  * @return true if the Item is NaN, false otherwise.
258  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
259  */
260  bool isNaN () const;
261 
262  /** \brief Check if the Item is a node Item.
263  *
264  * Note that this function is available for all types of Items.
265  *
266  * @return true if the Item is of type node, false otherwise.
267  */
268  bool isNode () const;
269 
270  /** \brief Check if the Item is null.
271  *
272  * If this function returns true, the Item is not valid.
273  * Note that this function is available for all types of Items.
274  *
275  * @return true if the Item is null, false otherwise.
276  */
277  bool isNull () const;
278 
279  /** \brief Check if the value of the Item is positive or negative infinity.
280  *
281  * Note that this function is only available for numeric Items (e.g. Double or Float).
282  *
283  * @return true if the Item is +/-INF, false otherwise.
284  * @throw ZorbaException if an error occured, e.g. the Item is not a numeric type.
285  */
286  bool isPosOrNegInf () const;
287 
288  /** \brief Free all resources aquired by this Item.
289  *
290  * After calling close() on an Item the Item is invalidated, i.e. a subsequent
291  * call to isNull() will return true.
292  *
293  * Note that calling this function is usually not necessary because close() is
294  * implicitly called by the destructor. Calling close() is only necessary if
295  * the resources aquired by an Item should be released before the Item goes out
296  * of scope, i.e. the destructor is called.
297  *
298  * Also note that this function is available for all types of Items.
299  */
300  void close();
301 
302  /** \brief Serializes the object
303  *
304  * Put the serialized object into the specified stream.
305  *
306  * @param aStream The stream to write the value of the Item.
307  * @throw ZorbaException if an error occured.
308  */
309  void serializeToStream(ZorbaIOStream & aStream) const;
310 
311  /** \brief Serializes the object
312  *
313  * Put the serialized object into the specified stream.
314  *
315  * @param aStream The stream to write the value of the Item.
316  * @param serOptions The serialization options for this Item
317  * @throw ZorbaException if an error occured.
318  */
319  void serializeToStream(ZorbaIOStream & aStream, SerializationOptions serOptions) const;
320 
321 }; // class Item
322 
323 #endif
blog comments powered by Disqus