PropertyMap Module

Module Contents

Todo

set_property throws warnings when parsed by Breathe so documentation isn’t generated for this function. Breathe doesn’t easily support overloaded functions utilizing doxygenfunction::, need to figure out how to handle the manually declared overloaded functions.

typedef std::map<std::string, PropertyValueT> tracktable::PropertyMap

Name -> property map.

We will use this as our container for named properties.

Note

A std::unordered_map (hashtable) would have slightly faster asymptotic performance but we will probably never have enough entries in a single property map for it to even be noticeable, let alone significant.

bool tracktable::has_property(PropertyMap const &properties, string_type const &name)

Check whether a property is present.

Check to see whether a given property is present.

Check the map to see if it contains the given property. This function will not modify the map in any way.

Parameters:

• properties – [in] Property map to interrogate

• name – [in] Name of property to look up

• properties – [in] Property map

• name – [in] Property to search for in the map

Returns:

True/false (found or not)

PropertyValueT tracktable::property(PropertyMap const &properties, string_type const &name, bool *is_present)

Retrieve a property regardless of its type.

Retrieve a property from a map whatever its type.

This accessor will let you retrieve the value of a named property regardless of its underlying data type. The catch is that we don’t know whether or not the property is there to begin with. If it isn’t there then we can’t return anything sensible.

We deal with this by letting you pass in an optional pointer to a boolean. We will set its value to true or false depending on whether or not we found the property you wanted. If it is true, the return value is guaranteed to be whatever is in the map. If it is false, the return value will be an empty variant.

This function will give you back the named property as a PropertyValueT (a Boost variant) if it is present in the map. If not, you’ll get back an uninitialized PropertyValueT and the bool pointed at by is_present will be set to ‘false’.

Parameters:

• properties – [in] Property map to interrogate

• name – [in] Name of property to find

• is_present – Pointer to boolean

• properties – [in] Property map

• name – [in] Property to search for in the map

• is_present – [out] Flag indicating if the property is present

Returns:

Value of desired property (if present)

Returns:

On success, returns the requested property and sets *is_present to true. On failure, returns an uninitialized property and sets *is_present to false.

string_type tracktable::string_property(PropertyMap const &properties, string_type const &name, bool *is_present)

Retrieve a string property.

Retrieve a string-valued property from the map.

This accessor will let you retrieve the value of a string property. The catch is that we don’t know whether or not the property is there to begin with. If it isn’t there then we can’t return anything sensible.

We deal with this by letting you pass in an optional pointer to a boolean. We will set its value to true or false depending on whether or not we found the property you wanted. If it is true, the return value is guaranteed to be whatever is in the map. If it is false, the return value will be uninitialized.

This function will give you back the named property as a string_type if it is present and that is its proper type. It will not attempt to cast other types to string_type.

Note

For the purposes of this function, a property that is present but that has the wrong type is the same as a property that is not present in the map.

Parameters:

• properties – [in] Property map to interrogate

• name – [in] Name of property to find

• is_present – Pointer to boolean

• properties – [in] Property map

• name – [in] Property to search for in the map

• is_present – [out] Flag indicating if the property is present

Returns:

Value of desired property (if present)

Returns:

On success, returns the requested property as a string_type and sets *is_present to true. On failure, returns an uninitialized string_type and sets *is_present to false.

double tracktable::real_property(PropertyMap const &properties, string_type const &name, bool *is_present)

Retrieve a numeric property.

Retrieve a real-valued property from the map.

This accessor will let you retrieve the value of a numeric property. The catch is that we don’t know whether or not the property is there to begin with. If it isn’t there then we can’t return anything sensible.

We deal with this by letting you pass in an optional pointer to a boolean. We will set its value to true or false depending on whether or not we found the property you wanted. If it is true, the return value is guaranteed to be whatever is in the map. If it is false, the return value will be uninitialized.

This function will give you back the named property as a double-precision floating point number if it is present and that is its proper type. It will not attempt to cast other types to double.

Note

For the purposes of this function, a property that is present but that has the wrong type is the same as a property that is not present in the map.

Parameters:

• properties – [in] Property map to interrogate

• name – [in] Name of property to find

• is_present – Pointer to boolean

• properties – [in] Property map

• name – [in] Property to search for in the map

• is_present – [out] Flag indicating if the property is present

Returns:

Value of desired property (if present)

Returns:

On success, returns the requested property as a double and sets *is_present to true. On failure, returns 0 and sets *is_present to false.

Timestamp tracktable::timestamp_property(PropertyMap const &properties, string_type const &name, bool *is_present)

Retrieve a timestamp property.

Retrieve a timestamp-valued property from the map.

This accessor will let you retrieve the value of a timestamp property. The catch is that we don’t know whether or not the property is there to begin with. If it isn’t there then we can’t return anything sensible.

We deal with this by letting you pass in an optional pointer to a boolean. We will set its value to true or false depending on whether or not we found the property you wanted. If it is true, the return value is guaranteed to be whatever is in the map. If it is false, the return value will be uninitialized.

This function will give you back the named property as a Timestamp if it is present and that is its proper type. It will not attempt to cast other types to Timestamp.

Note

For the purposes of this function, a property that is present but that has the wrong type is the same as a property that is not present in the map.

Parameters:

• properties – [in] Property map to interrogate

• name – [in] Name of property to find

• is_present – Pointer to boolean

• properties – [in] Property map

• name – [in] Property to search for in the map

• is_present – [out] Flag indicating if the property is present

Returns:

Value of desired property (if present)

Returns:

On success, returns the requested property as a Timestamp and sets *is_present to true. On failure, returns an uninitialized timestamp and sets *is_present to false.

PropertyValueT tracktable::property_with_default(PropertyMap const &properties, string_type const &name, PropertyValueT const &default_value)

Retrieve a property or some default value.

Retrieve a property value or a default if it’s not there.

This method of retrieving a named property will never fail or throw an exception. You will either get back the value of the property you requested as your desired type or else you will get back your default value.

Note

This function works with variants instead of trying to cast down to a more specific type. As such, it does not care what the underlying type is for the requested value, only whether or not it’s there.

Parameters:

• properties – [in] Property map for lookup

• name – [in] Name of property to retrieve

• default_value – [in] Value to return if property is not present

double tracktable::real_property_with_default(PropertyMap const &properties, string_type const &name, double default_value)

Retrieve a numeric property or some default value.

This method of retrieving a named property will never fail or throw an exception. You will either get back the value of the property you requested as your desired type or else you will get back your default value.

Note

A property that is present but not numeric is treated as if the property were not present at all.

Parameters:

• properties – [in] Property map for lookup

• name – [in] Name of property to retrieve

• default_value – [in] Value to return if property is not present

string_type tracktable::string_property_with_default(PropertyMap const &properties, string_type const &name, string_type const &default_value)

Retrieve a string property or some default value.

This method of retrieving a named property will never fail or throw an exception. You will either get back the value of the property you requested as your desired type or else you will get back your default value.

Note

A property that is present but not numeric is treated as if the property were not present at all.

Parameters:

• properties – [in] Property map for lookup

• name – [in] Name of property to retrieve

• default_value – [in] Value to return if property is not present

Timestamp tracktable::timestamp_property_with_default(PropertyMap const &properties, string_type const &name, Timestamp const &default_value)

Retrieve a timestamp property or some default value.

This method of retrieving a named property will never fail or throw an exception. You will either get back the value of the property you requested as your desired type or else you will get back your default value.

Note

A property that is present but not numeric is treated as if the property were not present at all.

Parameters:

• properties – [in] Property map for lookup

• name – [in] Name of property to retrieve

• default_value – [in] Value to return if property is not present

string_type tracktable::property_map_to_string(tracktable::PropertyMap const &properties)

Render a property map’s contents as a string.

This function constructs a human-readable representation of a named property map.

Parameters:

properties – [in] Property map to write out

Returns:

Contents of property map as a string_type