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
33namespace 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
464SOPRANO_EXPORT QDebug operator<<( QDebug dbg, const Soprano::LiteralValue& );
465
466#endif
467