CppWAMP
C++11 client library for the WAMP protocol
wamp::Variant Class Reference

Discriminated union container that represents a JSON value. More...

#include <cppwamp/variant.hpp>

Public Types

using SizeType = Array::size_type
 Integer type used to access array elements.
 
using CharType = String::value_type
 Character type used by string variants.
 
Bound Types
using Null = wamp::Null
 Represents an empty value.
 
using Bool = wamp::Bool
 Boolean type.
 
using Int = wamp::Int
 Signed integer type.
 
using UInt = wamp::UInt
 Unsigned integer type.
 
using Real = wamp::Real
 Floating-point number type.
 
using String = wamp::String
 String type.
 
using Blob = wamp::Blob
 Binary data as an array of bytes.
 
using Array = wamp::Array
 Dynamic array of variants.
 
using Object = wamp::Object
 Dictionary of variants.
 

Public Member Functions

Observers
TypeId typeId () const
 Returns the id of the variant's current dynamic type.
 
 operator bool () const
 Returns false iff the variant is currently null.
 
template<typename TBound >
bool is () const
 Returns true iff the variant's current dynamic type matches the given TBound type parameter.
 
template<TypeId id>
bool is () const
 Returns true iff the variant's current dynamic type matches the given id template parameter.
 
template<typename T >
to () const
 Converts the variant's bound value to the given type. More...
 
template<typename T >
void to (T &value) const
 Converts the variant's bound value to the given type, and assigns the result to the given value reference. More...
 
template<typename T >
ValueTypeOf< T > valueOr (T &&fallback) const
 Obtains the variant's value converted to the given type, or the given fallback value if the variant is null. More...
 
SizeType size () const
 Returns the number of elements contained by the variant. More...
 
Access
template<typename TBound >
TBound & as ()
 Returns a reference to the variant's bound value. More...
 
template<typename TBound >
const TBound & as () const
 Returns a constant reference to the variant's bound value. More...
 
template<TypeId id>
BoundTypeForId< id > & as ()
 Returns a reference to the variant's bound value. More...
 
template<TypeId id>
const BoundTypeForId< id > & as () const
 Returns a constant reference to the variant's bound value. More...
 
Variantoperator[] (SizeType index)
 Accesses an array element by index. More...
 
const Variantoperator[] (SizeType index) const
 Accesses a constant array element by index. More...
 
Variantat (SizeType index)
 Accesses an array element by index. More...
 
const Variantat (SizeType index) const
 Accesses a constant array element by index. More...
 
Variantoperator[] (const String &key)
 Accesses an object value by key. More...
 
Variantat (const String &key)
 Accesses an object value by key. More...
 
const Variantat (const String &key) const
 Accesses a constant object value by key. More...
 
Comparison
bool operator== (const Variant &other) const
 Compares two variants for equality. More...
 
bool operator!= (const Variant &other) const
 Compares two variants for inequality. More...
 
bool operator< (const Variant &other) const
 Less-than comparison between two variants. More...
 
Modifiers
Variantoperator= (const Variant &other)
 Assigns a variant onto another variant. More...
 
Variantoperator= (Variant &&other) noexcept
 Move-assigns from one variant into another. More...
 
template<typename T >
Variantoperator= (T value)
 Assigns a value to a variant. More...
 
Variantoperator= (Array array)
 Assigns an array variant to a variant. More...
 
template<typename T >
Variantoperator= (std::vector< T > vec)
 Assigns a std::vector to a variant. More...
 
Variantoperator= (Object object)
 Assigns an object variant to a variant. More...
 
template<typename T >
Variantoperator= (std::map< String, T > map)
 Assigns a std::map to a variant. More...
 
void swap (Variant &other) noexcept
 Swaps two variants. More...
 

Related Functions

(Note that these are not member functions.)

Non-member Modifiers
void swap (Variant &v, Variant &w) noexcept
 Swaps two variant objects. More...
 
Non-member Observers
bool isNumber (const Variant &v)
 Returns true iff the variant's current dynamic type is numeric. More...
 
bool isScalar (const Variant &v)
 Returns true iff the variant's current dynamic type is scalar. More...
 
Variant::String typeNameOf (const Variant &v)
 Returns a textual representation of the variant's current dynamic type. More...
 
template<typename TBound >
Variant::String typeNameOf ()
 Returns a textual representation of a bound type. More...
 
Non-member Output
std::ostream & operator<< (std::ostream &out, const Array &a)
 Outputs the given Array to the given output stream.
 
std::ostream & operator<< (std::ostream &out, const Object &o)
 Outputs the given Object to the given output stream.
 
std::ostream & operator<< (std::ostream &out, const Variant &v)
 Outputs the given Variant to the given output stream.
 
std::string toString (const Array &a)
 Outputs the given Array to a new string.
 
std::string toString (const Object &o)
 Outputs the given Object to a new string.
 
std::string toString (const Variant &v)
 Outputs the given Variant to a new string.
 
Non-member Comparison
template<typename T >
bool operator== (const Variant &variant, const T &value)
 Compares a variant with a non-variant value for equality. More...
 
template<typename T >
bool operator== (const T &value, const Variant &variant)
 Compares a non-variant value with a variant for equality. More...
 
bool operator== (const Variant &variant, const Variant::CharType *str)
 Compares a variant with a null-terminated constant character array for equality. More...
 
bool operator== (const Variant::CharType *str, const Variant &variant)
 Compares a null-terminated constant character array with a variant for equality. More...
 
bool operator== (const Variant &variant, Variant::CharType *str)
 Compares a variant with a null-terminated mutable character array for equality. More...
 
bool operator== (Variant::CharType *str, const Variant &variant)
 Compares a null-terminated mutable character array with a variant for equality. More...
 
template<typename T >
bool operator!= (const Variant &variant, const T &value)
 Compares a variant with a non-variant value for inequality. More...
 
template<typename T >
bool operator!= (const T &value, const Variant &variant)
 Compares a non-variant value with a variant for inequality. More...
 
bool operator!= (const Variant &variant, const Variant::CharType *str)
 Compares a variant with a null-terminated constant character array for inequality. More...
 
bool operator!= (const Variant::CharType *str, const Variant &variant)
 Compares a null-terminated constant character array with a variant for inequality. More...
 
bool operator!= (const Variant &variant, Variant::CharType *str)
 Compares a variant with a null-terminated mutable character array for inequality. More...
 
bool operator!= (Variant::CharType *str, const Variant &variant)
 Compares a null-terminated mutable character array with a variant for inequality. More...
 
Non-member Visitation Functions (in visitor.hpp)
template<typename V , typename T >
ResultTypeOf< V > apply (V &&visitor, T &&variant)
 Applies the given _static visitor) functor to the given variant. More...
 
template<typename V , typename L , typename R >
ResultTypeOf< V > apply (V &&visitor, L &&leftVariant, R &&rightVariant)
 Applies the given binary visitor functor to the two given variants. More...
 
template<typename V , typename T , typename O >
ResultTypeOf< V > applyWithOperand (V &&visitor, T &&variant, O &&operand)
 Applies the given static visitor functor, with an operand value, to the given variant. More...
 

Metafunctions

template<TypeId typeId>
using BoundTypeForId = typename internal::FieldTypeForId< typeId >::Type
 Obtains the bound type associated with a particular TypeId.
 
template<typename T >
static constexpr bool isValidArg () noexcept
 Indicates that the given argument type is convertible to a bound type.
 
template<typename T >
static constexpr bool isInvalidArg () noexcept
 
template<typename T >
static constexpr bool isVariantArg () noexcept
 

Construction

template<typename TValue >
static Variant from (TValue &&value)
 Constructs a variant from a custom type.
 
 Variant () noexcept
 Constructs a null variant.
 
 Variant (const Variant &other)
 Copy constructor.
 
 Variant (Variant &&other) noexcept
 Move constructor.
 
template<typename T >
 Variant (T value)
 Converting constructor taking an initial value. More...
 
 Variant (Array array)
 Converting constructor taking an initial Array value. More...
 
template<typename T >
 Variant (std::vector< T > vec)
 Converting constructor taking a std::vector of initial Array values. More...
 
 Variant (Object object)
 Converting constructor taking an initial Object value. More...
 
template<typename T >
 Variant (std::map< String, T > map)
 Converting constructor taking a std::map of key-value pairs. More...
 
 ~Variant ()
 Destructor.
 

Detailed Description

Discriminated union container that represents a JSON value.

A Variant behaves similarly to a dynamically-typed Javascript variable. Their underlying type can change at runtime, depending on the actual values assigned to them. Variants play a central role in CppWAMP, as they are used to represent dynamic data exchanged with a WAMP peer.

Variants can hold any of the following value types:

  • Null : represents an empty or missing value
  • Bool : true or false
  • Numbers: as integer (Int, UInt), or floating point (Real)
  • String : only UTF-8 encoded strings are currently supported
  • Blob : binary data as an array of bytes
  • Array : dynamically-sized lists of variants
  • Object : dictionaries having string keys and variant values

Array and object variants are recursive composites: their element values are also variants which can themselves be arrays or objects.

The Args struct is a value type that bundles one or more variants into positional and/or keyword arguments, to be exchanged with a WAMP peer.

See also
Args

Constructor & Destructor Documentation

◆ Variant() [1/5]

template<typename T >
wamp::Variant::Variant ( value)

Converting constructor taking an initial value.

Only participates in overload resolution when Variant::isValidArg<T>() == true.

See also
Variant::from
Template Parameters
T(Deduced) Value type which must be convertible to a bound type.
Postcondition
*this == value

◆ Variant() [2/5]

wamp::Variant::Variant ( Array  array)

Converting constructor taking an initial Array value.

Postcondition
this->is<Array>() == true
*this == array

◆ Variant() [3/5]

template<typename T >
wamp::Variant::Variant ( std::vector< T >  vec)

Converting constructor taking a std::vector of initial Array values.

Precondition
The vector elements must be convertible to a bound type (checked at compile time).
Postcondition
this->is<Array>() == true
*this == vec

◆ Variant() [4/5]

wamp::Variant::Variant ( Object  object)

Converting constructor taking an initial Object value.

Postcondition
this->is<Object>() == true
*this == object

◆ Variant() [5/5]

template<typename T >
wamp::Variant::Variant ( std::map< String, T >  map)

Converting constructor taking a std::map of key-value pairs.

Postcondition
this->is<Object>() == true
*this == map
Precondition
The map values must be convertible to bound types (checked at compile time).

Member Function Documentation

◆ to() [1/2]

template<typename T >
T wamp::Variant::to

Converts the variant's bound value to the given type.

The variant is deemed convertible to the target type according to the following table:

Target, Variant-> Null Bool Int UInt Real String Array Object
Null true false false false false false false false
Bool false true true true true false false false
integer type false true true true true false false false
floating point type false true true true true false false false
String false false false false false true false false
Array false false false false false false true false
std::vector<T> false false false false false false maybe false
Object false false false false false false false true
std::map<String,T> false false false false false false false maybe
An `Array` is convertible to `std::vector<T>` iff all `Array` elements are
    convertible to `T`.

An `Object` is convertible to `std::map<String,T>` iff all Object values
    are convertible to `T`.

@tparam T The target type to convert to. Must be default-constructable.
        If T's default constructor is private, then T must grant friendship
        to wamp::ConversionAccess.
@return The converted value.
@pre The variant is convertible to the destination type.
@throws error::Conversion if the variant is not convertible to
        the destination type. 

◆ to() [2/2]

template<typename T >
void wamp::Variant::to ( T &  value) const

Converts the variant's bound value to the given type, and assigns the result to the given value reference.

Template Parameters
TThe target type to convert to.
Precondition
The variant is convertible to the destination type.
Exceptions
error::Conversionif the variant is not convertible to the destination type.

◆ valueOr()

template<typename T >
ValueTypeOf< T > wamp::Variant::valueOr ( T &&  fallback) const

Obtains the variant's value converted to the given type, or the given fallback value if the variant is null.

Template Parameters
TThe target type of the result.
Precondition
The variant is null, or is convertible to the destination type.
Exceptions
error::Conversionif the variant is not null and is not convertible to the destination type.

◆ size()

Variant::SizeType wamp::Variant::size ( ) const

Returns the number of elements contained by the variant.

Returns
0 if the variant is null
1 if the variant is a boolean, number, or string
The number of elements if the variant is an array
The number of members if the variant is an object

◆ as() [1/4]

template<typename TBound >
TBound & wamp::Variant::as

Returns a reference to the variant's bound value.

Template Parameters
TBoundThe bound type under which to interpret the variant.
Precondition
TBound must match the variant's current bound type.
Exceptions
error::Accessif TBound does not match the variant's current bound type.

◆ as() [2/4]

template<typename TBound >
const TBound & wamp::Variant::as

Returns a constant reference to the variant's bound value.

Template Parameters
TBoundThe bound type under which to interpret the variant.
Precondition
TBound must match the variant's current bound type.
Exceptions
error::Accessif TBound does not match the variant's current bound type.

◆ as() [3/4]

template<TypeId id>
Variant::BoundTypeForId< id > & wamp::Variant::as

Returns a reference to the variant's bound value.

Template Parameters
idThe bound type id under which to interpret the variant.
Precondition
this->typeId() == id
Exceptions
error::Accessif this->typeId() != id.

◆ as() [4/4]

template<TypeId id>
const Variant::BoundTypeForId< id > & wamp::Variant::as

Returns a constant reference to the variant's bound value.

Template Parameters
idThe bound type id under which to interpret the variant.
Precondition
this->typeId() == id
Exceptions
error::Accessif this->typeId() != id.

◆ operator[]() [1/3]

Variant & wamp::Variant::operator[] ( SizeType  index)

Accesses an array element by index.

Precondition
this->is<Array>() == true
this->size() > index
Exceptions
error::Accessif this->is<Array>() == false
std::out_of_rangeif index >= this->size().

◆ operator[]() [2/3]

const Variant & wamp::Variant::operator[] ( SizeType  index) const

Accesses a constant array element by index.

Precondition
this->is<Array>() == true
this->size() > index
Exceptions
error::Accessif this->is<Array>() == false
std::out_of_rangeif index >= this->size().

◆ at() [1/4]

Variant & wamp::Variant::at ( SizeType  index)

Accesses an array element by index.

Precondition
this->is<Array>() == true
this->size() > index
Exceptions
error::Accessif this->is<Array>() == false
std::out_of_rangeif index >= this->size().

◆ at() [2/4]

const Variant & wamp::Variant::at ( SizeType  index) const

Accesses a constant array element by index.

Precondition
this->is<Array>() == true
this->size() > index
Exceptions
error::Accessif this->is<Array>() == false
std::out_of_rangeif index >= this->size().

◆ operator[]() [3/3]

Variant & wamp::Variant::operator[] ( const String key)

Accesses an object value by key.

If there is no element under the given key, a null variant will be automatically inserted under that key before the reference is returned.

Precondition
this->is<Object>() == true
Exceptions
error::Accessif this->is<Object>() == false

◆ at() [3/4]

Variant & wamp::Variant::at ( const String key)

Accesses an object value by key.

Precondition
this->is<Object>() == true
this->as<Object>().count(key) > 0
Exceptions
error::Accessif this->is<Object>() == false
std::out_of_rangeif the key does not exist.

◆ at() [4/4]

const Variant & wamp::Variant::at ( const String key) const

Accesses a constant object value by key.

Precondition
this->is<Object>() == true
this->as<Object>().count(key) > 0
Exceptions
error::Accessif this->is<Object>() == false
std::out_of_rangeif the key does not exist.

◆ operator==()

bool wamp::Variant::operator== ( const Variant other) const

Compares two variants for equality.

The comparison is analogous to the Javascript === operator, and is performed according to the following matrix:

LHS, RHS-> Null Bool Int UInt Real String Array Object
Null true false false false false false false false
Bool false L==R false false false false false false
Int false false L==R L==R L==R false false false
UInt false false L==R L==R L==R false false false
Real false false L==R L==R L==R false false false
String false false false false false L==R false false
Array false false false false false false L==R false
Object false false false false false false false L==R

◆ operator!=()

bool wamp::Variant::operator!= ( const Variant other) const

Compares two variants for inequality.

The result is equivalant to !(lhs == rhs)

See also
Variant::operator==

◆ operator<()

bool wamp::Variant::operator< ( const Variant other) const

Less-than comparison between two variants.

This operator is provided to allow the use of variants in associative containers. The comparison is performed according to the following matrix:

LHS, RHS-> Null Bool Int UInt Real String Array Object
Null false false false false false false false false
Bool false L<R false false false false false false
Int false false L<R L<R L<R false false false
UInt false false L<R L<R L<R false false false
Real false false L<R L<R L<R false false false
String false false false false false L<R false false
Array false false false false false false L<R false
Object false false false false false false false L<R

◆ operator=() [1/7]

Variant & wamp::Variant::operator= ( const Variant other)

Assigns a variant onto another variant.

Postcondition
this->typeId() == other.typeId()
*this == other

◆ operator=() [2/7]

Variant & wamp::Variant::operator= ( Variant &&  other)
noexcept

Move-assigns from one variant into another.

Postcondition
other == null

◆ operator=() [3/7]

template<typename T >
Variant & wamp::Variant::operator= ( value)

Assigns a value to a variant.

The variant's dynamic type will change to accomodate the assigned value.

Precondition
The value must be convertible to a bound type (checked at compile time).
Postcondition
*this == value

◆ operator=() [4/7]

Variant & wamp::Variant::operator= ( Array  array)

Assigns an array variant to a variant.

Postcondition
this->typeId() == TypeId::array
*this == array

◆ operator=() [5/7]

template<typename T >
Variant & wamp::Variant::operator= ( std::vector< T >  vec)

Assigns a std::vector to a variant.

Precondition
The vector elements must be convertible to a bound type (checked at compile time).
Postcondition
this->typeId() == TypeId::array
*this == vec

◆ operator=() [6/7]

Variant & wamp::Variant::operator= ( Object  object)

Assigns an object variant to a variant.

Postcondition
this->typeId() == TypeId::object
*this == object

◆ operator=() [7/7]

template<typename T >
Variant & wamp::Variant::operator= ( std::map< String, T >  map)

Assigns a std::map to a variant.

Precondition
The map values must be convertible to a bound type (checked at compile time).
Postcondition
this->typeId() == TypeId::object
*this == map

◆ swap()

void wamp::Variant::swap ( Variant other)
noexcept

Swaps two variants.

See also
void swap(Variant& v, Variant& w) noexcept

Friends And Related Function Documentation

◆ swap()

void swap ( Variant v,
Variant w 
)
related

Swaps two variant objects.

See also
Variant::swap

◆ isNumber()

bool isNumber ( const Variant v)
related

Returns true iff the variant's current dynamic type is numeric.

The numeric bound types are:

◆ isScalar()

bool isScalar ( const Variant v)
related

Returns true iff the variant's current dynamic type is scalar.

The scalar bound types are:

◆ typeNameOf() [1/2]

Variant::String typeNameOf ( const Variant v)
related

Returns a textual representation of the variant's current dynamic type.

This function is intended for diagnostic purposes. Equivalent to:

Variant::typeNameOf<CurrentBoundType>()

◆ typeNameOf() [2/2]

template<typename TBound >
Variant::String typeNameOf ( )
related

Returns a textual representation of a bound type.

This function is intended for diagnostic purposes.

Template Parameters
TBoundThe bound type from which a textual representation will be returned.

◆ operator==() [1/6]

template<typename T >
bool operator== ( const Variant variant,
const T &  value 
)
related

Compares a variant with a non-variant value for equality.

The comparison is performed according to the following matrix:

Value, Variant-> Null Bool Int UInt Real String Blob Array Object
Null true false false false false false false false false
Bool false L==R false false false false false false false
integer type false false L==R L==R L==R false false false false
floating point type false false L==R L==R L==R false false false false
String false false false false false L==R false false false
Blob false false false false false false L==R false false
Array false false false false false false false L==R false
std::vector<T> false false false false false false false L==R false
Object false false false false false false false false L==R
std::map<String,T> false false false false false false false false L==R

◆ operator==() [2/6]

template<typename T >
bool operator== ( const T &  value,
const Variant variant 
)
related

Compares a non-variant value with a variant for equality.

See also
bool operator==(const Variant& variant, const T& value)

◆ operator==() [3/6]

bool operator== ( const Variant variant,
const Variant::CharType str 
)
related

Compares a variant with a null-terminated constant character array for equality.

Returns
true iff variant.is<String>() && variant.as<String>() == str

◆ operator==() [4/6]

bool operator== ( const Variant::CharType str,
const Variant variant 
)
related

Compares a null-terminated constant character array with a variant for equality.

Returns
true iff variant.is<String>() && variant.as<String>() == str

◆ operator==() [5/6]

bool operator== ( const Variant variant,
Variant::CharType str 
)
related

Compares a variant with a null-terminated mutable character array for equality.

Returns
true iff variant.is<String>() && variant.as<String>() == str

◆ operator==() [6/6]

bool operator== ( Variant::CharType str,
const Variant variant 
)
related

Compares a null-terminated mutable character array with a variant for equality.

Returns
true iff variant.is<String>() && variant.as<String>() == str

◆ operator!=() [1/6]

template<typename T >
bool operator!= ( const Variant variant,
const T &  value 
)
related

Compares a variant with a non-variant value for inequality.

See also
bool operator==(const Variant& variant, const T& value)

◆ operator!=() [2/6]

template<typename T >
bool operator!= ( const T &  value,
const Variant variant 
)
related

Compares a non-variant value with a variant for inequality.

See also
bool operator==(const Variant& variant, const T& value)

◆ operator!=() [3/6]

bool operator!= ( const Variant variant,
const Variant::CharType str 
)
related

Compares a variant with a null-terminated constant character array for inequality.

Returns
true iff !variant.is<String>() || variant.as<String>() != str

◆ operator!=() [4/6]

bool operator!= ( const Variant::CharType str,
const Variant variant 
)
related

Compares a null-terminated constant character array with a variant for inequality.

Returns
true iff !variant.is<String>() || variant.as<String>() != str

◆ operator!=() [5/6]

bool operator!= ( const Variant variant,
Variant::CharType str 
)
related

Compares a variant with a null-terminated mutable character array for inequality.

Returns
true iff !variant.is<String>() || variant.as<String>() != str

◆ operator!=() [6/6]

bool operator!= ( Variant::CharType str,
const Variant variant 
)
related

Compares a null-terminated mutable character array with a variant for inequality.

Returns
true iff !variant.is<String>() || variant.as<String>() != str

◆ apply() [1/2]

template<typename V , typename T >
ResultTypeOf< V > apply ( V &&  visitor,
T &&  variant 
)
related

Applies the given _static visitor) functor to the given variant.

Template Parameters
V(Deduced) The visitor type, conforming to StaticVisitor
T(Deduced) The Variant type

◆ apply() [2/2]

template<typename V , typename L , typename R >
ResultTypeOf< V > apply ( V &&  visitor,
L &&  leftVariant,
R &&  rightVariant 
)
related

Applies the given binary visitor functor to the two given variants.

Template Parameters
V(Deduced) The visitor type, conforming to BinaryVisitor
L(Deduced) The left-hand Variant type
R(Deduced) The right-hand Variant type

◆ applyWithOperand()

template<typename V , typename T , typename O >
ResultTypeOf< V > applyWithOperand ( V &&  visitor,
T &&  variant,
O &&  operand 
)
related

Applies the given static visitor functor, with an operand value, to the given variant.

Template Parameters
V(Deduced) The visitor type, conforming to OperandVisitor
T(Deduced) The Variant type
O(Deduced) The value type of the operand

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