Apama  10.1.0.5
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
MapExtractor Class Reference

Provides a compile-time type-safe way to extract values from a map_t, with user-friendly error messages identifying the map and key within the map if any item is missing. More...

#include <map_extractor.hpp>

Public Member Functions

 MapExtractor (const map_t &map, const std::string &displayName)
 Construct a MapExtractor wrapping the specified map. More...
 
 MapExtractor (MapExtractor &&other)
 Construct a MapExtractor, moving the contents from another MapExtractor. More...
 
bool empty ()
 Returns true if the map is empty. More...
 
const map_tgetUnderlyingMap ()
 Returns a reference to the wrapped map. More...
 
std::string getDisplayName ()
 Returns the display name associated with this map. More...
 
std::string toString ()
 Returns a string representation of this object, including both the display name and map contents. More...
 
void checkNoItemsRemaining ()
 Checks that all entries in this map have been read (using one of the get functions in this class), throwing an exception listing any unexpected items. More...
 
template<typename T >
const is_convertable_t< T > get (const data_t &key)
 Returns a value of type T from the map, throwing an exception if the key is missing or the associated value is the empty data_t. More...
 
template<typename T >
const T get (const data_t &key, const T defaultValue)
 Returns a value of type T from the map, returning the default value if the key is missing or the associated value is the empty data_t. More...
 
MapExtractor getMap (const data_t &key, bool emptyIfMissing)
 Returns a MapExtractor wrapping a map_t from the map. More...
 
std::string getStringDisallowEmpty (const data_t &key)
 Returns a string value, throwing an exception if the key is missing, the associated value is the empty data_t or the string is empty. More...
 
std::string getStringDisallowEmpty (const data_t &key, std::string defaultValue)
 Returns a string value, returning the defaultValue if the key is missing, the associated value is the empty data_t or the string is empty. More...
 
std::string getStringAllowEmpty (const data_t &key)
 Returns a string value, throwing an exception if the key is missing or the associated value is the empty data_t. More...
 
std::string getStringAllowEmpty (const data_t &key, std::string defaultValue)
 Returns a string value, returning the defaultValue if the key is missing or the associated value is the empty data_t. More...
 

Detailed Description

Provides a compile-time type-safe way to extract values from a map_t, with user-friendly error messages identifying the map and key within the map if any item is missing.

Useful for handling message payload, metadata or plug-in configuration objects. Typical usage would involve creating an instance for accessing a plug-in's configuration, calling the appropriate get functions to extract all required information, before calling the checkNoItemsRemaining() function to produce a clear error if the user neglected any elements.

Constructor & Destructor Documentation

MapExtractor::MapExtractor ( const map_t map,
const std::string &  displayName 
)
inline

Construct a MapExtractor wrapping the specified map.

The lifetime of this object must be shorter than the lifetime of the wrapped map.

MapExtractor::MapExtractor ( MapExtractor &&  other)
inline

Construct a MapExtractor, moving the contents from another MapExtractor.

Member Function Documentation

void MapExtractor::checkNoItemsRemaining ( )
inline

Checks that all entries in this map have been read (using one of the get functions in this class), throwing an exception listing any unexpected items.

bool MapExtractor::empty ( )
inline

Returns true if the map is empty.

template<typename T >
const is_convertable_t<T> MapExtractor::get ( const data_t key)
inline

Returns a value of type T from the map, throwing an exception if the key is missing or the associated value is the empty data_t.

If the type T is one of double, int64_t, bool or std::string then the underlying value will automatically be converted to/from the string form as appropriate to convert it to the requested type. In this case the return is by value and is a copy of the underlying value. An exception will be thrown if the actually underlying data is not a type which can be converted to the requested type.

If the type T is one of the other types which can be stored in a data_t (including const char *) then no conversion will be attempted. In this case the return is by const reference to the underlying value. An exception will be thrown if the underlying data is not the requested type.

template<typename T >
const T MapExtractor::get ( const data_t key,
const T  defaultValue 
)
inline

Returns a value of type T from the map, returning the default value if the key is missing or the associated value is the empty data_t.

T can only be one of the primitive types contained within a data_t (including const char *). The return is by value as a copy of either the underlying value or of the defaultValue if the requested key is not in the map. The default value is also returned if the key is in the map, but the value is not of the requested type or convertable to the requested type.

std::string MapExtractor::getDisplayName ( )
inline

Returns the display name associated with this map.

MapExtractor MapExtractor::getMap ( const data_t key,
bool  emptyIfMissing 
)
inline

Returns a MapExtractor wrapping a map_t from the map.

If the key is missing or the associated value is the empty data_t and emptyIfMissing is true, returns a MapExtractor holding an empty map, else throws an exception.

std::string MapExtractor::getStringAllowEmpty ( const data_t key)
inline

Returns a string value, throwing an exception if the key is missing or the associated value is the empty data_t.

std::string MapExtractor::getStringAllowEmpty ( const data_t key,
std::string  defaultValue 
)
inline

Returns a string value, returning the defaultValue if the key is missing or the associated value is the empty data_t.

std::string MapExtractor::getStringDisallowEmpty ( const data_t key)
inline

Returns a string value, throwing an exception if the key is missing, the associated value is the empty data_t or the string is empty.

std::string MapExtractor::getStringDisallowEmpty ( const data_t key,
std::string  defaultValue 
)
inline

Returns a string value, returning the defaultValue if the key is missing, the associated value is the empty data_t or the string is empty.

const map_t& MapExtractor::getUnderlyingMap ( )
inline

Returns a reference to the wrapped map.

std::string MapExtractor::toString ( )

Returns a string representation of this object, including both the display name and map contents.

Intended for diagnostic purposes and not for identitifaction; the format of this string may change in the future.


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