CppWAMP
C++11 client library for the WAMP protocol
|
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 > | |
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... | |
Variant & | operator[] (SizeType index) |
Accesses an array element by index. More... | |
const Variant & | operator[] (SizeType index) const |
Accesses a constant array element by index. More... | |
Variant & | at (SizeType index) |
Accesses an array element by index. More... | |
const Variant & | at (SizeType index) const |
Accesses a constant array element by index. More... | |
Variant & | operator[] (const String &key) |
Accesses an object value by key. More... | |
Variant & | at (const String &key) |
Accesses an object value by key. More... | |
const Variant & | at (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 | |
Variant & | operator= (const Variant &other) |
Assigns a variant onto another variant. More... | |
Variant & | operator= (Variant &&other) noexcept |
Move-assigns from one variant into another. More... | |
template<typename T > | |
Variant & | operator= (T value) |
Assigns a value to a variant. More... | |
Variant & | operator= (Array array) |
Assigns an array variant to a variant. More... | |
template<typename T > | |
Variant & | operator= (std::vector< T > vec) |
Assigns a std::vector to a variant. More... | |
Variant & | operator= (Object object) |
Assigns an object variant to a variant. More... | |
template<typename T > | |
Variant & | operator= (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. | |
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:
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.
wamp::Variant::Variant | ( | T | value | ) |
Converting constructor taking an initial value.
Only participates in overload resolution when Variant::isValidArg<T>() == true
.
T | (Deduced) Value type which must be convertible to a bound type. |
*this == value
wamp::Variant::Variant | ( | Array | array | ) |
Converting constructor taking an initial Array value.
this->is<Array>() == true
*this == array
wamp::Variant::Variant | ( | std::vector< T > | vec | ) |
Converting constructor taking a std::vector
of initial Array values.
this->is<Array>() == true
*this == vec
wamp::Variant::Variant | ( | Object | object | ) |
Converting constructor taking an initial Object value.
this->is<Object>() == true
*this == object
wamp::Variant::Variant | ( | std::map< String, T > | map | ) |
Converting constructor taking a std::map
of key-value pairs.
this->is<Object>() == true
*this == map
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.
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.
T | The target type to convert to. |
error::Conversion | if the variant is not convertible to the destination type. |
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.
T | The target type of the result. |
error::Conversion | if the variant is not null and is not convertible to the destination type. |
Variant::SizeType wamp::Variant::size | ( | ) | const |
Returns the number of elements contained by the variant.
0
if the variant is null 1
if the variant is a boolean, number, or string TBound & wamp::Variant::as |
Returns a reference to the variant's bound value.
TBound | The bound type under which to interpret the variant. |
TBound
must match the variant's current bound type. error::Access | if TBound does not match the variant's current bound type. |
const TBound & wamp::Variant::as |
Returns a constant reference to the variant's bound value.
TBound | The bound type under which to interpret the variant. |
TBound
must match the variant's current bound type. error::Access | if TBound does not match the variant's current bound type. |
Variant::BoundTypeForId< id > & wamp::Variant::as |
Returns a reference to the variant's bound value.
id | The bound type id under which to interpret the variant. |
this->typeId() == id
error::Access | if this->typeId() != id . |
const Variant::BoundTypeForId< id > & wamp::Variant::as |
Returns a constant reference to the variant's bound value.
id | The bound type id under which to interpret the variant. |
this->typeId() == id
error::Access | if this->typeId() != id . |
Accesses an array element by index.
this->is<Array>() == true
this->size() > index
error::Access | if this->is<Array>() == false |
std::out_of_range | if index >= this->size() . |
Accesses a constant array element by index.
this->is<Array>() == true
this->size() > index
error::Access | if this->is<Array>() == false |
std::out_of_range | if index >= this->size() . |
Accesses an array element by index.
this->is<Array>() == true
this->size() > index
error::Access | if this->is<Array>() == false |
std::out_of_range | if index >= this->size() . |
Accesses a constant array element by index.
this->is<Array>() == true
this->size() > index
error::Access | if this->is<Array>() == false |
std::out_of_range | if index >= this->size() . |
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.
this->is<Object>() == true
error::Access | if this->is<Object>() == false |
Accesses an object value by key.
this->is<Object>() == true
this->as<Object>().count(key) > 0
error::Access | if this->is<Object>() == false |
std::out_of_range | if the key does not exist. |
Accesses a constant object value by key.
this->is<Object>() == true
this->as<Object>().count(key) > 0
error::Access | if this->is<Object>() == false |
std::out_of_range | if the key does not exist. |
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 |
bool wamp::Variant::operator!= | ( | const Variant & | other | ) | const |
Compares two variants for inequality.
The result is equivalant to !(lhs == rhs)
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 |
Assigns a variant onto another variant.
this->typeId() == other.typeId()
*this == other
Move-assigns from one variant into another.
other == null
Variant & wamp::Variant::operator= | ( | T | value | ) |
Assigns a value to a variant.
The variant's dynamic type will change to accomodate the assigned value.
*this == value
Assigns an array variant to a variant.
this->typeId() == TypeId::array
*this == array
Variant & wamp::Variant::operator= | ( | std::vector< T > | vec | ) |
Assigns a std::vector
to a variant.
this->typeId() == TypeId::array
*this == vec
Assigns an object variant to a variant.
this->typeId() == TypeId::object
*this == object
Assigns a std::map
to a variant.
this->typeId() == TypeId::object
*this == map
|
noexcept |
Swaps two variants.
Swaps two variant objects.
|
related |
Returns true
iff the variant's current dynamic type is numeric.
The numeric bound types are:
|
related |
Returns true
iff the variant's current dynamic type is scalar.
The scalar bound types are:
|
related |
Returns a textual representation of the variant's current dynamic type.
This function is intended for diagnostic purposes. Equivalent to:
|
related |
Returns a textual representation of a bound type.
This function is intended for diagnostic purposes.
TBound | The bound type from which a textual representation will be returned. |
|
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 |
|
related |
Compares a non-variant value with a variant for equality.
|
related |
Compares a variant with a null-terminated constant character array for equality.
true
iff variant.is<String>() && variant.as<String>() == str
|
related |
Compares a null-terminated constant character array with a variant for equality.
true
iff variant.is<String>() && variant.as<String>() == str
|
related |
Compares a variant with a null-terminated mutable character array for equality.
true
iff variant.is<String>() && variant.as<String>() == str
|
related |
Compares a null-terminated mutable character array with a variant for equality.
true
iff variant.is<String>() && variant.as<String>() == str
|
related |
Compares a variant with a non-variant value for inequality.
|
related |
Compares a non-variant value with a variant for inequality.
|
related |
Compares a variant with a null-terminated constant character array for inequality.
true
iff !variant.is<String>() || variant.as<String>() != str
|
related |
Compares a null-terminated constant character array with a variant for inequality.
true
iff !variant.is<String>() || variant.as<String>() != str
|
related |
Compares a variant with a null-terminated mutable character array for inequality.
true
iff !variant.is<String>() || variant.as<String>() != str
|
related |
Compares a null-terminated mutable character array with a variant for inequality.
true
iff !variant.is<String>() || variant.as<String>() != str
|
related |
Applies the given _static visitor) functor to the given variant.
V | (Deduced) The visitor type, conforming to StaticVisitor |
T | (Deduced) The Variant type |
|
related |
Applies the given binary visitor functor to the two given variants.
V | (Deduced) The visitor type, conforming to BinaryVisitor |
L | (Deduced) The left-hand Variant type |
R | (Deduced) The right-hand Variant type |
|
related |
Applies the given static visitor functor, with an operand value, to the given variant.
V | (Deduced) The visitor type, conforming to OperandVisitor |
T | (Deduced) The Variant type |
O | (Deduced) The value type of the operand |