Zorba
The XQuery Processor
Documentation
Live Demo
Modules
Download
Tools
Blog
Code
Main Page
Related Pages
Classes
Files
File List
File Members
swig
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
;
49
friend
class
StaticCollectionManager
;
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