Encapsulates an hierarchical database containing name/value pairs. More...

#include <jem/util/Properties.h>

Public Types
typedef DictionaryEnumerator	Enumerator
	An enumerator type. More...

Public Member Functions
	Properties (const String &name="")
	Constructs an empty `Properties` object. More...

	Properties (const Ref< Dictionary > &dict, const String &name="")
	Constructs a `Properties` object given a dictionary and a name. More...

	Properties (const Properties &rhs)
	Constructs a shallow copy of a `Properties` object. More...

Properties &	operator= (const Properties &rhs)
	Makes a shallow copy of another `Properties` object. More...

Properties	clone () const
	Returns a deep copy of this properties set. More...

void	swap (Properties &rhs)
	Swaps the contents of two `Properties` objects. More...

Dictionary *	getContents () const
	Returns the dictionary containing the properties. More...

void	setContents (const Ref< Dictionary > &dict)
	Sets the dictionary encapsulated by this object. More...

String	getName () const
	Returns the name of this object. More...

Ref< Enumerator >	enumerate () const
	Returns an enumeration over all properties in this object. More...

void	parseFile (const String &fname, int options=0) const
	Reads a set of properties from a file. More...

void	parseFrom (Tokenizer &input, const String &source, int options=0) const
	Reads properties from a given tokenizer. More...

void	printTo (io::PrintWriter &out) const
	Prints the contents of this properties set. More...

void	set (const String &name, const Ref< Object > &value) const
	Inserts a property with type `Object`. More...

void	set (const String &name, bool value) const
	Inserts a boolean property. More...

void	set (const String &name, int value) const
	Inserts an integer property. More...

void	set (const String &name, double value) const
	Inserts a floating point property. More...

void	set (const String &name, const char *value) const
	Inserts a string property. More...

void	set (const String &name, const String &value) const
	Inserts a string property. More...

void	set (const String &name, const Array< bool > &values) const
	Inserts a boolean array property. More...

void	set (const String &name, const Array< int > &values) const
	Inserts an integer array property. More...

void	set (const String &name, const Array< double > &values) const
	Inserts a floating point array property. More...

void	set (const String &name, const Array< String > &values) const
	Inserts a string array property. More...

void	set (const String &name, const Properties &values) const
	Inserts a nested set of properties. More...

template<class T >
bool	find (Ref< T > &value, const String &name) const
	Searches for a property. More...

bool	find (bool &value, const String &name) const
	Searches for a boolean property. More...

bool	find (int &value, const String &name) const
	Searches for an integer property. More...

bool	find (double &value, const String &name) const
	Searches for a floating point property. More...

bool	find (String &value, const String &name) const
	Searches for a string property. More...

bool	find (Array< bool > &values, const String &name) const
	Searches for a boolean array property. More...

bool	find (Array< int > &values, const String &name) const
	Searches for an integer array property. More...

bool	find (Array< double > &values, const String &name) const
	Searches for a floating point array property. More...

bool	find (Array< String > &values, const String &name) const
	Searches for a string array property. More...

bool	find (Properties &values, const String &name) const
	Searches for a nested set of properties. More...

bool	find (int &value, const String &name, int lbound, int ubound) const
	Searches for an integer property and checks its range. More...

bool	find (double &value, const String &name, double lbound, double ubound) const
	Searches for a floating point property and checks its range. More...

bool	find (Array< int > &values, const String &name, int lbound, int ubound) const
	Searches for an integer array property and checks the range of each element. More...

bool	find (Array< double > &values, const String &name, double lbound, double ubound) const
	Searches for a floating point array property and checks the range of each element. More...

Ref< Object >	get (const String &name) const
	Returns a property as an object. More...

template<class T >
void	get (T &value, const String &name) const
	Reads the value of a property. More...

template<class T >
void	get (T &value, const String &name, T lbound, T ubound) const
	Reads the value of a property and checks its range. More...

template<class T >
void	get (Array< T > &values, const String &name, T lbound, T ubound) const
	Reads the value of an array property and checks its range. More...

Properties	makeProps (const String &name) const
	Creates and returns a nested set of properties. More...

Properties	findProps (const String &name) const
	Searches for a nested properties set. More...

Properties	getProps (const String &name) const
	Returns a nested properties set. More...

bool	contains (const String &name) const
	Checks for the existence of a property. More...

void	erase (const String &name) const
	Deletes a property. More...

void	clear () const
	Deletes all properties. More...

String	getContext () const
	Returns a context string. More...

String	getContext (const String &name) const
	Returns a context string. More...

void	propertyError (const String &name, const String &msg) const
	Throws a `PropertyException`. More...

Static Public Attributes
static const int	PARSE_STRICT
	Specifies that only known properties should be parsed. More...

static const int	PARSE_TO_UPPER
	Specifies that property names should be converted to upper case. More...

static const int	PARSE_INCLUDE
	Specifies that files may be included when parsing a properties file. More...

static const int	PARSE_STRINGS
	Specifies that strings should be expanded. More...

Related Functions
(Note that these are not member functions.)
void	swap (Properties &lhs, Properties &rhs)
	Swaps the contents of two properties sets. More...

io::Writer &	operator<< (io::Writer &out, const Properties &props)
	Prints the contents of a set of properties. More...

io::ObjectInput &	operator>> (io::ObjectInput &in, Properties &props)
	Properties de-serialization operator. More...

io::ObjectOutput &	operator<< (io::ObjectOutput &out, const Properties &props)
	Properties serialization operator. More...

Detailed Description

The Properties class implements an hierarchical database containing a set of name/value pairs called properties. It is typically used as a repository for configuration data.

The name of a property is represented by a String instance. The value of a property is a variable that has one of the following types: bool, int, double, String, Array<bool>, Array<int>, Array<double>, Array<String>, or Object. The value of a property can also be a Properties object so that you can build hierarchical sets of properties. A Properties object that is contained by another Properties object is called a nested Properties object.

A Properties object can be filled by calling the member functions parseFile() and parseFrom(). The former reads a set of properties from a file, while the latter reads a set of properties from any text input stream. The contents of a Properties object can be printed by calling the member function printTo() or by calling the print operator.

Individual properties can be inserted into a Properties object by calling one of the overloaded versions of the set() member function. They can be extracted from a Properties object by calling one of the overloaded versions of the find() or get() member functions. The difference between these two functions is that the former does nothing if a property does not exist, while the latter will throw an exception if a property does not exist. Optionally, these functions can check if the value of a property lies within a valid range. The following code fragment illustrates how to set and get properties. The last statement will throw an exception because the property named "x" does not exist.

Properties  props;
double      x;
int         i;
props.set  ( "i", 1 );
props.get  ( i, "i" );
props.get  ( i, "i", 0, 10 );  // With bounds checking.
props.find ( x, "x" );         // Ok; no effect.
props.get  ( x, "x" );         // Error.

A property can be inserted into or extracted from a nested Properties object by calling the set(), find() and get() functions with a compound property name. Such a name consists of a series of simple names concatenated by '.' characters. Here is an example:

Properties props;
double     length;
props.set ( "jones.age", 34 );
props.get ( length, "brown.length" );

The first statement inserts the integer property "age" into the nested Properties object named "jones". If this object does not exist it is created on the fly. The second statement reads the double property "length" from the nested Properties object named "brown". An exception is thrown if this object does not exist.

A Properties object keeps track of its own name so that it can generate meaningful error messages. The name of a Properties object is empty by default. It is assigned a value when a Properties object is read from another Properties object.

A Properties object stores its properties as String/Object pairs in a Dictionary. In fact, a Properties object is essentially a convenient wrapper around a reference to a Dictionary object. The added value of the Properties class is that it automatically converts property values into Object instances and back again. An exception is thrown whenever a conversion fails.

Examples:: Database.cpp, DataParser.cpp, and Properties.cpp.

Member Typedef Documentation

typedef DictionaryEnumerator jem::util::Properties::Enumerator

Objects of type Enumerator can be used to iterate over all properties in a Properties object. The Enumerator type is just a convenient alias for the class DictionaryEnumerator.

Constructor & Destructor Documentation

jem::util::Properties::Properties ( const String & name = "" )

explicit

Constructs a Properties object with name name that encapsulates a newly created, empty Dictionary object. The runtime type of the Dictionary object is not specified.

Parameters

name	- the name of the newly constructed `Properties` object.

Postcondition: getName() == name

jem::util::Properties::Properties	(	const Ref< Dictionary > &	dict,
		const String &	name = `""`
	)

explicit

Constructs a Properties object that uses the Dictionary dict to store its properties. The string name specifies the name of the Properties object – as returned by getName().

Parameters

dict	- the `Dictionary` in which the properties are to be stored.
name	- the name of the newly constructed `Properties` object.

Precondition: dict != NIL

Postcondition: getContents() == dict && getName() == name

jem::util::Properties::Properties ( const Properties & rhs )

Constructs a Properties object that points to the same Dictionary as the Properties object rhs. The name of this Properties object equals the name of the rhs Properties object.

Parameters

rhs	- a `Properties` object.

Postcondition: this->getContents() == rhs.getContents()

Member Function Documentation

Properties& jem::util::Properties::operator= ( const Properties & rhs )

Makes a shallow copy of the Properties object rhs. After calling the assignment operator, both objects point to the same Dictionary object and have the same name.

Parameters

rhs	- the `Properties` object to be copied.

Postcondition: this->getContents() == rhs.getContents() && this->getName() == rhs.getName()

Properties jem::util::Properties::clone ( ) const

Returns a deep copy of this properties set. This function essentially executes:

return Properties (
  checkedCast<Dictionary> ( this->getContents() ),
  this->getName ()
);

Returns: A deep copy of this properties set.

void jem::util::Properties::swap ( Properties & rhs )

Swaps the contents of this object with the rhs object. It has the same effect as:

Properties tmp ( *this );
*this = rhs;
rhs   = tmp;

Parameters

rhs	- a `Properties` object.

Dictionary* jem::util::Properties::getContents ( ) const

Returns a reference to the dictionary containing the properties stored in this Properties object.

void jem::util::Properties::setContents ( const Ref< Dictionary > & dict )

Sets the Dictionary reference owned by this object to dict.

Parameters

dict	- a reference to the dictionary that is to be wrapped by this `Properties` object.

Precondition: dict != NIL

Postcondition: this->getContents() == dict

String jem::util::Properties::getName ( ) const

Returns the name of this Properties object. By default, the name of a Properties object is an empty string. It is set whenever a Properties object is extracted from another Properties object.

Ref<Enumerator> jem::util::Properties::enumerate ( ) const

Returns an enumerator over all properties in this Properties object. This function is equivalent with:

return this->getContents()->enumerate();

void jem::util::Properties::parseFile	(	const String &	fname,
		int	options = `0`
	)		const

Reads a set of properties from the file named fname and adds those properties to the current set of properties stored in this Properties object. The format of the properties file is described by the page Properties file format. The input argument options controls how the properties are parsed and added to the current set of properties. See the documentation of the function parseFrom() for the details.

Note that this function essentially creates a Tokenizer object and then calls the function parseFrom().

Parameters

fname	- the name of the file from which the properties are to be read.
options	- an integer flag specifying how the properties are to be parsed.

Exceptions

ParseException	- if a parse error occurs.
IllegalInputException	- if the properties file contains semantic errors (like references to non-existing properties).
PropertyException	- if a property is not present in the current set or if the type of a property is incorrect.
io::FileNotFoundException	- if the specified properties file does not exist.
io::IOException	- if an I/O error occurs.

Examples:: Properties.cpp.

void jem::util::Properties::parseFrom	(	Tokenizer &	input,
		const String &	source,
		int	options = `0`
	)		const

Reads properties from the tokenizer input and inserts them into this Properties object. The format of the input stream read by the tokenizer is described by the page Properties file format. This function returns when the entire input stream has been parsed, or when an illegal token is encountered.

The second input parameter source specifies the name of the input stream, and is used in error messages. It is typically the name of a file associated with the input stream.

The input argument options controls how the properties are read from the tokenizer. It should be a bitwise OR of the constants PARSE_TO_UPPER, PARSE_STRICT, PARSE_INCLUDE and PARSE_STRINGS. The first constant indicates that all names of the read properties are to be converted to uppercase characters.

The constant PARSE_STRICT indicates that the current set of properties determines which properties may be read from the tokenizer. That is, each property name read from the tokenizer is looked up in the current set of properties. If a property with that name exists, its type is compared with the type of the property value read from the tokenizer. If both types are equal, the current property is replaced by the one read from the tokenizer. An exception is thrown if the two types are not equal or if the property is not present in the current set of properties. Note that a property read from the tokenizer may have any type if the corresponding property in the current set has the value NIL. In other words, the value NIL functions as a wild-card that matches any type.

If the PARSE_STRICT constant is not set in the argument options, then all properties read from the tokenizer are inserted into the current set of properties. A property read from the tokenizer replaces an existing property if it has the same name.

The constant PARSE_INCLUDE indicates that files may be included into the input stream by means of the include keyword (see the page Properties file format for the details). If the PARSE_INCLUDE bit has not been set in the parameter options, then the word include is handled as a normal property name.

The constant PARSE_STRINGS indicates that all strings containing substitution directives of the form should be expanded. If the PARSE_STRINGS bit has not been set in the options parameter, then all string values are stored directly without expanding them.

Parameters

input	- the `Tokenizer` from which a set of properties is to be read.
source	- the name of the input stream.
options	- an integer flag that specifies how the properties are to be parsed and added to the current set of properties.

Exceptions

ParseException	- if a parse error occurs.
IllegalInputException	- if the properties file contains semantic errors (like references to non-existing properties).
PropertyException	- if a property is not present in the current set or if the type of a property is incorrect.
io::IOException	- if an I/O error occurs.

void jem::util::Properties::printTo ( io::PrintWriter & out ) const

Prints the contents of this Properties object to the formatted output stream out. The output has the same format as the input read by the member parseFrom(). Nested Properties objects are printed recursively.

Exceptions

io::IOException - if an I/O error occurs,

void jem::util::Properties::set	(	const String &	name,
		const Ref< Object > &	value
	)		const

Inserts the property with name name and value value into this Properties object. If a property with the same name already exists, its value is replaced by the object value. If name is a compound name – containing one or more dots – the property is inserted into a nested Properties object. Non-existent nested Property object are created on the fly, possibly replacing existing properties that are not of type Properties. Here is an example:

this->set ( "car", "Mercedes" );

this->set ( "car.brand", "Mercedes" );

The first statement inserts a property named "car" with the value "Mercedes". The second statement replaces this property with a nested Properties object, and then inserts the property named "brand" into the nested Properties object.

This function calls the function Dictionary::insert() to insert the property into the dictionary owned by this Properties object or the dictionary of a nested Properties object.

Parameters

name	- the name of the property to be inserted.
value	- the value of the property to be inserted.

void jem::util::Properties::set	(	const String &	name,
		bool	value
	)		const

Inserts a boolean property. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		int	value
	)		const

Inserts an integer property. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		double	value
	)		const

Inserts a property with type double. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const char *	value
	)		const

Inserts a property with type String. This function exists only to avoid conversion problems (pointers are converted to booleans). It is equivalent with:

this->set ( name, String( value ) );

See also: set( const String&, const String& )

void jem::util::Properties::set	(	const String &	name,
		const String &	value
	)		const

Inserts a string property. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const Array< bool > &	values
	)		const

Inserts a property of which the value is a boolean array. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const Array< int > &	values
	)		const

Inserts a property of which the value is an integer array. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const Array< double > &	values
	)		const

Inserts a property with type Array<double>. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const Array< String > &	values
	)		const

Inserts a property of which the value is an array of strings. This function has the same effect as

this->set ( name, toObject( value ) );

See also: set( const String&, const Ref<Object>& )

void jem::util::Properties::set	(	const String &	name,
		const Properties &	values
	)		const

Inserts a nested set of properties. This function has the same effect as

this->set ( name, values.getContents() );

See also: set( const String&, const Ref<Object>& )

template<class T >

bool jem::util::Properties::find	(	Ref< T > &	value,
		const String &	name
	)		const

Searches for a property with type T and name name. If the property exists, its address is stored in the output parameter value and true is returned. Otherwise, value is not modified and false is returned. If the name of the property is a compound name – containing one or more dots – then the property is looked up in a nested set of properties.

This function calls the member function Dictionary::find() to search for the property in the dictionary encapsulated by this Properties object or by a nested Properties object.

Parameters

value	- a reference in which the address of the requested property is stored.
name	- the name of the property to be found.

Returns: true is the property has been found, and false otherwise.

Exceptions

PropertyException - if the property exists but is not of type T.

Examples:: Properties.cpp.

bool jem::util::Properties::find	(	bool &	value,
		const String &	name
	)		const

Searches for a boolean property with name name. If the property exists, its value is stored in the argument value, and true is returned. Otherwise, value is not modified and false is returned.

Exceptions

PropertyException - if the property exists but is not of type bool.

See also: find ( Ref<T>&, const String& )

bool jem::util::Properties::find	(	int &	value,
		const String &	name
	)		const

Searches for an integer property.

Exceptions

PropertyException - if the property exists but is not of type int.

See also: find ( bool&, const String& )

bool jem::util::Properties::find	(	double &	value,
		const String &	name
	)		const

Searches for a property with type double.

Exceptions

PropertyException - if the property exists but is not of type double.

See also: find ( bool&, const String& )

bool jem::util::Properties::find	(	String &	value,
		const String &	name
	)		const

Searches for a string property.

Exceptions

PropertyException - if the property exists but is not of type String.

See also: find ( bool&, const String& )

bool jem::util::Properties::find	(	Array< bool > &	values,
		const String &	name
	)		const

Searches for a property that has type Array<bool> and name name. If the property exists, then a shallow copy of its value is stored in the argument values and true is returned. Otherwise, values is not modified and false is returned.

This function first searches for a generic object property with name name by calling

this->find ( obj, name );

where obj is an object reference of type Ref<Object>. If the call returns false, this function returns false too. Else, if obj equals NIL, the argument values is set to an empty array by executing the statement

values.ref ( Array<bool>() );

Else, if obj points to an object that can be converted to a boolean array, the argument values is set as follows:

values.ref ( toValue< Array<bool> >( obj ) );

Else, if obj points to an object that can be converted to a boolean value, then values is set to a new array of length one containing the value of the property. Else, an exception is thrown.

Note that in the second case above the argument values points to the same data as the property object stored in this Properties object (or a nested Properties object). This means that if the contents of the array values are later modified, the contents of the original property object will be modified too.

Here is an example involving boolean array properties.

Array<bool>  values ( 3 );  
Properties   props;
values = false;
props.set  ( "a", values );
props.set  ( "b", true   );
props.set  ( "c", 1.0    );
props.find ( values, "a" );  // OK
props.find ( values, "b" );  // OK: conversion from bool
props.find ( values, "c" );  // Error: invalid property value

Parameters

values	- a boolean array that will point to the data of the property if it has been found.
name	- the name of the property to be found.

Returns: true if the property has been found, and false otherwise.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<bool>.

See also: find ( Ref<Object>&, const String& )

bool jem::util::Properties::find	(	Array< int > &	values,
		const String &	name
	)		const

Searches for a property that has type Array<int>.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<int>.

See also: find ( Array<bool>&, const String& )

bool jem::util::Properties::find	(	Array< double > &	values,
		const String &	name
	)		const

Searches for a property that has type Array<double>.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<double>.

See also: find ( Array<bool>&, const String& )

bool jem::util::Properties::find	(	Array< String > &	values,
		const String &	name
	)		const

Searches for a property that has type Array<String>.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<String>.

See also: find ( Array<String>&, const String& )

bool jem::util::Properties::find	(	Properties &	values,
		const String &	name
	)		const

Searches for a nested set of properties with name name. If the nested set of properties exists, a shallow copy is assigned to the argument values and true is returned. Otherwise, values is not modified and false is returned.

This function first searches for a generic object property with name name by calling

this->find ( obj, name );

where obj as an object reference of type Ref<Object>. If the call returns false, this function returns false too. Else, if the object pointed to by obj can be converted to an object of type Dictionary, then the argument values is set as follows:

values = Properties ( dynamicCast<Dictionary>( obj ) );

Else an exception is thrown to indicate the type of the property named name is incorrect.

If this function returns true, then the name of the Properties object values will be equal to the concatenation of the name of this Properties object and the string name. To be precise, the name of the Properties object values will be equal to

this->getName() + "." + name

provided that the name of this Properties object is not empty. If it is, then the name of the object values will be equal to the input argument name.

Parameters

values	- a reference `Properties` object that will point to the nested properties set if that set has been found.
name	- the name of the nested set of properties to be found.

Returns: true if the nested set of properties has been found, and false otherwise.

Exceptions

PropertyException - if the value of the property named name can not be converted to a Dictionary.

See also: find ( Ref<Object>&, const String& )

bool jem::util::Properties::find	(	int &	value,
		const String &	name,
		int	lbound,
		int	ubound
	)		const

Searches for an integer property and checks whether the value of that property is larger than or equal to lbound and smaller than or equal to ubound. This function is equivalent with:

int tmp;
if ( ! this->find( tmp, name ) ) {
  return false;
}
if ( tmp < lbound || tmp > ubound ) {
  throw PropertyException;
}
value = tmp;
return true;

Parameters

value	- a reference to an integer that will be set to the value of the property if it has been found and its range is valid.
name	- the name of the property to be found.
lbound	- the lower bound (inclusive) of the valid range.
ubound	- the upper bound (inclusive) of the valid range.

Returns: true if the property has been found and is valid, and false otherwise.

Exceptions

PropertyException - if the property named name exists but is not of type int or if its value is out of range.

See also: find ( int&, const String& )

bool jem::util::Properties::find	(	double &	value,
		const String &	name,
		double	lbound,
		double	ubound
	)		const

Searches for a floating point property and checks whether the value of that property is larger than or equal to lbound and smaller than or equal to ubound.

Exceptions

PropertyException - if the property named name exists but is not of type double or if its value is out of range.

See also: find ( int&, const String&, int, int )

bool jem::util::Properties::find	(	Array< int > &	values,
		const String &	name,
		int	lbound,
		int	ubound
	)		const

Searches for a property with type Array<int> and checks whether all array elements are larger than or equal to lbound and smaller than or equal to ubound. This function is equivalent with:

Array<int> tmp;
if ( ! this->find( tmp, name ) ) {
  return false;
}
if ( testany( tmp < lbound || tmp > ubound ) ) {
  throw PropertyException;
}
value.ref( tmp );
return true;

Parameters

values	- a reference to an integer array that will be set to the value of the property if it has been found and its range is valid.
name	- the name of the property to be found.
lbound	- the lower bound (inclusive) of the valid range.
ubound	- the upper bound (inclusive) of the valid range.

Returns: true if the property has been found and is valid, and false otherwise.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<int> or if one of the array elements is out of range.

See also: find ( Array<int>&, const String& )

bool jem::util::Properties::find	(	Array< double > &	values,
		const String &	name,
		double	lbound,
		double	ubound
	)		const

Searches for a property with type Array<double> and checks whether all array elements are larger than or equal to lbound and smaller than or equal to ubound.

Exceptions

PropertyException - if the property named name exists but can not be converted to an array of type Array<double> or if one of the array elements is out of range.

See also: find ( Array<int>&, const String&, int, int )

Ref<Object> jem::util::Properties::get ( const String & name ) const

Returns the property named name as an Object instance. This function is equivalent with:

Ref<Object> obj;
if ( ! this->find ( obj, name ) ) {
  throw PropertyException;
}
return obj;

Parameters

name	- the name of the property to be found.

Exceptions

PropertyException - if the property can not be found.

Examples:: Properties.cpp.

template<class T >

void jem::util::Properties::get	(	T &	value,
		const String &	name
	)		const

Stores the value of the property named name into the output parameter value. This function is equivalent with:

if ( ! this->find ( value, name ) ) {
  throw PropertyException;
}

Parameters

value	- a reference to a variable of type `T` into which the value of the property is to be stored.
name	- the name of the property to be found.

Exceptions

PropertyException - if the property can not be found or if the property is not of type T.

template<class T >

void jem::util::Properties::get	(	T &	value,
		const String &	name,
		T	lbound,
		T	ubound
	)		const

Stores the value of the property named name into the output parameter value and checks whether the value is larger than or equal to lbound and smaller than or equal to ubound. This function is equivalent with:

if ( this->find ( value, name, lbound, ubound ) ) {
  throw PropertyException;
}

Parameters

value	- a reference to a variable of type `T` that will be set to the value of the property (if it has been found and its range is valid).
name	- the name of the property to be found.
lbound	- the lower bound (inclusive) of the valid range.
ubound	- the upper bound (inclusive) of the valid range.

Exceptions

PropertyException - if the property can not be found; or if the property is not of type T; or if the value property is out of range.

template<class T >

void jem::util::Properties::get	(	Array< T > &	values,
		const String &	name,
		T	lbound,
		T	ubound
	)		const

Stores a shallow copy of the array property named name into the output parameter value and checks whether the array elements are larger than or equal to lbound and smaller than or equal to ubound. This function is equivalent with:

if ( this->find ( value, name, lbound, ubound ) ) {
  throw PropertyException;
}

Parameters

values	- a reference to an array of type `Array<T>` that will be set to the value of the property (if it has been found and its range is valid).
name	- the name of the property to be found.
lbound	- the lower bound (inclusive) of the valid range.
ubound	- the upper bound (inclusive) of the valid range.

Exceptions

PropertyException - if the property can not be found; or if the property is not of type Array<T>; or if one of the array elements is out of range.

Properties jem::util::Properties::makeProps ( const String & name ) const

Searches for a nested set of properties named name. If that nested set does not exist, a new, nested properties set is created. If there exists a property named name that is not a properties object, that property will be replaced by a new, nested properties set. This function returns the nested properties set that has been found or that has been created.

Parameters

name	- the name of the nested properties set to be found or created.

Returns: A nested properties set named name.

Properties jem::util::Properties::findProps ( const String & name ) const

Searches for and returns the nested set of properties named name. An empty properties object is returned if this properties set does not contain a property named name. This function is equivalent with:

Properties tmp;
this->find ( tmp, name );
return tmp;

Parameters

name	- the name of the nested properties set to be found.

Returns: The nested properties set named name, or an empty properties set if there is no property named name.

Exceptions

PropertyException - if the property with the specified name is not of type Properties.

Properties jem::util::Properties::getProps ( const String & name ) const

Returns the nested properties set named name. An exception is thrown if the nested properties set does not exist. This function has the same effect as:

Properties tmp;
this->get ( tmp, name );
return tmp;

Parameters

name	- the name of the nested properties set to be found.

Returns: The nested properties set named name.

Exceptions

PropertyException - if the nested properties set does not exist; or if the property with the specified name is not a nested properties set.

bool jem::util::Properties::contains ( const String & name ) const

Checks whether the property named name is part of this set of properties. This function is equivalent with:

Ref<Object> dummy;
return this->find ( dummy, name );

Parameters

name	- the name of a property.

void jem::util::Properties::erase ( const String & name ) const

Deletes the property named name from this set of properties. If name is a compound name (containing one or more dots), then the property is deleted from a nested set of properties. This function has no effect if the property does not exist.

Parameters

name	- the name of a property.

Postcondition: this->contains( name ) == false

void jem::util::Properties::clear ( ) const

Deletes all properties from this Properties object. This function has the same effect as

this->getContents()->clear();

String jem::util::Properties::getContext ( ) const

Returns a context string that can be used for displaying errors and other types of messages that are related to this set of properties. The returned string is typically passed as a context string to the constructor of an exception class.

Returns: A context string.

See also: getContext( const String& )

String jem::util::Properties::getContext ( const String & name ) const

Returns a context string that can be used for displaying errors related to a property named name in this set of properties. The returned string is typically passed as a context string to the constructor of an exception class.

Parameters

name	- the name of a property.

Returns: A context string.

See also: propertyError()

void jem::util::Properties::propertyError	(	const String &	name,
		const String &	msg
	)		const

Throws a PropertyException indicating that the property named name is invalid. The input string msg should explain why the property is invalid.

Exceptions

PropertyException

Friends And Related Function Documentation

void swap	(	Properties &	lhs,
		Properties &	rhs
	)

lhs.swap ( rhs );

Parameters

lhs	- a `Properties` object.
rhs	- another `Properties` object.

io::Writer & operator<<	(	io::Writer &	out,
		const Properties &	props
	)

Prints the contents of the properties set props to the text output stream out. This function essentially wraps the output stream into a jem::io::PrintWriter and then calls the member function Properties::printTo().

Exceptions

io::IOException - if an I/O error occurs,

io::ObjectInput & operator>>	(	io::ObjectInput &	in,
		Properties &	props
	)

Parameters

in	- the object input stream from which the `Properties` object is to be read.
props	- the `Properties` object to be read.

Returns: in

Exceptions

io::IOException	- if an I/O error occurs.
io::SerializationException	- if the object input stream is corrupt.

io::ObjectOutput & operator<<	(	io::ObjectOutput &	out,
		const Properties &	props
	)

Parameters

out	- the object output stream to which the `Properties` object is to be written.
props	- the `Properties` object to be written.

Returns: out

Exceptions

io::IOException - if an I/O error occurs.

Member Data Documentation

const int jem::util::Properties::PARSE_STRICT

static

A constant specifying that only known properties should be parsed.

const int jem::util::Properties::PARSE_TO_UPPER

static

A constant specifying that all property names should be converted to upper case.

const int jem::util::Properties::PARSE_INCLUDE

static

A constant specifying that files may be included (by means of the include keyword) when parsing a properties file.

const int jem::util::Properties::PARSE_STRINGS

static

A constant specifying that string values containing substitution directives should be expanded.

Public Types

Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation