1 | /* |
2 | * This file is part of Soprano Project. |
3 | * |
4 | * Copyright (C) 2007-2011 Sebastian Trueg <trueg@kde.org> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef LITERAL_VALUE_H |
23 | #define LITERAL_VALUE_H |
24 | |
25 | #include "soprano_export.h" |
26 | |
27 | #include <QtCore/QVariant> |
28 | #include <QtCore/QSharedDataPointer> |
29 | |
30 | #include "languagetag.h" |
31 | |
32 | |
33 | namespace Soprano |
34 | { |
35 | /** |
36 | * \class LiteralValue literalvalue.h Soprano/LiteralValue |
37 | * |
38 | * \brief Represents a literal value of an RDF Node. |
39 | * |
40 | * LiteralValue is based on QVariant to support |
41 | * a subset of the XML Schema types that are compatible |
42 | * with QT types. |
43 | * |
44 | * The following types are supported natively including |
45 | * automatic type conversion. Other types are represented |
46 | * as strings. |
47 | * |
48 | * \li int (Vocabulary::XMLSchema::xsdInt) |
49 | * \li qlonglong (Vocabulary::XMLSchema::xsdLong) |
50 | * \li unsigned int (Vocabulary::XMLSchema::unsignedInt) |
51 | * \li qulonglong (Vocabulary::XMLSchema::unsignedLong) |
52 | * \li bool (Vocabulary::XMLSchema::boolean) |
53 | * \li double and float (Vocabulary::XMLSchema::xsdDouble) (float values are always converted to double) |
54 | * \li QString (Vocabulary::XMLSchema::string or Vocabulary::RDF::XMLLiteral) |
55 | * \li QDate (Vocabulary::XMLSchema::date) |
56 | * \li QTime (Vocabulary::XMLSchema::time) |
57 | * \li QDateTime (Vocabulary::XMLSchema::dateTime) |
58 | * \li QByteArray (Vocabulary::XMLSchema::base64Binary) |
59 | * |
60 | * Literal values can be converted from strings via fromString(). |
61 | * |
62 | * \sa Vocabulary::XMLSchema |
63 | * |
64 | * \author Sebastian Trueg <trueg@kde.org> |
65 | */ |
66 | class SOPRANO_EXPORT LiteralValue |
67 | { |
68 | public: |
69 | //@{ |
70 | /** |
71 | * Create an empty literal value |
72 | */ |
73 | LiteralValue(); |
74 | |
75 | /** |
76 | * Destructor |
77 | */ |
78 | ~LiteralValue(); |
79 | |
80 | /** |
81 | * Default copy constructor |
82 | */ |
83 | LiteralValue( const LiteralValue& other ); |
84 | |
85 | /** |
86 | * Creates a new LiteralValue from a QVariant. |
87 | * User types are not supported. If v contains an |
88 | * unsupported type an invalid LiteralValue is created. |
89 | * |
90 | * \sa fromVariant() |
91 | */ |
92 | LiteralValue( const QVariant& v ); |
93 | |
94 | /** |
95 | * Creates a literal value of type int (i.e. |
96 | * http://www.w3.org/2001/XMLSchema#int) |
97 | */ |
98 | LiteralValue( int i ); |
99 | |
100 | /** |
101 | * Creates a literal value of type long long (i.e. |
102 | * http://www.w3.org/2001/XMLSchema#long) |
103 | */ |
104 | LiteralValue( qlonglong i ); |
105 | |
106 | /** |
107 | * Creates a literal value of type unsigned int (i.e. |
108 | * http://www.w3.org/2001/XMLSchema#unsignedInt) |
109 | */ |
110 | LiteralValue( uint i ); |
111 | |
112 | /** |
113 | * Creates a literal value of type unsigned long long (i.e. |
114 | * http://www.w3.org/2001/XMLSchema#unsignedLong) |
115 | */ |
116 | LiteralValue( qulonglong i ); |
117 | |
118 | /** |
119 | * Creates a literal value of type bool (i.e. |
120 | * http://www.w3.org/2001/XMLSchema#boolean) |
121 | */ |
122 | LiteralValue( bool b ); |
123 | |
124 | /** |
125 | * Creates a literal value of type double (i.e. |
126 | * http://www.w3.org/2001/XMLSchema#double) |
127 | */ |
128 | LiteralValue( double d ); |
129 | |
130 | /** |
131 | * Creates a literal value of type QString (i.e. |
132 | * http://www.w3.org/2001/XMLSchema#string) |
133 | * \param string The value of the new literal interpreted |
134 | * as UTF-8 encoded string. |
135 | */ |
136 | LiteralValue( const char* string ); |
137 | |
138 | /** |
139 | * Creates a literal value of type QString (i.e. |
140 | * http://www.w3.org/2001/XMLSchema#string) |
141 | */ |
142 | LiteralValue( const QLatin1String& string ); |
143 | |
144 | /** |
145 | * Creates a literal value of type QString (i.e. |
146 | * http://www.w3.org/2001/XMLSchema#string) |
147 | */ |
148 | LiteralValue( const QString& string ); |
149 | |
150 | /** |
151 | * Creates a literal value of type QDate (i.e. |
152 | * http://www.w3.org/2001/XMLSchema#date) |
153 | */ |
154 | LiteralValue( const QDate& date ); |
155 | |
156 | /** |
157 | * Creates a literal value of type QTime (i.e. |
158 | * http://www.w3.org/2001/XMLSchema#time) |
159 | */ |
160 | LiteralValue( const QTime& time ); |
161 | |
162 | /** |
163 | * Creates a literal value of type QDateTime (i.e. |
164 | * http://www.w3.org/2001/XMLSchema#dateTime) |
165 | */ |
166 | LiteralValue( const QDateTime& datetime ); |
167 | |
168 | /** |
169 | * Creates a literal value of type QByteArray (i.e. |
170 | * http://www.w3.org/2001/XMLSchema#base64Binary) |
171 | */ |
172 | LiteralValue( const QByteArray& data ); |
173 | //@} |
174 | |
175 | //@{ |
176 | /** |
177 | * Creates a copy of \a other |
178 | */ |
179 | LiteralValue& operator=( const LiteralValue& other ); |
180 | |
181 | /** |
182 | * Assigns \a i to this literal value. The type will |
183 | * be set to int (http://www.w3.org/2001/XMLSchema#int) |
184 | * unless it is already set to a compatible type. |
185 | * |
186 | * Thus, a type http://www.w3.org/2001/XMLSchema#integer |
187 | * or http://www.w3.org/2001/XMLSchema#decimal will not |
188 | * be changed. |
189 | * |
190 | * Be aware that Soprano does not check the ranges of the |
191 | * integer value yet. |
192 | */ |
193 | LiteralValue& operator=( int i ); |
194 | |
195 | /** |
196 | * Assigns \a i to this literal value. The type will |
197 | * be set to long (http://www.w3.org/2001/XMLSchema#long). |
198 | */ |
199 | LiteralValue& operator=( qlonglong i ); |
200 | |
201 | /** |
202 | * Assigns \a i to this literal value. The type will |
203 | * be set to uint (http://www.w3.org/2001/XMLSchema#unsignedInt) |
204 | * unless it is already set to a compatible type. |
205 | * |
206 | * Thus, a type http://www.w3.org/2001/XMLSchema#unsignedShort |
207 | * will not be changed. |
208 | * |
209 | * Be aware that Soprano does not check the ranges of the |
210 | * unsigned value yet. |
211 | */ |
212 | LiteralValue& operator=( uint i ); |
213 | |
214 | /** |
215 | * Assigns \a i to this literal value. The type will |
216 | * be set to unsigned long (http://www.w3.org/2001/XMLSchema#unsignedLong). |
217 | */ |
218 | LiteralValue& operator=( qulonglong i ); |
219 | |
220 | /** |
221 | * Assigns \a b to this literal value. The type will |
222 | * be set to bool (http://www.w3.org/2001/XMLSchema#boolean). |
223 | */ |
224 | LiteralValue& operator=( bool b ); |
225 | |
226 | /** |
227 | * Assigns \a d to this literal value. The type will |
228 | * be set to double (http://www.w3.org/2001/XMLSchema#double). |
229 | */ |
230 | LiteralValue& operator=( double d ); |
231 | |
232 | /** |
233 | * Assigns \a s to this literal value. The type will |
234 | * be set to string (http://www.w3.org/2001/XMLSchema#string). |
235 | */ |
236 | LiteralValue& operator=( const QString& s ); |
237 | |
238 | /** |
239 | * Assigns \a s to this literal value. The type will |
240 | * be set to string (http://www.w3.org/2001/XMLSchema#string). |
241 | */ |
242 | LiteralValue& operator=( const QLatin1String& s ); |
243 | |
244 | /** |
245 | * Assigns \a date to this literal value. The type will |
246 | * be set to %data (http://www.w3.org/2001/XMLSchema#date). |
247 | */ |
248 | LiteralValue& operator=( const QDate& date ); |
249 | |
250 | /** |
251 | * Assigns \a time to this literal value. The type will |
252 | * be set to %time (http://www.w3.org/2001/XMLSchema#time). |
253 | */ |
254 | LiteralValue& operator=( const QTime& time ); |
255 | |
256 | /** |
257 | * Assigns \a datetime to this literal value. The type will |
258 | * be set to dateTime (http://www.w3.org/2001/XMLSchema#dateTime). |
259 | */ |
260 | LiteralValue& operator=( const QDateTime& datetime ); |
261 | |
262 | /** |
263 | * Assigns \a datetime to this literal value. The type will |
264 | * be set to ByteArray (http://www.w3.org/2001/XMLSchema#base64Binary). |
265 | */ |
266 | LiteralValue& operator=( const QByteArray& data ); |
267 | //@} |
268 | |
269 | //@{ |
270 | bool operator==( const LiteralValue& other ) const; |
271 | |
272 | bool operator!=( const LiteralValue& other ) const; |
273 | //@} |
274 | |
275 | //@{ |
276 | bool isValid() const; |
277 | |
278 | /** |
279 | * Determines if this literal value is a plain literal. |
280 | * Plain literals have no data type, but may have an optional language tag. |
281 | * |
282 | * \return \c true if this literal is plain |
283 | */ |
284 | bool isPlain() const; |
285 | |
286 | bool isInt() const; |
287 | bool isInt64() const; |
288 | bool isUnsignedInt() const; |
289 | bool isUnsignedInt64() const; |
290 | bool isBool() const; |
291 | bool isDouble() const; |
292 | |
293 | /** |
294 | * Check if the literal contains a string value. |
295 | * Be aware that unknown literal types are also |
296 | * treated as strings. In that case compare |
297 | * dataTypeUrl. |
298 | */ |
299 | bool isString() const; |
300 | bool isDate() const; |
301 | bool isTime() const; |
302 | bool isDateTime() const; |
303 | bool isByteArray() const; |
304 | //@} |
305 | |
306 | //@{ |
307 | int toInt() const; |
308 | qlonglong toInt64() const; |
309 | uint toUnsignedInt() const; |
310 | qulonglong toUnsignedInt64() const; |
311 | bool toBool() const; |
312 | double toDouble() const; |
313 | |
314 | /** |
315 | * Each type can be converted to a string which means that |
316 | * toString in combination with dataTypeUrl provides all the |
317 | * information necessary to store this literal as RDF. |
318 | * |
319 | * The string value is cached so calling it multiple times in |
320 | * a row is fast. |
321 | * |
322 | * \warning For historical reasons this is not a user-readable representation. |
323 | * |
324 | * \sa Node::toString |
325 | */ |
326 | QString toString() const; |
327 | QDate toDate() const; |
328 | QTime toTime() const; |
329 | QDateTime toDateTime() const; |
330 | QByteArray toByteArray() const; |
331 | //@} |
332 | |
333 | //@{ |
334 | /** |
335 | * The XML Schema datatype URI. |
336 | * |
337 | * \return The URI of the XML Schema type referring to the |
338 | * stored type or an empty QUrl if the LiteralValue is empty or |
339 | * is a plain literal. |
340 | */ |
341 | QUrl dataTypeUri() const; |
342 | |
343 | /** |
344 | * The language tag. |
345 | * |
346 | * \return The language tag of the plain literal or an empty LanguageTag |
347 | * if the LiteralValue has no language or it is a typed literal. |
348 | */ |
349 | LanguageTag language() const; |
350 | |
351 | /** |
352 | * The type of the data. |
353 | * |
354 | * \return The QVariant type of the stored data or QVariant::Invalid |
355 | * if it is an empty value. |
356 | */ |
357 | QVariant::Type type() const; |
358 | |
359 | /** |
360 | * The literal value represented in a QVariant. |
361 | * Be aware that the RDF typing information is lost |
362 | * in the converted variant. |
363 | */ |
364 | QVariant variant() const; |
365 | //@} |
366 | |
367 | /** |
368 | * Create a LiteralValue object by parsing string \a value based on \a type. |
369 | * If \a type is unknown a simple string LiteralValue object is returned |
370 | * containing the plain string \a value. |
371 | * |
372 | * \sa fromString(const QString&, const QUrl&) |
373 | */ |
374 | static LiteralValue fromString( const QString& value, QVariant::Type type ); |
375 | |
376 | /** |
377 | * Create a LiteralValue object by parsing string \a value based on \a dataTypeUri. |
378 | * |
379 | * \param value The value of the literal. Might be converted based on \a dataTypeUri. |
380 | * |
381 | * \param dataTypeUri The data type URI. %Soprano can automatically convert all XML schema |
382 | * types. All other (unknown) types will be stored as a string value with the plain |
383 | * \a dataTypeUri as type. Thus, unknown literal types can still be used without |
384 | * automatic type conversion. (Be aware though, that changing the value of a LiteralValue |
385 | * instance will reset the type, ie. custom data type URIs will be lost.) |
386 | * |
387 | * Both an empty \a value and \a dataTypeUri will result in an invalid LiteralValue |
388 | * instance but an empty \a value with a valid \a dataTypeUri is possible. A valid |
389 | * \a value with an invalid \a dataTypeUri will result in a LiteralValue of type |
390 | * Vocabulary::XMLSchema::string. |
391 | * |
392 | * \return A newly created LiteralValue instance based on the provided \a value and |
393 | * \a dataTypeUri. |
394 | * |
395 | * \sa fromString(const QString&, QVariant::Type), Vocabulary::XMLSchema |
396 | */ |
397 | static LiteralValue fromString( const QString& value, const QUrl& dataTypeUri ); |
398 | |
399 | /** |
400 | * Create a LiteralValue object by converting \p value to the given \p dataType. |
401 | * |
402 | * If the type of the variant matches the \p dataType this method has the same |
403 | * effect as the constructor which takes a QVariant as parameter. However, this |
404 | * method supports automatic conversion for a set of types including: |
405 | * |
406 | * \li Conversion of different decimal types |
407 | * \li Conversion of everything to xsd:string |
408 | * \li Conversion of decimal types to xsd:dateTime (using QDateTime::fromTime_t()) |
409 | * |
410 | * \param value The value the created LiteralValue should have. If invalid an |
411 | * invalid LiteralValue will be created. |
412 | * \param dataType The RDF literal data type the created LiteralValue should have. |
413 | * If empty the result will be the same as providing \p value to the constructor |
414 | * of LiteralValue. No conversion will take place. |
415 | * |
416 | * \return A newly created Literalvalue instance based on the given \p value and |
417 | * \p dataType. |
418 | * |
419 | * \since 2.7 |
420 | */ |
421 | static LiteralValue fromVariant( const QVariant& value, const QUrl& dataType ); |
422 | |
423 | /** |
424 | * Create a plain LiteralValue object with an optional language tag. |
425 | * |
426 | * \param value The value of the literal. |
427 | * |
428 | * \param lang The language tag. |
429 | * |
430 | * Both an empty \a value and \a lang will result in an invalid LiteralValue |
431 | * instance but an empty \a value with a valid \a lang is possible. A valid |
432 | * \a value with an empty \a lang will result in a plain, untyped literal with no |
433 | * language tag. |
434 | * |
435 | * \return A newly created LiteralValue instance based on the provided \a value and |
436 | * \a lang. |
437 | */ |
438 | static LiteralValue createPlainLiteral( const QString& value, const LanguageTag& lang = LanguageTag() ); |
439 | |
440 | /** |
441 | * Convert an XML Schema URI into a QVariant::Type. |
442 | * \return The QVariant::Type corresponding to dataTypeUri or QVariant::Invalid |
443 | * if dataTypeUri is unknown. |
444 | */ |
445 | static QVariant::Type typeFromDataTypeUri( const QUrl& dataTypeUri ); |
446 | |
447 | /** |
448 | * Convert a QVariant::Type into an XML Schema URI. |
449 | * \return The XML Schema URI that corresponds to \p type or an empty QUrl if |
450 | * the type os unknown, i.e. can not be mapped to an XML Schema type. |
451 | */ |
452 | static QUrl dataTypeUriFromType( QVariant::Type type ); |
453 | |
454 | private: |
455 | class LiteralValueData; |
456 | class PlainData; |
457 | class TypedData; |
458 | QSharedDataPointer<LiteralValueData> d; |
459 | }; |
460 | |
461 | SOPRANO_EXPORT uint qHash( const LiteralValue& lit ); |
462 | } |
463 | |
464 | SOPRANO_EXPORT QDebug operator<<( QDebug dbg, const Soprano::LiteralValue& ); |
465 | |
466 | #endif |
467 | |