Detailed Description
Encapsulates the results of an engine's processing.
The class is constructed using an instance of a C fiftyoneDegreesResultsBase structure which is then referenced to return associated values and metrics. Any memory used by the results is freed by the extending class.
Values contained in a results instance can be returned as a string, or as a type specified by the method used to fetch the value. For example, the getValueAsBool(int) method returns a value as a bool instead of a string representation.
The key used to get the value for a property can be either the name of the property, or its required property index, which is the index of the property in the names the engine was created with. A reload does not change it, and a property the data file lacks reads as a property the data set does not have. An engine that named no properties has no required property indexes, so its values are read by name.
A results instance is used by one thread at a time, because reading a value writes into the results. An engine created naming its properties walks every graph the results need as it processes the evidence, and otherwise the first read of a component's property walks the component's graph. Different results instances can be used on different threads at once, and the engine that created them can be shared, when EngineBase::getIsThreadSafe is true.
Results instances should only be created by a Engine.
Usage Example
Inheritance diagram for FiftyoneDegrees::Common::ResultsBase:
Collaboration diagram for FiftyoneDegrees::Common::ResultsBase:
Public Member Functions | |
Constructors and Destructors | |
| ResultsBase (fiftyoneDegreesResultsBase *results, shared_ptr< fiftyoneDegreesResourceManager > manager) | |
| Create a new instance of Results from the results structure provided. | |
| virtual | ~ResultsBase () |
| Free any memory associated with the results and release any resource handles. | |
Available Properties | |
| int | getAvailableProperties () const |
| Get the number of required property indexes, which is the number of names the engine was created with, including any the data file lacks. | |
| bool | containsProperty (const string &propertyName) const |
| Get whether or not this results instance contains a value for the requested property. | |
| vector< string > | getProperties () const |
| Get the names of the properties the data set has, in ascending order. | |
| string | getPropertyName (int requiredPropertyIndex) const |
| Get the name of the property at the required property index, or an empty string if there is no property at the index. | |
Value Getters | |
| Value< vector< string > > | getValues (const char *propertyName) |
| Get a vector with all values associated with the required property name. | |
| Value< vector< string > > | getValues (const string &propertyName) |
| Get a vector with all values associated with the required property name. | |
| Value< vector< string > > | getValues (const string *propertyName) |
| Get a vector with all values associated with the required property name. | |
| Value< vector< string > > | getValues (int requiredPropertyIndex) |
| Get a vector with all values associated with the required property index. | |
| Value< string > | getValueAsString (const char *propertyName) |
| Get a string representation of the value associated with the required property name. | |
| Value< string > | getValueAsString (const string &propertyName) |
| Get a string representation of the value associated with the required property name. | |
| Value< string > | getValueAsString (const string *propertyName) |
| Get a string representation of the value associated with the required property name. | |
| virtual Value< string > | getValueAsString (int requiredPropertyIndex) |
| Get a string representation of the value associated with the required property index. | |
| Value< bool > | getValueAsBool (const char *propertyName) |
| Get a boolean representation of the value associated with the required property name. | |
| Value< bool > | getValueAsBool (const string &propertyName) |
| Get a boolean representation of the value associated with the required property name. | |
| Value< bool > | getValueAsBool (const string *propertyName) |
| Get a boolean representation of the value associated with the required property name. | |
| virtual Value< bool > | getValueAsBool (int requiredPropertyIndex) |
| Get a boolean representation of the value associated with the required property index. | |
| Value< int > | getValueAsInteger (const char *propertyName) |
| Get an integer representation of the value associated with the required property name. | |
| Value< int > | getValueAsInteger (const string &propertyName) |
| Get an integer representation of the value associated with the required property name. | |
| Value< int > | getValueAsInteger (const string *propertyName) |
| Get an integer representation of the value associated with the required property name. | |
| virtual Value< int > | getValueAsInteger (int requiredPropertyIndex) |
| Get an integer representation of the value associated with the required property index. | |
| Value< double > | getValueAsDouble (const char *propertyName) |
| Get a double representation of the value associated with the required property name. | |
| Value< double > | getValueAsDouble (const string &propertyName) |
| Get a double representation of the value associated with the required property name. | |
| Value< double > | getValueAsDouble (const string *propertyName) |
| Get a double representation of the value associated with the required property name. | |
| virtual Value< double > | getValueAsDouble (int requiredPropertyIndex) |
| Get a double representation of the value associated with the required property index. | |
| Value< bool > | getValueAsStrictBool (const char *propertyName) |
| Get the value as a boolean only if its text is "True" or "False". | |
| Value< bool > | getValueAsStrictBool (const string &propertyName) |
| Get the value as a boolean only if its text is "True" or "False". | |
| Value< bool > | getValueAsStrictBool (int requiredPropertyIndex) |
| Get the value as a boolean only if its text is "True" or "False". | |
| Value< int > | getValueAsStrictInteger (const char *propertyName) |
| Get the value as an integer only if all of its text is a whole number an int can hold. | |
| Value< int > | getValueAsStrictInteger (const string &propertyName) |
| Get the value as an integer only if all of its text is a whole number an int can hold. | |
| Value< int > | getValueAsStrictInteger (int requiredPropertyIndex) |
| Get the value as an integer only if all of its text is a whole number an int can hold. | |
| Value< double > | getValueAsStrictDouble (const char *propertyName) |
| Get the value as a double only if all of its text is a finite number. | |
| Value< double > | getValueAsStrictDouble (const string &propertyName) |
| Get the value as a double only if all of its text is a finite number. | |
| Value< double > | getValueAsStrictDouble (int requiredPropertyIndex) |
| Get the value as a double only if all of its text is a finite number. | |
Protected Member Functions | |
| int | getRequiredPropertyIndex (const char *propertyName) |
| Get the required property index of the property name provided. | |
| int | allowedRequiredPropertyIndex (int requiredPropertyIndex) const |
| Get the index a read by required property index uses, which is the index given when the engine named its properties. | |
| virtual void | getValuesInternal (int requiredPropertyIndex, vector< string > &values)=0 |
| Get the values for the index in required properties and add them to the values vector supplied. | |
| virtual bool | hasValuesInternal (int requiredPropertyIndex)=0 |
| Get whether or not there are valid values available for the property identified by its index in the required properties. | |
| virtual const char * | getNoValueMessageInternal (fiftyoneDegreesResultsNoValueReason reason)=0 |
| Get the message explaining the reason for missing values. | |
| virtual fiftyoneDegreesResultsNoValueReason | getNoValueReasonInternal (int requiredPropertyIndex)=0 |
| Get the reason for values not being available. | |
Protected Attributes | |
| fiftyoneDegreesPropertiesAvailable * | available |
| Pointer to the underlying available properties structure. | |
Constructor & Destructor Documentation
◆ ResultsBase()
| FiftyoneDegrees::Common::ResultsBase::ResultsBase | ( | fiftyoneDegreesResultsBase * | results, |
| shared_ptr< fiftyoneDegreesResourceManager > | manager ) |
Create a new instance of Results from the results structure provided.
This method should only be called from inside an engine's process method.
- Parameters
-
results pointer to the underlying results structure manager shared pointer to the manager which manages the data set used to create the results. This is needed for thread-safe operation, see local variable description for more info.
Member Function Documentation
◆ allowedRequiredPropertyIndex()
|
protected |
Get the index a read by required property index uses, which is the index given when the engine named its properties.
When it named none there are no required property indexes, so -1 is given, which reads as a property the data set does not have.
- Parameters
-
requiredPropertyIndex index given by the caller
- Returns
- the index to read, or -1
◆ containsProperty()
| bool FiftyoneDegrees::Common::ResultsBase::containsProperty | ( | const string & | propertyName | ) | const |
Get whether or not this results instance contains a value for the requested property.
- Parameters
-
propertyName name of the property to check for
- Returns
- true if there is a value for the requested property
◆ getAvailableProperties()
| int FiftyoneDegrees::Common::ResultsBase::getAvailableProperties | ( | ) | const |
Get the number of required property indexes, which is the number of names the engine was created with, including any the data file lacks.
When the engine named no properties, it is the number of properties the data set has.
- Returns
- the number of required property indexes
◆ getNoValueMessageInternal()
|
protectedpure virtual |
Get the message explaining the reason for missing values.
This can differ slightly between APIs, so the implementation of this is left up to the extending class. This is used when populating a Value instance to return.
- Parameters
-
reason the enum indicating the reason no values are available
- Returns
- string explaining the reason in more detail
Implemented in FiftyoneDegrees::DeviceDetection::Hash::ResultsHash.
◆ getNoValueReasonInternal()
|
protectedpure virtual |
Get the reason for values not being available.
This is implemented by the extending class and is called when the hasValuesInternal method returns false.
- Parameters
-
requiredPropertyIndex required property index of the property
- Returns
- enum indicating the reason for values not being available
Implemented in FiftyoneDegrees::DeviceDetection::Hash::ResultsHash.
◆ getProperties()
| vector< string > FiftyoneDegrees::Common::ResultsBase::getProperties | ( | ) | const |
Get the names of the properties the data set has, in ascending order.
A name's place in the vector is not its required property index when the engine named its properties, so read the values by name.
- Returns
- vector containing the names of all available properties
◆ getPropertyName()
| string FiftyoneDegrees::Common::ResultsBase::getPropertyName | ( | int | requiredPropertyIndex | ) | const |
Get the name of the property at the required property index, or an empty string if there is no property at the index.
A property the data file lacks gives the name the engine was created with.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no name, as there are no indexes
- Returns
- the name of the property, or an empty string if not valid
◆ getRequiredPropertyIndex()
|
protected |
Get the required property index of the property name provided.
- Returns
- 0 based index or -1 if not found
◆ getValueAsBool() [1/4]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsBool | ( | const char * | propertyName | ) |
Get a boolean representation of the value associated with the required property name.
If the property name is not valid then false is returned. Stored text such as "Unknown" gives false with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictBool(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a boolean representation of the value for the property
- Examples
- Hash/StronglyTyped.cpp.
◆ getValueAsBool() [2/4]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsBool | ( | const string & | propertyName | ) |
Get a boolean representation of the value associated with the required property name.
If the property name is not valid then false is returned. Stored text such as "Unknown" gives false with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictBool(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a boolean representation of the value for the property
◆ getValueAsBool() [3/4]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsBool | ( | const string * | propertyName | ) |
Get a boolean representation of the value associated with the required property name.
If the property name is not valid then false is returned. Stored text such as "Unknown" gives false with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictBool(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a boolean representation of the value for the property
◆ getValueAsBool() [4/4]
|
virtual |
Get a boolean representation of the value associated with the required property index.
If the property index is not valid then false is returned. Stored text such as "Unknown" gives false with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictBool(int).
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- a boolean representation of the value for the property
◆ getValueAsDouble() [1/4]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsDouble | ( | const char * | propertyName | ) |
Get a double representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictDouble(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a double representation of the value for the property
◆ getValueAsDouble() [2/4]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsDouble | ( | const string & | propertyName | ) |
Get a double representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictDouble(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a double representation of the value for the property
◆ getValueAsDouble() [3/4]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsDouble | ( | const string * | propertyName | ) |
Get a double representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictDouble(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- a double representation of the value for the property
◆ getValueAsDouble() [4/4]
|
virtual |
Get a double representation of the value associated with the required property index.
If the property index is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictDouble(int).
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- a double representation of the value for the property
◆ getValueAsInteger() [1/4]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsInteger | ( | const char * | propertyName | ) |
Get an integer representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictInteger(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- an integer representation of the value for the property
◆ getValueAsInteger() [2/4]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsInteger | ( | const string & | propertyName | ) |
Get an integer representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictInteger(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- an integer representation of the value for the property
◆ getValueAsInteger() [3/4]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsInteger | ( | const string * | propertyName | ) |
Get an integer representation of the value associated with the required property name.
If the property name is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictInteger(const char*).
- Parameters
-
propertyName string containing the property name
- Returns
- an integer representation of the value for the property
◆ getValueAsInteger() [4/4]
|
virtual |
Get an integer representation of the value associated with the required property index.
If the property index is not valid then 0 is returned. Using a property which returns non-numeric characters will result in unexpected behavior. Stored text such as "Unknown" gives 0 with a value, which is kept for backwards compatibility. The remedy until version 5 is getValueAsStrictInteger(int).
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- an integer representation of the value for the property
◆ getValueAsStrictBool() [1/3]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictBool | ( | const char * | propertyName | ) |
Get the value as a boolean only if its text is "True" or "False".
Any other text, such as "Unknown", gives no value, where getValueAsBool(const char*) gives false. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictBool() [2/3]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictBool | ( | const string & | propertyName | ) |
Get the value as a boolean only if its text is "True" or "False".
Any other text, such as "Unknown", gives no value, where getValueAsBool(const char*) gives false. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictBool() [3/3]
| Value< bool > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictBool | ( | int | requiredPropertyIndex | ) |
Get the value as a boolean only if its text is "True" or "False".
Any other text, such as "Unknown", gives no value, where getValueAsBool(int) gives false. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictDouble() [1/3]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictDouble | ( | const char * | propertyName | ) |
Get the value as a double only if all of its text is a finite number.
Any other text, such as "Unknown", gives no value, where getValueAsDouble(const char*) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictDouble() [2/3]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictDouble | ( | const string & | propertyName | ) |
Get the value as a double only if all of its text is a finite number.
Any other text, such as "Unknown", gives no value, where getValueAsDouble(const char*) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictDouble() [3/3]
| Value< double > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictDouble | ( | int | requiredPropertyIndex | ) |
Get the value as a double only if all of its text is a finite number.
Any other text, such as "Unknown", gives no value, where getValueAsDouble(int) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictInteger() [1/3]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictInteger | ( | const char * | propertyName | ) |
Get the value as an integer only if all of its text is a whole number an int can hold.
Any other text, such as "Unknown", gives no value, where getValueAsInteger(const char*) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictInteger() [2/3]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictInteger | ( | const string & | propertyName | ) |
Get the value as an integer only if all of its text is a whole number an int can hold.
Any other text, such as "Unknown", gives no value, where getValueAsInteger(const char*) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
propertyName string containing the property name
- Returns
- the value, or the reason there is no value
◆ getValueAsStrictInteger() [3/3]
| Value< int > FiftyoneDegrees::Common::ResultsBase::getValueAsStrictInteger | ( | int | requiredPropertyIndex | ) |
Get the value as an integer only if all of its text is a whole number an int can hold.
Any other text, such as "Unknown", gives no value, where getValueAsInteger(int) gives 0. This is the remedy until version 5, as that accessor keeps its behaviour for backwards compatibility.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- the value, or the reason there is no value
◆ getValueAsString() [1/4]
| Value< string > FiftyoneDegrees::Common::ResultsBase::getValueAsString | ( | const char * | propertyName | ) |
Get a string representation of the value associated with the required property name.
If the property name is not valid an empty string is returned. If the property relates to a list with more than one value then values are separated by '|' characters.
- Parameters
-
propertyName string containing the property name
- Returns
- a string representation of the value for the property
- Examples
- Hash/GettingStarted.cpp, and Hash/MatchMetrics.cpp.
◆ getValueAsString() [2/4]
| Value< string > FiftyoneDegrees::Common::ResultsBase::getValueAsString | ( | const string & | propertyName | ) |
Get a string representation of the value associated with the required property name.
If the property name is not valid an empty string is returned. If the property relates to a list with more than one value then values are separated by '|' characters.
- Parameters
-
propertyName string containing the property name
- Returns
- a string representation of the value for the property
◆ getValueAsString() [3/4]
| Value< string > FiftyoneDegrees::Common::ResultsBase::getValueAsString | ( | const string * | propertyName | ) |
Get a string representation of the value associated with the required property name.
If the property name is not valid an empty string is returned. If the property relates to a list with more than one value then values are separated by '|' characters.
- Parameters
-
propertyName string containing the property name
- Returns
- a string representation of the value for the property
◆ getValueAsString() [4/4]
|
virtual |
Get a string representation of the value associated with the required property index.
If the index is not valid an empty string is returned. If the property relates to a list with more than one value then values are separated by '|' characters.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- a string representation of the value for the property or an empty string
◆ getValues() [1/4]
| Value< vector< string > > FiftyoneDegrees::Common::ResultsBase::getValues | ( | const char * | propertyName | ) |
Get a vector with all values associated with the required property name.
If the name is not valid an empty vector is returned.
- Parameters
-
propertyName pointer to a string containing the property name
- Returns
- a vector of values for the property
◆ getValues() [2/4]
| Value< vector< string > > FiftyoneDegrees::Common::ResultsBase::getValues | ( | const string & | propertyName | ) |
Get a vector with all values associated with the required property name.
If the name is not valid an empty vector is returned.
- Parameters
-
propertyName pointer to a string containing the property name
- Returns
- a vector of values for the property
◆ getValues() [3/4]
| Value< vector< string > > FiftyoneDegrees::Common::ResultsBase::getValues | ( | const string * | propertyName | ) |
Get a vector with all values associated with the required property name.
If the name is not valid an empty vector is returned.
- Parameters
-
propertyName pointer to a string containing the property name
- Returns
- a vector of values for the property
◆ getValues() [4/4]
| Value< vector< string > > FiftyoneDegrees::Common::ResultsBase::getValues | ( | int | requiredPropertyIndex | ) |
Get a vector with all values associated with the required property index.
If the index is not valid an empty vector is returned.
- Parameters
-
requiredPropertyIndex index of the property in the names the engine was created with. When the engine named no properties there is no value, with the invalid property reason, so read by name
- Returns
- a vector of values for the property
◆ getValuesInternal()
|
protectedpure virtual |
Get the values for the index in required properties and add them to the values vector supplied.
This is implemented by extending classes.
- Parameters
-
requiredPropertyIndex required property index of the property values vector to populate with the values for the property
Implemented in FiftyoneDegrees::DeviceDetection::Hash::ResultsHash.
◆ hasValuesInternal()
|
protectedpure virtual |
Get whether or not there are valid values available for the property identified by its index in the required properties.
This is implemented by extending classes, and used when populating a Value instance to return.
- Parameters
-
requiredPropertyIndex required property index of the property
- Returns
- true if there are values available for the property
Implemented in FiftyoneDegrees::DeviceDetection::Hash::ResultsHash.
The documentation for this class was generated from the following file: