dd::Properties Class Reference

The Properties class defines an interface for storing key=value pairs, where both key and value may be UTF-8 strings. More...

#include <properties.h>

Inheritance diagram for dd::Properties:

Public Types
typedef std::map< String_type, String_type >	Map
typedef std::map< String_type, String_type >::size_type	size_type
typedef Map::iterator	iterator
typedef Map::const_iterator	const_iterator

Public Member Functions
virtual iterator	begin ()=0
virtual const_iterator	begin () const =0
virtual iterator	end ()=0
virtual const_iterator	end () const =0
virtual bool	insert_values (const Properties &properties)=0
	Insert keys and values from a different property object. More...
virtual bool	insert_values (const String_type &raw_string)=0
	Insert keys and values from a raw string. More...
virtual size_type	size () const =0
	Get the number of key=value pairs. More...
virtual bool	empty () const =0
	Are there any key=value pairs? More...
virtual void	clear ()=0
	Remove all key=value pairs. More...
virtual bool	valid_key (const String_type &key) const =0
	Check if the submitted key is valid. More...
virtual bool	exists (const String_type &key) const =0
	Check for the existence of a key=value pair given the key. More...
virtual bool	remove (const String_type &key)=0
	Remove the key=value pair for the given key if it exists. More...
virtual const String_type	raw_string () const =0
	Create a string containing all key=value pairs as a semicolon separated list. More...
virtual bool	get (const String_type &key, String_type *value) const =0
	Get the string value for a given key. More...
template<typename Lex_type >
bool	get (const String_type &key, Lex_type *value, MEM_ROOT *mem_root) const
	Get the lex string value for a given key. More...
template<typename Value_type >
bool	get (const String_type &key, Value_type *value) const
	Get the string value for the key and convert it to the appropriate type. More...
virtual bool	set (const String_type &key, const String_type &value)=0
	Add a new key=value pair where the value is a string. More...
template<typename Value_type >
bool	set (const String_type &key, Value_type value)
	Convert the value to a string and set it for the given key. More...
	Properties ()=default
	Properties (const Properties &)=default
Properties &	operator= (const Properties &)=delete
virtual	~Properties ()=default

Static Public Member Functions
template<typename T >
static bool	from_str (const String_type &number, T *value)
	Convert a string to a value of an integral type. More...
static bool	from_str (const String_type &bool_str, bool *value)
	Convert string to bool. More...
template<class T >
static String_type	to_str (T value)
	Convert a value of an integral type (including bool) to a string. More...
static Properties *	parse_properties (const String_type &raw_properties)
	Parse the submitted string for properties on the format "key=value;key=value;...". More...

Detailed Description

The Properties class defines an interface for storing key=value pairs, where both key and value may be UTF-8 strings.

The interface contains functions for testing whether a key exists, replacing or removing key=value pairs, iteration etc. The interface also defines template functions for converting between strings and various primitive types.

Please note that in debug builds, the get() functions will assert that the key exists. This is to make sure that non-existing keys are handled explicitly at the client side.

The raw_string() function returns a semicolon separated list of all key=value pairs. Characters '=' and ';' that are part of key or value are escaped using the '\' as an escape character. The escape character itself must also be escaped if being part of key or value.

Examples of usage:

Add key=value: p->set("akey=avalue");

Add a numeric value: p->set("intvalue", 1234);

Get values: int32 num; p->get("intvalue", &num);

Get raw string: String_type mylist= p->raw_string();

Further comments can be found in the files properties_impl.{h,cc} where the interface is implemented.

Member Typedef Documentation

const_iterator

typedef Map::const_iterator dd::Properties::const_iterator

iterator

typedef Map::iterator dd::Properties::iterator

Map

typedef std::map<String_type, String_type> dd::Properties::Map

size_type

typedef std::map<String_type,String_type>::size_type dd::Properties::size_type

Constructor & Destructor Documentation

Properties() [1/2]

dd::Properties::Properties ( )

default

Properties() [2/2]

dd::Properties::Properties ( const Properties &  )

default

~Properties()

virtual dd::Properties::~Properties ( )

virtualdefault

Member Function Documentation

begin() [1/2]

virtual const_iterator dd::Properties::begin ( ) const

pure virtual

Implemented in dd::Properties_impl.

begin() [2/2]

virtual iterator dd::Properties::begin ( )

pure virtual

Implemented in dd::Properties_impl.

clear()

virtual void dd::Properties::clear ( )

pure virtual

Remove all key=value pairs.

Implemented in dd::Properties_impl.

empty()

virtual bool dd::Properties::empty ( ) const

pure virtual

Are there any key=value pairs?

Returns

true if there is no key=value pair, else false.

Implemented in dd::Properties_impl.

end() [1/2]

virtual const_iterator dd::Properties::end ( ) const

pure virtual

Implemented in dd::Properties_impl.

end() [2/2]

virtual iterator dd::Properties::end ( )

pure virtual

Implemented in dd::Properties_impl.

exists()

virtual bool dd::Properties::exists ( const String_type &  key ) const

pure virtual

Check for the existence of a key=value pair given the key.

Parameters

key	Key to be checked.

Returns

true if the given key exists, false otherwise.

Implemented in dd::Properties_impl.

from_str() [1/2]

bool dd::Properties::from_str ( const String_type &  bool_str, bool *  value  )

static

Convert string to bool.

Valid values are "true", "false", and decimal numbers, where "0" will be taken to mean false, and numbers != 0 will be taken to mean true.

Parameters

	bool_str	String containing boolean value to convert.
[out]	value	Converted value.

Returns

operation status.

Return values

true	if an error occurred
false	if success

from_str() [2/2]

template<typename T >

bool dd::Properties::from_str ( const String_type &  number, T *  value  )

static

Convert a string to a value of an integral type.

Verify correct sign, check for overflow and conversion errors.

Template Parameters

T	Value type.

Parameters

	number	String containing integral value to convert.
[out]	value	Converted value.

Returns

operation status.

Return values

true	if an error occurred
false	if success

get() [1/3]

template<typename Lex_type >

bool dd::Properties::get	(	const String_type &	key,
		Lex_type *	value,
		MEM_ROOT *	mem_root
	)		const

Get the lex string value for a given key.

Return true (assert in debug builds) if the operation fails, i.e., if the key does not exist or if the key is invalid.

Template Parameters

Lex_type

Type of LEX string.

Parameters

	key	Key to lookup the value for.
[out]	value	LEX_STRING or LEX_CSTRING value.
[in]	mem_root	MEM_ROOT to allocate string.

Returns

operation outcome, false if success, otherwise true.

get() [2/3]

virtual bool dd::Properties::get ( const String_type &  key, String_type *  value  ) const

pure virtual

Get the string value for a given key.

Return true (assert in debug builds) if the operation fails, i.e., if the key does not exist or if the key is invalid.

Parameters

	key	Key to lookup the value for.
[out]	value	String value.

Returns

operation outcome, false if success, otherwise true.

Implemented in dd::Properties_impl.

get() [3/3]

template<typename Value_type >

bool dd::Properties::get	(	const String_type &	key,
		Value_type *	value
	)		const

Get the string value for the key and convert it to the appropriate type.

Return true (assert in debug builds) if the operation fails, i.e., if the key does not exist or is invalid, or if the type conversion fails.

Template Parameters

Value_type

Type of the value to get.

Parameters

	key	Key to lookup.
[out]	value	Value of appropriate type.

Returns

operation outcome, false if success, otherwise true.

insert_values() [1/2]

virtual bool dd::Properties::insert_values ( const Properties &  properties )

pure virtual

Insert keys and values from a different property object.

Note

The valid keys in the target object are used to filter out invalid keys, which will be silently ignored. The set of valid keys in the source object is not copied.

Precondition

The 'this' object shall be empty.

Parameters

properties

Object which will have its properties copied to 'this' object.

Returns

operation outcome, false if success, otherwise true.

Implemented in dd::Properties_impl.

insert_values() [2/2]

virtual bool dd::Properties::insert_values ( const String_type &  raw_string )

pure virtual

Insert keys and values from a raw string.

Invalid keys will be silently ignored, using the set of valid keys in the target object as a filter. The source is a string, so it has no definition of valid keys.

Precondition

The 'this' object shall be empty.

Parameters

raw_string

String with key/value pairs which will be parsed and added to the 'this' object.

Returns

operation outcome, false if success, otherwise true.

Implemented in dd::Properties_impl.

operator=()

Properties & dd::Properties::operator= ( const Properties &  )

delete

parse_properties()

Properties * dd::Properties::parse_properties ( const String_type &  raw_properties )

static

Parse the submitted string for properties on the format "key=value;key=value;...".

Create new property object and add the properties to the map in the object.

Parameters

raw_properties

string containing list of key=value pairs

Returns

pointer to new Property_impl object

Return values

NULL	if an error occurred

raw_string()

virtual const String_type dd::Properties::raw_string ( ) const

pure virtual

Create a string containing all key=value pairs as a semicolon separated list.

Key and value are separated by '='. The '=' and ';' characters are escaped using '\' if part of key or value, hence, the escape character '\' must also be escaped.

Returns

a string listing all key=value pairs.

Implemented in dd::Properties_impl.

remove()

virtual bool dd::Properties::remove ( const String_type &  key )

pure virtual

Remove the key=value pair for the given key if it exists.

Otherwise, do nothing.

Parameters

key	key to lookup.

Returns

false if the given key existed, true otherwise.

Implemented in dd::Properties_impl.

set() [1/2]

virtual bool dd::Properties::set ( const String_type &  key, const String_type &  value  )

pure virtual

Add a new key=value pair where the value is a string.

If the key already exists, the associated value will be replaced by the new value argument.

Return true (assert in debug builds) if the operation fails, i.e., if the key is invalid.

Parameters

key	Key to map to a value.
value	String value to be associated with the key.

Returns

operation outcome, false if success, otherwise true.

Implemented in dd::Properties_impl.

set() [2/2]

template<typename Value_type >

bool dd::Properties::set ( const String_type &  key, Value_type  value  )

inline

Convert the value to a string and set it for the given key.

Return true (assert in debug builds) if the operation fails, i.e., if the key is invalid.

Template Parameters

Value_type

Type of the value to set.

Parameters

	key	Key to assign to.
[out]	value	Value of appropriate type.

Returns

operation outcome, false if success, otherwise true.

size()

virtual size_type dd::Properties::size ( ) const

pure virtual

Get the number of key=value pairs.

Note

Invalid keys that are present will also be reflected in the count.

Returns

number of key=value pairs

Implemented in dd::Properties_impl.

to_str()

template<class T >

String_type dd::Properties::to_str ( T  value )

static

Convert a value of an integral type (including bool) to a string.

Create an output stream and write the value.

Template Parameters

T	Value type.

Parameters

value

Actual value to convert.

Returns

string containing representation of the value.

valid_key()

virtual bool dd::Properties::valid_key ( const String_type &  key ) const

pure virtual

Check if the submitted key is valid.

Parameters

key	Key to be checked.

Return values

true	if the key is valid, otherwise false.

Implemented in dd::Properties_impl.

---

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

• sql/dd/properties.h
• sql/dd/impl/properties_impl.cc
• sql/dd/properties.cc