The Variant class provides utilities for working with QVariants. Working with QVariants can be tedious if you have to work with them without knowing the structure of the data they hold. So, if you need to do convert a QVariant or want to compare them look no futher. More...

#include <variant.hpp>

Classes
class	Iterator

Public Types
typedef bool(*	Comparison )(const void , const void )

typedef void (	Conversion )(const void *)

typedef void(*	IteratorDtorFunc )(void *)

typedef void (	IteratorCopyFunc )(void *)

typedef QVariant(*	IteratorValueFunc )(void *, int)

typedef void(*	IteratorIncFunc )(void *)

typedef void (	IteratorMoveFunc )(void *, int)

typedef int(*	IteratorDistanceFunc )(void , void )

typedef void (	IteratorStartEndFunc )(void *)

typedef bool(*	IteratorComparisonFunc )(void , void )

typedef int(*	IteratorCountFunc )(void *)

typedef void (	IteratorFindFunc )(void *, const QVariant &)

Static Public Member Functions
static bool	equal (const QVariant &left, const QVariant &right)

static bool	notEqual (const QVariant &left, const QVariant &right)

static bool	lessThan (const QVariant &left, const QVariant &right)

static bool	greaterThan (const QVariant &left, const QVariant &right)

static bool	lessEqualThan (const QVariant &left, const QVariant &right)

static bool	greaterEqualThan (const QVariant &left, const QVariant &right)

static bool	canCompare (const QVariant &left, const QVariant &right)

static bool	canCompare (const QVariant &left, int rightType)

template<typename Right >
static bool	canCompare (const QVariant &left)

template<typename Left , typename Right >
static bool	canCompare ()

static bool	canCompare (int leftType, int rightType)

static QVariant	convert (const QVariant &variant, int type)

template<typename T >
static QVariant	convert (const QVariant &variant)

template<typename T >
static bool	canConvert (const QVariant &variant)

static bool	canConvert (const QVariant &variant, int toType)

static bool	canConvert (int fromType, int toType)

template<typename T >
static T	toValue (const QVariant &variant)

template<typename T >
static void	registerType ()

template<typename T , typename Right >
static void	registerType ()

static void	registerType (int type, int rightType, Comparison equal, Comparison lessThan)

static void	registerType (int type, int rightType, Comparison equal, Comparison notEqual, Comparison less, Comparison greater, Comparison lessEqual, Comparison greaterEqual)

template<typename From , typename To >
static void	registerConversion (To (func)(const From &))

template<typename From , typename To >
static void	registerConversion ()

static void	registerConversion (int from, int to, Conversion func)

template<typename T >
static void	registerIterators (typename T::mapped_type a=(typename T::mapped_type ) 0)

template<typename T >
static void	registerIterators (typename T::value_type a=(typename T::value_type ) 0)

static Iterator	begin (QVariant &variant)

static Iterator	end (QVariant &variant)

static Iterator	find (QVariant &variant, QVariant ident)

static int	itemCount (const QVariant &variant)

static bool	isList (const QVariant &variant)

static bool	isList (int typeId)

static bool	isMap (const QVariant &variant)

static bool	isMap (int typeId)

static bool	isGeneric (const QVariant &variant)

static bool	isGeneric (int typeId)

static QVariantList	toList (QVariant variant)

static QVariantMap	toMap (QVariant variant)

template<typename... Items>
static QVariantList	buildList (const Items &...items)

static void *	stealPointer (QVariant &variant)

Detailed Description

The Variant class provides utilities for working with QVariants. Working with QVariants can be tedious if you have to work with them without knowing the structure of the data they hold. So, if you need to do convert a QVariant or want to compare them look no futher.

Warning: Do not use types with this class which use virtual methods as this can lead to crashes. If you want to use a type like this, register the pointer-type instead.

Comparisons: Variant provides multiple ways to compare two QVariants. First, if you haven't defined NURIA_NO_TEMPLATE_COMPARISON you're able to simply compare a QVariant to any class you registered to the Qt meta system: if (myQVariant < currentIndex) { // ...

Another possibility is to use the comparison methods as provided by Variant like equal or lessThan: if (Nuria::Variant::lessThan (myQVariant, currentIndex)) { // ...

To be able to compare QVariants you need to register your classes by using registerType.

Note: All registered classes must overload operator==() and operator<() correctly.

Comparisons are alyways 'smart'. If you try to compare two QVariants of non-comparable types, it will first try to convert the RHS QVariant to the type of the LHS QVariant. If this fails, it tries to convert the RHS to something the LHS can compare to. If this still fails, LHS is checked if it can be compared to QVariants. If yes these operators are used, if not false is returned. To check if two types are comparable use one of the many canCompare overloads.

See also: canCompare

Warning: A failed comparison always returns false!

Note: The LHS won't be touched. All conversions are done to the RHS only.

Conversions: Another feature that QVariant is lacking is the ability to convert a QVariant to or from a user type. This means you can register conversion functions which take type A and return a pointer to an instance of type B.

See also: convert canConvert registerConversion

It is also possible to check beforehand if a certain conversion is possible at all using one of the various canConvert() overloads:

By using the template version if (Nuria::Variant::canConvert< QString > (myQVariant)) { // ...
By using the type id of to target type if (Nuria::Variant::canConvert (myQVariant, QMetaType::QString)) { // ...
By using the type id of both the source and target type if (Nuria::Variant::canConvert (QMetaType::Int, QMetaType::QString)) { // ...

Note: Custom conversions take precedence over the default Qt ones!

Iterating over a variant: A variant can hold multiple items if it contains a QStringList or a QVariantList. Sometimes it would be neat if you could iterate over this list without knowing its exact type, right? This is where VARIANT_FOREACH comes in. This little macro works like Q_FOREACH, with the exception it always expects a QVariant instead of a container. VARIANT_FOREACH iterates over any iteratorable type.

See also: registerIterators

Example:

QVariant a ("Hello"), b (QStringList() << "One" << "Two" << "Three");
// Outputs: "Hello"
VARIANT_FOREACH(const QVariant &cur, a) qDebug() << cur;
//Outputs: "One" "Two" "Three" (on a line of their own)
VARIANT_FOREACH(const QVariant &cur, b) qDebug() << cur;

If you need more control though, there is Variant::Iterator for you. It works like all Qt STL-style iterators.

See also: begin end Iterator

Member Typedef Documentation

typedef bool(* Nuria::Variant::Comparison)(const void *, const void *)

Prototype of a comparison function.

typedef void*(* Nuria::Variant::Conversion)(const void *)

Prototype of a conversion function.

Member Function Documentation

static Iterator Nuria::Variant::begin ( QVariant & variant )

static

Returns the begin iterator of variant. If variant is invalid, the returned iterator will be equal to the end iterator.

template<typename... Items>

static QVariantList Nuria::Variant::buildList ( const Items &... items )

inlinestatic

Builds a QVariantList out of all arguments passed to the method. This does the same as QVariantList () << QVariant::fromValue (first) << ... But it's easier and shorter to read and write.

Note: This method implicitly converts passed arguments of type const char* to QString. You can disable this by defining NURIA_NO_CHAR_ARRAY_TO_QSTRING

static Iterator Nuria::Variant::end ( QVariant & variant )

static

Returns the end iterator of variant.

static Iterator Nuria::Variant::find	(	QVariant &	variant,
		QVariant	ident
	)

static

Returns an iterator pointing to the item with key ident if variant contains a map-like type. If variant contains a list-like type, it'll search for an item which matches ident. If variant is generic, the value will be matched to ident. Whatever check is done, if ident can't be found a invalid Iterator instance is returned.

Warning: This function does not work like its STL-style counterpart!

See also: Iterator::isValid

static bool Nuria::Variant::isGeneric ( const QVariant & variant )

static

Returns true if variant contains a generic type. A generic type is a type which isn't a map nor a list.

static bool Nuria::Variant::isGeneric ( int typeId )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static bool Nuria::Variant::isList ( const QVariant & variant )

static

Returns true if variant contains a iterable list.

Note: A list in the sense of: Doesn't have a key.

static bool Nuria::Variant::isList ( int typeId )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static bool Nuria::Variant::isMap ( const QVariant & variant )

static

Returns true if variant contains a iterable map.

static bool Nuria::Variant::isMap ( int typeId )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static int Nuria::Variant::itemCount ( const QVariant & variant )

static

Returns the item count in a QVariant. If variant contains a non-iterable type 1 is returned. If variant is invalid 0 is returned. If variant contains a iterable type the item count is returned.

template<typename From , typename To >

static void Nuria::Variant::registerConversion ( To *(*)(const From &) func )

inlinestatic

Registers a possible conversion from type From to type To. This method takes a pointer to a conversion method. This method must be static and must take an instance of const From & as only argument. The method must return a pointer to an instance of To. If conversion fails the function should return 0.

template<typename From , typename To >

static void Nuria::Variant::registerConversion ( )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Registers a automatically generated conversion function, which can convert a QVariant containing a instance of From to a QVariant containing a instance of To. This is possible if To has a constructor which accepts a instance of To. Prototype: From (const To &); or From (To);

static void Nuria::Variant::registerConversion	(	int	from,
		int	to,
		Conversion	func
	)

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Registers a possible conversion from from to to. The semantics of func are the same.

template<typename T >

static void Nuria::Variant::registerIterators ( typename T::mapped_type * a = (typename T::mapped_type *)0 )

inlinestatic

Registers a iteratorable type to the system so it can be used by Variant::Iterator and VARIANT_FOREACH.

template<typename T >

static void Nuria::Variant::registerIterators ( typename T::value_type * a = (typename T::value_type *)0 )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Overload for types which don't have keys (lists, vectors, ...)

template<typename T >

static void Nuria::Variant::registerType ( )

inlinestatic

Registers a class to the system. After this method has been is called it is possible to compare QVariants containing instances of this class.

Note: It is safe to call this method multiple times on the same class.; If you want to compare against plain QVariants see the overloads of this method.

A good place to do this would be for example the constructor of the specific class.

template<typename T , typename Right >

static void Nuria::Variant::registerType ( )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Same as the other registerType method, except that you can specify the type you want to compare your type to

static void Nuria::Variant::registerType	(	int	type,
		int	rightType,
		Comparison	equal,
		Comparison	lessThan
	)

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Registers a class without using templates. If you have implementations of all comparison operators for this type use the other overload of this method. type is the usertype id as reported by the Qt meta system.

static void Nuria::Variant::registerType	(	int	type,
		int	rightType,
		Comparison	equal,
		Comparison	notEqual,
		Comparison	less,
		Comparison	greater,
		Comparison	lessEqual,
		Comparison	greaterEqual
	)

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Registers a class without using templates. If you have implemented all comparison operators use this method.

static void* Nuria::Variant::stealPointer ( QVariant & variant )

static

Steals the pointer from variant and returns it. Works only for pointer types, that is, T* but not T. If variant is invalid, nullptr is returned. After return, variant will be invalid if it contained a pointer.

Note: Ownership of the returned pointer is transferred to the caller.

static QVariantList Nuria::Variant::toList ( QVariant variant )

static

Tries to convert variant to a QVariantList.

If variant is not a list nor a map, a list containing variant is returned.
If variant is a list, its contents are copied over.
If variant is a map, all values are copied to a list.
If variant is invalid, an empty QVariantList is returned.

static QVariantMap Nuria::Variant::toMap ( QVariant variant )

static

Tries to convert variant to a QVariantMap. This is only successful if:

variant contains a map of some type.
The key-type of the map can be converted to a QString.

If one of these rules fail, an empty QVariantMap is returned.

See also: isMap

template<typename T >

static T Nuria::Variant::toValue ( const QVariant & variant )

inlinestatic

Same as QVariant::value, but this method tries to convert using the convert method instead.

The documentation for this class was generated from the following file:

variant.hpp

Classes

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation