This class stores a flexible map of strings and ints to KaRL variables FlexMap differs from Map in three distinct ways. More...

#include <FlexMap.h>

Inheritance diagram for madara::knowledge::containers::FlexMap:

[legend]

Collaboration diagram for madara::knowledge::containers::FlexMap:

[legend]

Public Member Functions
	FlexMap (const KnowledgeUpdateSettings &settings=KnowledgeUpdateSettings(), const std::string &delimiter=".")
	Default constructor. More...

	FlexMap (const std::string &name, KnowledgeBase &knowledge, const KnowledgeUpdateSettings &settings=KnowledgeUpdateSettings(), const std::string &delimiter=".")
	Constructor. More...

	FlexMap (const std::string &name, Variables &knowledge, const KnowledgeUpdateSettings &settings=KnowledgeUpdateSettings(), const std::string &delimiter=".")
	Constructor. More...

	FlexMap (const FlexMap &rhs)
	Copy constructor. More...

virtual	~FlexMap ()
	Destructor. More...

void	clear (void)
	Clears the map. More...

virtual BaseContainer *	clone (void) const
	Clones this container. More...

void	erase (const std::string &key, bool delete_subkeys=true)
	Erases a variable from the map. More...

void	exchange (FlexMap &other, bool refresh_keys=true, bool delete_keys=true)
	Exchanges the map at this location with the map at another location. More...

bool	exists (const std::string &key, bool first_level_key=false) const
	Checks if a key is in the map. More...

bool	exists (void) const
	Checks for the existence of the current location in the context. More...

std::string	get_debug_info (void)
	Returns the type of the container along with name and any other useful information. More...

std::string	get_delimiter (void)
	Gets the delimiter for adding and detecting subvariables. More...

std::string	get_name (void) const
	Returns the name of the container. More...

KnowledgeUpdateSettings	get_settings (void)
	Gets the update settings for the container. More...

bool	is_false (void) const
	Checks if the value in the record is false (0) More...

bool	is_true (void) const
	Checks if the value in the record is not false (0) More...

void	keys (std::vector< std::string > &curkeys, bool first_level_keys_only=true) const
	Returns the keys within the map. More...

void	modify (void)
	Mark the flex map as modified. More...

virtual bool	modify_if_false (BaseContainer &conditional)
	Modifies the container if the argument is false. More...

virtual bool	modify_if_true (BaseContainer &conditional)
	Modifies the container if the argument is true. More...

void	operator= (const FlexMap &rhs)
	Assignment operator. More...

void	operator= (knowledge::KnowledgeRecord::Integer value)
	Sets the location to the specified Integer. More...

void	operator= (int value)
	Sets the location to the specified int. More...

void	operator= (double value)
	Sets the location to the specified double. More...

void	operator= (const std::string value)
	Sets the location to the specified STL string. More...

void	operator= (const std::vector< KnowledgeRecord::Integer > &value)
	Sets the location to native integer vector of the provided values. More...

void	operator= (const std::vector< double > &value)
	Sets the location to native double vector of the provided values. More...

FlexMap	operator[] (const std::string &key)
	Retrieves a flex map at the keyed location. More...

FlexMap	operator[] (size_t index)
	Retrieves a flex map at the indexed location. More...

int	read_file (const std::string &filename)
	Read a file into a location in the map. More...

int	read_file (const std::string &filename, const KnowledgeUpdateSettings &settings)
	Read a file into a location in the map. More...

int	set (knowledge::KnowledgeRecord::Integer value=knowledge::KnowledgeRecord::MODIFIED)
	Sets the location within the map to the specified value. More...

int	set (KnowledgeRecord::Integer value, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (const knowledge::KnowledgeRecord::Integer *value, uint32_t size)
	Sets the location within the map to the specified value. More...

int	set (const knowledge::KnowledgeRecord::Integer *value, uint32_t size, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (const std::vector< KnowledgeRecord::Integer > &value)
	Sets the location within the map to the specified value. More...

int	set (const std::vector< KnowledgeRecord::Integer > &value, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (double value)
	Sets the location within the map to the specified value. More...

int	set (double value, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (const double *value, uint32_t size)
	Sets the location within the map to the specified value. More...

int	set (const double *value, uint32_t size, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (const std::vector< double > &value)
	Sets the location within the map to the specified value. More...

int	set (const std::vector< double > &value, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

int	set (const std::string &value)
	Sets the location within the map to the specified value. More...

int	set (const std::string &value, const KnowledgeUpdateSettings &settings)
	Sets the location within the map to the specified value. More...

void	set_delimiter (const std::string &delimiter)
	Sets the delimiter for adding and detecting subvariables. More...

int	set_file (const unsigned char *value, size_t size)
	Atomically sets the value of an index to an arbitrary string. More...

int	set_file (const unsigned char *value, size_t size, const KnowledgeUpdateSettings &settings)
	Atomically sets the value of an index to an arbitrary string. More...

int	set_index (size_t index, knowledge::KnowledgeRecord::Integer value)
	Sets an index within an array to a specified value. More...

int	set_index (size_t index, knowledge::KnowledgeRecord::Integer value, const KnowledgeUpdateSettings &settings)
	Sets an index within an array to a specified value. More...

int	set_index (size_t index, double value)
	Sets an index within a map to a specified value. More...

int	set_index (size_t index, double value, const KnowledgeUpdateSettings &settings)
	Sets an index within a map to a specified value. More...

int	set_jpeg (const unsigned char *value, size_t size)
	Atomically sets the value of an index to a JPEG image. More...

int	set_jpeg (const unsigned char *value, size_t size, const KnowledgeUpdateSettings &settings)
	Atomically sets the value of an index to a JPEG image. More...

void	set_name (const std::string &var_name, KnowledgeBase &knowledge)
	Sets the variable name that this refers to. More...

void	set_name (const std::string &var_name, Variables &knowledge)
	Sets the variable name that this refers to. More...

void	set_quality (uint32_t quality, const KnowledgeReferenceSettings &settings=KnowledgeReferenceSettings(false))
	Sets the quality of writing to a certain variable from this entity. More...

void	set_settings (const KnowledgeUpdateSettings &settings)
	Sets the update settings for the container. More...

size_t	size (bool first_level_keys_only=true) const
	Returns the size of the map. More...

void	to_container (BufferVector &target) const
	Fills a BufferVector container with all subkeys. More...

void	to_container (DoubleVector &target) const
	Fills a DoubleVector container with all subkeys. More...

void	to_container (IntegerVector &target) const
	Fills a IntegerVector container with all subkeys. More...

void	to_container (NativeDoubleVector &target) const
	Fills a NativeDoubleVector container with all subkeys. More...

void	to_container (NativeIntegerVector &target) const
	Fills a NativeIntegerVector container with all subkeys. More...

void	to_container (StringVector &target) const
	Fills a StringVector container with all subkeys. More...

void	to_container (Double &target) const
	Fills a Double container with the current location. More...

void	to_container (Integer &target) const
	Fills an Integer container with the current location. More...

void	to_container (String &target) const
	Fills a String container with the current location. More...

void	to_container (Map &target) const
	Fills a Map container with all subkeys. More...

double	to_double (void) const
	Returns the value at the location as a double. More...

knowledge::KnowledgeRecord::Integer	to_integer (void) const
	Returns the value at the location as an integer. More...

knowledge::KnowledgeRecord	to_record (void) const
	Retrieves a copy of the record from the current location. More...

std::string	to_string (void) const
	Returns the value at the location as a string. More...

Protected Attributes
MADARA_LOCK_TYPE	mutex_
	guard for access and changes More...

std::string	name_
	Prefix of variable. More...

KnowledgeUpdateSettings	settings_
	Settings for modifications. More...

Private Types
typedef std::map< std::string, VariableReference >	InternalFlexMap
	internal map of variable references More...

Private Member Functions
virtual std::string	get_debug_info_ (void)
	Returns the type of the container along with name and any other useful information. More...

virtual bool	is_false_ (void) const
	Polymorphic is false method which can be used to determine if at least one value in the container is false. More...

virtual bool	is_true_ (void) const
	Polymorphic is true method which can be used to determine if all values in the container are true. More...

virtual void	modify_ (void)
	Polymorphic modify method used by collection containers. More...

void	update_variable (void) const
	Updates the variable reference if necessary. More...

Private Attributes
ThreadSafeContext *	context_
	Variable context that we are modifying. More...

std::string	delimiter_
	Delimiter for the prefix to subvars. More...

VariableReference	variable_
	The current location variable. More...

Detailed Description

This class stores a flexible map of strings and ints to KaRL variables FlexMap differs from Map in three distinct ways.

First, it can use either integers (for easy multi-dimensional arrays) or strings like Map. Second, it allows for the usage of the [] operator to modify values. This can causes a small performance penalty due to the creation of FlexMaps with each [] operator, but is much more intuitive and an increase in quality-of-life. Third, because of its micromanagement of the variable names, it is slower than Map in almost all operations on variables within the map.

Definition at line 53 of file FlexMap.h.

Member Typedef Documentation

typedef std::map<std::string, VariableReference> madara::knowledge::containers::FlexMap::InternalFlexMap

private

internal map of variable references

Definition at line 681 of file FlexMap.h.

Constructor & Destructor Documentation

madara::knowledge::containers::FlexMap::FlexMap	(	const KnowledgeUpdateSettings &	settings = `KnowledgeUpdateSettings ()`,
		const std::string &	delimiter = `"."`
	)

Default constructor.

Parameters

settings	settings to apply by default
delimiter	the delimiter for variables in the map

Definition at line 6 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap::FlexMap	(	const std::string &	name,
		KnowledgeBase &	knowledge,
		const KnowledgeUpdateSettings &	settings = `KnowledgeUpdateSettings ()`,
		const std::string &	delimiter = `"."`
	)

Constructor.

Parameters

name	the name of the map within the variable context
knowledge	the variable context
settings	settings to apply by default
delimiter	the delimiter for variables in the map

Definition at line 14 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap::FlexMap	(	const std::string &	name,
		Variables &	knowledge,
		const KnowledgeUpdateSettings &	settings = `KnowledgeUpdateSettings ()`,
		const std::string &	delimiter = `"."`
	)

Constructor.

Parameters

name	the name of the map within the variable context
knowledge	the variable context
settings	settings to apply by default
delimiter	the delimiter for variables in the map

Definition at line 24 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap::FlexMap ( const FlexMap & rhs )

Copy constructor.

Definition at line 35 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap::~FlexMap ( )

virtual

Destructor.

Definition at line 43 of file FlexMap.cpp.

Member Function Documentation

void madara::knowledge::containers::FlexMap::clear ( void )

Clears the map.

This deletes all keys in the Flex Map from the context.

Definition at line 536 of file FlexMap.cpp.

madara::knowledge::containers::BaseContainer * madara::knowledge::containers::FlexMap::clone ( void ) const

virtual

Clones this container.

Returns: a deep copy of the container that must be managed by the user (i.e., you have to delete the return value)

Implements madara::knowledge::containers::BaseContainer.

Definition at line 152 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::erase	(	const std::string &	key,
		bool	delete_subkeys = `true`
	)

Erases a variable from the map.

Parameters

key	the variable to delete from the map
delete_subkeys	if true, delete all keys with the key prefix

Definition at line 555 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::exchange	(	FlexMap &	other,
		bool	refresh_keys = `true`,
		bool	delete_keys = `true`
	)

Exchanges the map at this location with the map at another location.

Parameters

other	the other integer to exchange with
refresh_keys	force a refresh of the keys in both maps to ensure all keys are swapped
delete_keys	delete any unused keys

Definition at line 516 of file FlexMap.cpp.

bool madara::knowledge::containers::FlexMap::exists	(	const std::string &	key,
		bool	first_level_key = `false`
	)		const

Checks if a key is in the map.

By default, this will check for an exact match (i.e., the exact string matches to an existing record). If you want to just check if the key exists in the next level, set first_level_key to true.

Parameters

key	the map key to check for
first_level_key	if true, checks for existence of key in the next level of map hierarchy. This is a more expensive version of exists. O (log N) vs. O (N)

Definition at line 680 of file FlexMap.cpp.

bool madara::knowledge::containers::FlexMap::exists ( void ) const

Checks for the existence of the current location in the context.

Checks if the value in the record is false (0)

Returns: true if location exists in map. False otherwise.; true if value is false

Definition at line 664 of file FlexMap.cpp.

std::string madara::knowledge::containers::FlexMap::get_debug_info ( void )

Returns the type of the container along with name and any other useful information.

The provided information should be useful for developers wishing to debug container operations, especially as it pertains to pending network operations (i.e., when used in conjunction with modify)

Returns: info in format {container}: {name}{ = value, if appropriate}

Definition at line 116 of file FlexMap.cpp.

std::string madara::knowledge::containers::FlexMap::get_debug_info_ ( void )

privatevirtual

Returns the type of the container along with name and any other useful information.

The provided information should be useful for developers wishing to debug container operations, especially as it pertains to pending network operations (i.e., when used in conjunction with modify)

Returns: info in format {container}: {name}{ = value, if appropriate}

Implements madara::knowledge::containers::BaseContainer.

Definition at line 146 of file FlexMap.cpp.

std::string madara::knowledge::containers::FlexMap::get_delimiter ( void )

Gets the delimiter for adding and detecting subvariables.

By default, MADARA uses a '.' delimiter for names like "com.madara.Var1". Other conventions can include '/' for ROS-like topic directory structures, e.g., com/madara/Var1.

Returns: the delimiter to use for variable demarcation

Definition at line 654 of file FlexMap.cpp.

std::string madara::knowledge::containers::BaseContainer::get_name ( void ) const

inlineinherited

Returns the name of the container.

Returns: name of the container

Definition at line 5 of file BaseContainer.inl.

madara::knowledge::KnowledgeUpdateSettings madara::knowledge::containers::BaseContainer::get_settings ( void )

inherited

Gets the update settings for the container.

Returns: the current settings

Definition at line 37 of file BaseContainer.cpp.

bool madara::knowledge::containers::FlexMap::is_false ( void ) const

Checks if the value in the record is false (0)

Returns: true if value is false

Definition at line 77 of file FlexMap.cpp.

bool madara::knowledge::containers::FlexMap::is_false_ ( void ) const

privatevirtual

Polymorphic is false method which can be used to determine if at least one value in the container is false.

Implements madara::knowledge::containers::BaseContainer.

Definition at line 1292 of file FlexMap.cpp.

bool madara::knowledge::containers::FlexMap::is_true ( void ) const

Checks if the value in the record is not false (0)

Returns: true if value is not false

Definition at line 52 of file FlexMap.cpp.

bool madara::knowledge::containers::FlexMap::is_true_ ( void ) const

privatevirtual

Polymorphic is true method which can be used to determine if all values in the container are true.

Implements madara::knowledge::containers::BaseContainer.

Definition at line 1286 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::keys	(	std::vector< std::string > &	curkeys,
		bool	first_level_keys_only = `true`
	)		const

Returns the keys within the map.

This can be an O(n) operation that checks for any key that has name{delimiter}key.

Parameters

curkeys	the results of the operation
first_level_keys_only	if true, only generate first level keys

Definition at line 712 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::modify ( void )

Mark the flex map as modified.

The map retains the same values but will resend values as if they had been modified.

Definition at line 93 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::modify_ ( void )

privatevirtual

Polymorphic modify method used by collection containers.

This method calls the modify method for this class. We separate the faster version (modify) from this version (modify_) to allow users the opportunity to have a fastery version that does not use polymorphic functions (generally virtual functions are half as efficient as normal function calls)

Implements madara::knowledge::containers::BaseContainer.

Definition at line 140 of file FlexMap.cpp.

bool madara::knowledge::containers::BaseContainer::modify_if_false ( BaseContainer & conditional )

virtualinherited

Modifies the container if the argument is false.

Parameters

conditional the container that must be false to modify

Returns: true if the container was modified

Definition at line 64 of file BaseContainer.cpp.

bool madara::knowledge::containers::BaseContainer::modify_if_true ( BaseContainer & conditional )

virtualinherited

Modifies the container if the argument is true.

Parameters

conditional the container that must be true to modify

Returns: true if the container was modified

Definition at line 44 of file BaseContainer.cpp.

void madara::knowledge::containers::FlexMap::operator= ( const FlexMap & rhs )

Assignment operator.

Parameters

rhs	value to copy

Definition at line 158 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( knowledge::KnowledgeRecord::Integer value )

Sets the location to the specified Integer.

Parameters

value value to set at location

Definition at line 174 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( int value )

Sets the location to the specified int.

Parameters

value value to set at location

Definition at line 181 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( double value )

Sets the location to the specified double.

Parameters

value value to set at location

Definition at line 188 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( const std::string value )

Sets the location to the specified STL string.

Parameters

value value to set at location

Definition at line 195 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( const std::vector< KnowledgeRecord::Integer > & value )

Sets the location to native integer vector of the provided values.

Parameters

value array of integers to set at the location

Returns: 0 if successful, -1 if key is null, and -2 if quality isn't high enough

Definition at line 202 of file FlexMap.cpp.

void madara::knowledge::containers::FlexMap::operator= ( const std::vector< double > & value )

Sets the location to native double vector of the provided values.

Parameters

value array of doubles to set at the location

Returns: 0 if successful, -1 if key is null, and -2 if quality isn't high enough

Definition at line 209 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap madara::knowledge::containers::FlexMap::operator[] ( const std::string & key )

Retrieves a flex map at the keyed location.

Parameters

key	the name of the variable entry

Returns: a flex map of the location in the map

Definition at line 442 of file FlexMap.cpp.

madara::knowledge::containers::FlexMap madara::knowledge::containers::FlexMap::operator[] ( size_t index )

Retrieves a flex map at the indexed location.

Parameters

index the index of the variable entry

Returns: a flex map of the location in the map

Definition at line 461 of file FlexMap.cpp.

int madara::knowledge::containers::FlexMap::read_file ( const std::string & filename )

Read a file into a location in the map.

Parameters

filename file to read

Definition at line 739 of file FlexMap.cpp.

int madara::knowledge::containers::FlexMap::read_file	(	const std::string &	filename,
		const KnowledgeUpdateSettings &	settings
	)

Read a file into a location in the map.

Parameters

filename	file to read
settings	settings to use when evaluating/updating

Definition at line 760 of file FlexMap.cpp.

int madara::knowledge::containers::FlexMap::set ( knowledge::KnowledgeRecord::Integer value = knowledge::KnowledgeRecord::MODIFIED )