Gazebo Physics

API Reference

5.3.2

The CompositeData class allows arbitrary data structures to be composed together, copied, and moved with type erasure. More...

#include <CompositeData.hh>

Classes

struct  DataStatus
 Struct that describes the status of data. More...
 
struct  InsertResult
 This struct is the return type of the various Insert...<T>() functions. It returns a reference to the data entry for the Data type, and it indicates whether the insertion operation actually occurred. More...
 

Public Types

using MapOfData = std::map< std::string, DataEntry >
 
enum  QueryMode : int { NORMAL = 0, SILENT }
 Use these flags in Query(), Has(), and StatusOf() to change their effects on the meta info of the data being queried. More...
 

Public Member Functions

 CompositeData ()
 Default constructor. Creates an empty CompositeData object. More...
 
 CompositeData (CompositeData &&_other)
 Move constructor. Same as Copy(_other). More...
 
 CompositeData (const CompositeData &_other)
 Copy constructor. Same as Copy(_other). More...
 
virtual ~CompositeData ()=default
 Virtual destructor. More...
 
std::set< std::stringAllEntries () const
 Get an ordered set of all data entries in this CompositeData. Runs with O(N) complexity. More...
 
CompositeDataCopy (CompositeData &&_other, const bool _mergeRequirements=false)
 An alternative to Copy(const CompositeData &, bool) that takes advantage of move semantics. More...
 
CompositeDataCopy (const CompositeData &_other, const bool _mergeRequirements=false)
 Make this CompositeData a copy of _other. However, any data entries in this CompositeData which are marked as required will not be removed. More...
 
std::size_t EntryCount () const
 Check how many data entries are in this CompositeData. Runs with O(1) complexity. More...
 
template<typename Data >
Data & Get ()
 Get a reference to a Data object. If an object of the Data type does not already exist in this CompositeData, then create one using its default constructor. This function will fail to compile if a default constructor is not available for the Data type. More...
 
template<typename Data >
bool Has () const
 Returns true if this CompositeData has an object of type Data, otherwise returns false. This is literally equivalent to (nullptr != Query<Data>(QueryMode::SILENT)). More...
 
template<typename Data , typename... Args>
InsertResult< Data > Insert (Args &&..._args)
 This will attempt to insert a new Data entry into the CompositeData object, forwarding _args to the constructor of the entry. If an entry already exists for this Data type, then nothing will be inserted. More...
 
template<typename Data , typename... Args>
InsertResult< Data > InsertOrAssign (Args &&... _args)
 Attempt to insert a Data-type entry. If a Data-type entry did not already exist, it will be constructed by copying (or moving) the given arguments. If a Data-type entry already existed, the existing entry will be assigned the value of Data(_args...). More...
 
template<typename Data , typename... Args>
Data & MakeRequired (Args &&..._args)
 Marks the specified type of Data as required, creates one with the given arguments if it did not exist, and returns a reference to it. More...
 
CompositeDataMerge (CompositeData &&_other, const bool _mergeRequirements=false)
 An alternative to Merge(const CompositeData &, bool) that takes advantage of move semantics. More...
 
CompositeDataMerge (const CompositeData &_other, const bool _mergeRequirements=false)
 Merge the data from _other into this CompositeData. If there are any conflicting data entries, the entry from _other will take precedence. More...
 
CompositeDataoperator= (CompositeData &&_other)
 Move operator. Same as Copy(_other). More...
 
CompositeDataoperator= (const CompositeData &_other)
 Copy operator. Same as Copy(_other). More...
 
template<typename Data >
Data * Query (const QueryMode _mode=QueryMode::NORMAL)
 Query this CompositeData for a Data-type entry. If it contains a Data-type object, it gets returned as a Data*. Otherwise, a nullptr is returned. More...
 
template<typename Data >
const Data * Query (const QueryMode mode=QueryMode::NORMAL) const
 Const-qualified version of Query. This can be used to retrieve data from a const CompositeData. More...
 
template<typename Data >
bool Remove ()
 This will remove a Data-type object from this CompositeData and delete it if one is present. Otherwise, it will do nothing. Data-types that are marked as required will not (and cannot) be removed. More...
 
template<typename Data >
bool Requires () const
 Returns true if the specified Data type is required by this CompositeData object. Otherwise, returns false. More...
 
void ResetQueries () const
 Reset the query flags on all data entries. This will make it appear as though no entries have ever been queried. See UnqueriedEntries() for more information about the "queried" flag. More...
 
template<typename Data >
DataStatus StatusOf () const
 Returns a DataStatus object that describes the status of the requested data type. More...
 
std::set< std::stringUnqueriedEntries () const
 Get an ordered (alphabetical) set of the data entries in this CompositeData which have not been queried (Get, Insert, InsertOrAssign, Query, and MakeRequired all perform querying) since the data was implicitly created (e.g. by a copy or move operation) or since the last call to ResetQueries(), whichever is more recent. Runs with O(N) complexity. More...
 
std::size_t UnqueriedEntryCount () const
 Check how many data entries in this CompositeData have not been queried. See UnqueriedEntries() for more information about the "queried" flag. Runs with O(1) complexity. More...
 
template<typename Data >
bool Unquery () const
 Returns true if this CompositeData has a Data-type object which was marked as queried, and that object is now marked as unqueried. If an object of that type does not exist or it was already unqueried, this returns false. More...
 

Static Public Member Functions

template<typename Data >
static constexpr bool AlwaysRequires ()
 When called from a generic CompositeData type, this always returns false. Static (Always) requirements are determined at compile-time and cannot be changed at runtime. Using the RequireData class can make this return true for more highly specified CompositeData types. More...
 
template<typename Data >
static constexpr bool Expects ()
 When called from a generic CompositeData type, this always returns false. More highly specified CompositeData types that use ExpectData or RequireData may return true if the type of Data is expected. More...
 

Protected Attributes

MapOfData dataMap
 Map from the label of a data object type to its entry. More...
 
std::size_t numEntries
 Total number of data entries currently in this CompositeData. Note that this may differ from the size of dataMap, because some entries in dataMap will be referring to nullptrs. More...
 
std::size_t numQueries
 Total number of unique queries which have been performed since either construction or the last call to ResetQueries(). More...
 

Detailed Description

The CompositeData class allows arbitrary data structures to be composed together, copied, and moved with type erasure.

Member Typedef Documentation

◆ MapOfData

using MapOfData = std::map<std::string, DataEntry>

Member Enumeration Documentation

◆ QueryMode

enum QueryMode : int
strong

Use these flags in Query(), Has(), and StatusOf() to change their effects on the meta info of the data being queried.

See UnqueriedEntries() for more on the "queried" flag.

Enumerator
NORMAL 

Performing the operation will cause an unqueried Data's status to flip to queried. Data that is already marked as queried will be unaffected.

SILENT 

Performing the operation has no effect on whether data is marked as queried.

Constructor & Destructor Documentation

◆ CompositeData() [1/3]

Default constructor. Creates an empty CompositeData object.

◆ ~CompositeData()

virtual ~CompositeData ( )
virtualdefault

Virtual destructor.

◆ CompositeData() [2/3]

CompositeData ( const CompositeData _other)

Copy constructor. Same as Copy(_other).

◆ CompositeData() [3/3]

CompositeData ( CompositeData &&  _other)

Move constructor. Same as Copy(_other).

Member Function Documentation

◆ AllEntries()

std::set<std::string> AllEntries ( ) const

Get an ordered set of all data entries in this CompositeData. Runs with O(N) complexity.

Example usage:

#include <iostream>
using namespace ignition::physics;
struct MyData1
{
/* ... put some data here ... */
};
struct MyData2
{
/* ... put some data here ... */
};
struct MyData3
{
/* ... put some data here ... */
};
void PrintStuff(const CompositeData &composite)
{
std::cout << "Entry types:" << std::endl;
for (const std::string &label : composite.AllEntries())
{
std::cout << " " << label << std::endl;
}
}
int main()
{
CompositeData composite;
composite.Insert<MyData1>();
composite.Insert<MyData2>();
composite.Insert<MyData3>();
PrintStuff(composite);
// The function PrintStuff will print the names of each struct.
}
Returns
an ordered (alphabetical) set of all data entries in this CompositeData.

◆ AlwaysRequires()

static constexpr bool AlwaysRequires ( )
staticconstexpr

When called from a generic CompositeData type, this always returns false. Static (Always) requirements are determined at compile-time and cannot be changed at runtime. Using the RequireData class can make this return true for more highly specified CompositeData types.

Warning
This should never be used to check whether Data is required on a specific instance, because the requirements that are placed on an instance can be changed at runtime. This should only be used to check whether a certain data type is always required for a certain specification of CompositeData.
Template Parameters
DataThe type of data whose requirement we are checking at compile time
Returns
When called on a basic CompositeData object, this is always false.

◆ Copy() [1/2]

CompositeData& Copy ( CompositeData &&  _other,
const bool  _mergeRequirements = false 
)

An alternative to Copy(const CompositeData &, bool) that takes advantage of move semantics.

◆ Copy() [2/2]

CompositeData& Copy ( const CompositeData _other,
const bool  _mergeRequirements = false 
)

Make this CompositeData a copy of _other. However, any data entries in this CompositeData which are marked as required will not be removed.

Parameters
[in]_otherAnother CompositeData
[in]_mergeRequirementsIf true, this object will also take on the requirements specified by _other. Any objects that are already marked as required in this CompositeData will remain required. If false, the requirements of this CompositeData object are unaffected.
Returns
A reference to this object
See also
Copy(CompositeData &&, bool)
Merge()
operator=()

◆ EntryCount()

std::size_t EntryCount ( ) const

Check how many data entries are in this CompositeData. Runs with O(1) complexity.

Returns
the number of data entries currently contained in this CompositeData.

◆ Expects()

static constexpr bool Expects ( )
staticconstexpr

When called from a generic CompositeData type, this always returns false. More highly specified CompositeData types that use ExpectData or RequireData may return true if the type of Data is expected.

Template Parameters
DataThe type of data whose expectation is being checked
Returns
When called on a basic CompositeData object, this is always false.

◆ Get()

Data& Get ( )

Get a reference to a Data object. If an object of the Data type does not already exist in this CompositeData, then create one using its default constructor. This function will fail to compile if a default constructor is not available for the Data type.

When you have a const CompositeData object, you must use the function CompositeData::query<Data>() in order to retrieve objects.

Example usage:

#include <iostream>
using namespace ignition::physics;
// Create a data structure called MyData
struct MyData
{
std::string myString;
};
int main()
{
CompositeData composite;
// An object of type MyData is created using the default
// constructor of MyData. The MyData object will be stored
// inside of the object called "composite", and we can grab a
// mutable reference to it.
MyData &data = composite.Get<MyData>();
// We can modify the MyData object inside of "composite" using
// the mutable reference that we grabbed.
data.myString = "I modified this data";
// This will print out "I modified this data", because
// Get<MyData>() will retrieve the instance of MyData that was
// created by the first call of Get<MyData>().
std::cout << composite.Get<MyData>().myString << std::endl;
}
Template Parameters
DataThe type of data entry to get
Returns
a reference to to a Data-type object that is stored within this CompositeData.

◆ Has()

bool Has ( ) const

Returns true if this CompositeData has an object of type Data, otherwise returns false. This is literally equivalent to (nullptr != Query<Data>(QueryMode::SILENT)).

Template Parameters
DataThe type of data entry to check for
Returns
true if this CompositeData contains a Data-type entry.

◆ Insert()

InsertResult<Data> Insert ( Args &&...  _args)

This will attempt to insert a new Data entry into the CompositeData object, forwarding _args to the constructor of the entry. If an entry already exists for this Data type, then nothing will be inserted.

Example usage:

#include <iostream>
#include <cassert>
using namespace ignition::physics;
// Create a data structure called MyData
struct MyData
{
MyData(const std::string &_arg = "")
: myString(_arg)
{
// Intentionally blank
}
std::string myString;
};
int main()
{
CompositeData composite;
// Create an object of type MyData and store it in "composite".
// A reference to the newly created object is returned.
MyData &data = composite.Insert<MyData>("some argument").data;
// This will print out "some argument", because the string in
// MyData was initialized with that argument.
std::cout << composite.Get<MyData>().myString << std::endl;
// Modify the object
data.myString = "I modified this data";
// This will print out "I modified this data" because we used a
// mutable reference to change the value of MyData::myString.
std::cout << composite.Get<MyData>().myString << std::endl;
// This will not modify the MyData instance that's being held by
// "composite", because the instance already exists. It will
// just return the instance as a reference and ignore the
// argument that has been passed in.
MyData &altData = composite.Insert<MyData>(
"another argument").data;
// The reference to "data" is still perfectly valid, and in fact
// its underlying pointer is equal to the underlying pointer of
// "altData".
assert((&data) == (&altData));
// This will print out "I modified this data" because there have
// not been any function calls that can alter the value of
// myString in the time since that modification was made.
std::cout << composite.Insert<MyData>().data.myString
}
Template Parameters
DataThe type name for the data entry
ArgsThis will be inferred from _args; you should not typically set this explicitly.
Parameters
[in]_argsThe arguments to use for construction. These will get wrapped in a Data(...) constructor. If _args is left blank, the default constructor will be used.
Returns
An InsertResult<Data> which contains a reference to the data entry (either the one that is newly inserted or the one that already existed). InsertResult::inserted will be true if the entry was inserted by this function, or false if the entry already existed.
See also
InsertOrAssign

◆ InsertOrAssign()

InsertResult<Data> InsertOrAssign ( Args &&...  _args)

Attempt to insert a Data-type entry. If a Data-type entry did not already exist, it will be constructed by copying (or moving) the given arguments. If a Data-type entry already existed, the existing entry will be assigned the value of Data(_args...).

Any previously existing valid references to the Data entry will remain valid, even after this function is called.

Example usage:

#include <iostream>
using namespace ignition::physics;
// Create a data structure called MyData
struct MyData
{
MyData(const std::string &_arg = "")
: myString(_arg)
{
// Intentionally blank
}
std::string myString;
};
int main()
{
CompositeData composite;
// Create an object of type MyData and store it in "composite".
// A reference to the newly created object is returned.
MyData &data = composite.InsertOrAssign<MyData>(
"some argument").data;
// This will print out "some argument", because the string in
// MyData was initialized with that argument.
std::cout << composite.Get<MyData>().myString << std::endl;
// Modify the object
data.myString = "I modified this data";
// This will print out "I modified this data" because we used a
// mutable reference to change the value of MyData::myString.
std::cout << composite.Get<MyData>().myString << std::endl;
// Assign the MyData entry a new, default-constructed value.
composite.InsertOrAssign<MyData>();
// This will print out nothing but a newline.
std::cout << composite.Get<MyData>().myString << std::endl;
}
Template Parameters
DataThe type name for the data entry
ArgsThis will be inferred from _args; you should not typically set this explicitly.
Parameters
[in]_argsThe arguments to use for construction or assignment. These will get wrapped in a Data(...) constructor. If _args is left blank, the default constructor will be used.
Returns
an InsertResult<Data> which contains a reference to the Data-type entry of this CompositeData. InsertResult<Data>::inserted will be true iff a Data-type entry did not already exist in this CompositeData. If the value was instead assigned, InsertResult<Data>::inserted will be false.
See also
Insert

◆ MakeRequired()

Data& MakeRequired ( Args &&...  _args)

Marks the specified type of Data as required, creates one with the given arguments if it did not exist, and returns a reference to it.

Warning: This cannot be undone. Once a Data type is marked as required, it will continue to be required for this object throughout the rest of the CompositeData object's lifespan.

Example usage:

#include <cassert>
using namespace ignition::physics;
struct MyData
{
MyData(const std::string &arg = "")
: myString(arg)
{
// Intentionally blank
}
std::string myString;
};
int main()
{
CompositeData composite;
// Create an instance of MyData and mark it as required
composite.MakeRequired<MyData>("this is required");
// Now it cannot be removed from "composite"
assert(!composite.Remove<MyData>());
// Once "composite" goes out of scope, the MyData instance will
// be deleted as normal, because its lifecycle is still tied to
// the CompositeData object.
}
Template Parameters
DataThe type of data entry that should be marked as required
ArgsThis will be inferred from _args; you should not typically set this explicitly.
Parameters
[in]_argsThe arguments to use for construction, if a Data-type entry did not already exist within this CompositeData.
Returns
a reference to the Data-type entry

◆ Merge() [1/2]

CompositeData& Merge ( CompositeData &&  _other,
const bool  _mergeRequirements = false 
)

An alternative to Merge(const CompositeData &, bool) that takes advantage of move semantics.

◆ Merge() [2/2]

CompositeData& Merge ( const CompositeData _other,
const bool  _mergeRequirements = false 
)

Merge the data from _other into this CompositeData. If there are any conflicting data entries, the entry from _other will take precedence.

Parameters
[in]_otherAnother CompositeData
[in]_mergeRequirementsIf true, this object will also take on the requirements specified by _other. Any objects that are already marked as required in this CompositeData will remain required. If false, the requirements of this CompositeData object are unaffected.
Returns
A reference to this object
See also
Merge(CompositeData &&)
Copy()

◆ operator=() [1/2]

CompositeData& operator= ( CompositeData &&  _other)

Move operator. Same as Copy(_other).

◆ operator=() [2/2]

CompositeData& operator= ( const CompositeData _other)

Copy operator. Same as Copy(_other).

◆ Query() [1/2]

Data* Query ( const QueryMode  _mode = QueryMode::NORMAL)

Query this CompositeData for a Data-type entry. If it contains a Data-type object, it gets returned as a Data*. Otherwise, a nullptr is returned.

If _mode is set to QueryMode::SILENT, then calling this function will not cause the "queried" flag to change (see UnqueriedEntries() for more on the "queried" flag).

Example usage:

#include <iostream>
using namespace ignition::physics;
struct MyDataWithoutDefault
{
// This struct does not allow us to use the default constructor
MyDataWithoutDefault() = delete;
// We must call this constructor if we want to make an object of
// this type.
MyDataWithoutDefault(const int inputValue)
: myValue(inputValue)
{
// Intentionally blank
}
int myValue;
};
void SetValueIfAvailable(const int _value,
CompositeData &_composite)
{
// This CANNOT compile because MyDataWithoutDefault does not
// provide a default constructor
// MyDataWithoutDefault &data =
// composite.Get<MyDataWithoutDefault>();
// Get a pointer to a MyDataWithoutDefault instance if one is
// available, otherwise we get a nullptr.
MyDataWithoutDefault *data =
_composite.Query<MyDataWithoutDefault>();
if(data)
data->myValue = _value;
}
int main()
{
CompositeData composite;
// This will do nothing, because "composite" does not contain
// an object of type MyDataWithoutDefault.
SetValueIfAvailable(320, composite);
// We can create a MyDataWithoutDefault object by calling the
// Insert function and passing it an argument for the object's
// constructor.
composite.Insert<MyDataWithoutDefault>(123);
// This will print out "123" because the object will not be
// re-created by Insert. We can call Insert because it
// can use the argument we pass in to create an instance of
// MyDataWithoutDefault if an instance of it did not already
// exist, unlike Get which can only call the default
// constructor.
<< composite.Insert<MyDataWithoutDefault>(1).data.myValue
// This will set myValue to 5 because "composite" contains an
// instance of MyDataWithoutDefault.
SetValueIfAvailable(5, composite);
// This will print out "5" because that was the value set by
// SetValueIfAvailable.
<< composite.Insert<MyDataWithoutDefault>(3).data.myValue
}
Template Parameters
DataThe type of data entry to query for
Parameters
[in]_modeSpecify how this call should affect the query flag of the entry. The default behavior is strongly recommended, unless you know what you are doing. See QueryMode for more info.
Returns
a pointer to the Data entry if this CompositeData has one. Otherwise, this returns a nullptr.

◆ Query() [2/2]

const Data* Query ( const QueryMode  mode = QueryMode::NORMAL) const

Const-qualified version of Query. This can be used to retrieve data from a const CompositeData.

If "mode" is set to QueryMode::SILENT, then calling this function will not cause the "queried" flag to change (see UnqueriedEntries() for more on the "queried" flag).

Example usage:

#include <iostream>
using namespace ignition::physics;
struct MyData
{
std::string myString;
};
void PrintStringIfAvailable(const CompositeData &_composite)
{
// The following Get<T>() CANNOT compile because "composite" is
// a const-qualified reference, but Get<T>() is NOT a
// const-qualified member function. Get<T>() cannot be
// const-qualified because it needs to create an instance of
// type T if an instance of that type was not already available
// in the CompositeData object, and that would mean modifying
// the CompositeData object, which violates const-correctness.
// This is similarly the case for Insert<T>(~) and
// InsertOrAssign<T>(~).
//
// MyData &data = _composite.Get<T>(); // error!
// Instead, we use the const-qualified Query<T>() function which
// can return a const-qualified pointer to the data instance.
const MyData *data = _composite.Query<MyData>();
if(data)
std::cout << data->myString << std::endl;
else
std::cout << "No string available" << std::endl;
}
int main()
{
CompositeData composite;
// This will print "No string available" because "composite"
// does not have a MyData instance yet.
PrintStringIfAvailable(composite);
// Use the default constructor to create MyData, and use the
// reference it returns to set the value of MyData::myString.
composite.Get<MyData>().myString = "here is a string";
// This will print "here is a string".
PrintStringIfAvailable(composite);
}
Template Parameters
DataThe type of data entry to query for
Parameters
[in]_modeSpecify how this call should affect the query flag of the entry. The default behavior is strongly recommended, unless you know what you are doing. See QueryMode for more info.
Returns
a const-qualified pointer to the Data entry if this CompositeData has one. Otherwise, this returns a nullptr.

◆ Remove()

bool Remove ( )

This will remove a Data-type object from this CompositeData and delete it if one is present. Otherwise, it will do nothing. Data-types that are marked as required will not (and cannot) be removed.

If the data was successfully removed or did not exist to begin with, this returns true. If the data was marked as required and therefore not removed, this returns false.

Warning
Calling this function will permanently invalidate all existing references to the Data-type entry of this CompositeData, i.e. the references that get returned by Get<Data>(), Insert<Data>(~), InsertOrAssign<Data>(~), or Query<Data>().

Example usage:

#include <iostream>
using namespace ignition::physics;
// Create a data structure called MyData
struct MyData
{
MyData(const std::string &_arg = "")
: myString(_arg)
{
// Intentionally blank
}
std::string myString;
};
int main()
{
CompositeData composite;
// Create an object of type MyData and store it in "composite".
// Append .data to get a reference to the new data.
MyData &data = composite.Insert<MyData>("some argument").data;
// Print out "some argument"
<< composite.Insert<MyData>("another argument").data.myString
// Remove the MyData object. Note that "data" is now INVALID and
// must never be used again after this function call.
composite.Remove<MyData>();
// Print out "another argument"
<< composite.Insert<MyData>("another argument").data.myString
}
Template Parameters
DataThe type of data entry to remove
Returns
true iff the CompositeData no longer contains this Data type.

◆ Requires()

bool Requires ( ) const

Returns true if the specified Data type is required by this CompositeData object. Otherwise, returns false.

For more on required data, see MakeRequired<Data>().

Template Parameters
DataThe type of data entry whose requirements are being checked
Returns
true iff the specified Data type is required by this CompositeData

◆ ResetQueries()

void ResetQueries ( ) const

Reset the query flags on all data entries. This will make it appear as though no entries have ever been queried. See UnqueriedEntries() for more information about the "queried" flag.

Attention
It is good practice to call this function before returning a CompositeData from a function and handing it off to another segment of a pipeline, because sometimes the compiler inappropriately elides the copy/move constructor/operators and passes along the state of the queries, even though it should not.

◆ StatusOf()

DataStatus StatusOf ( ) const

Returns a DataStatus object that describes the status of the requested data type.

Template Parameters
DataThe type of data entry to check the status of
Returns
a DataStatus for the requested entry.

◆ UnqueriedEntries()

std::set<std::string> UnqueriedEntries ( ) const

Get an ordered (alphabetical) set of the data entries in this CompositeData which have not been queried (Get, Insert, InsertOrAssign, Query, and MakeRequired all perform querying) since the data was implicitly created (e.g. by a copy or move operation) or since the last call to ResetQueries(), whichever is more recent. Runs with O(N) complexity.

Unqueried data entries might be created by copy/move construction, copy/move assignment operation, or the Copy(~) function. Using the copy/move operator or the Copy(~) function will reset the query flag on any data that gets copied or moved over.

Note
This function can be useful for reporting runtime warnings about any unsupported data types that have been given to you.

Example usage:

#include <iostream>
using namespace ignition::physics;
struct MyData1
{
/* ... put some data here ... */
};
struct MyData2
{
/* ... put some data here ... */
};
struct MyData3
{
/* ... put some data here ... */
};
void DoStuff(CompositeData &composite)
{
MyData1 &data1 = composite.Get<MyData1>();
/* ... do something with data1 ... */
MyData2 &data2 = composite.Get<MyData2>();
/* ... do something with data2 ... */
const std::set<std::string> &unqueried =
composite.UnqueriedEntries();
if(unqueried.size() > 0)
{
std::cout << "I don't know what to do with "
<< "the following type(s) of data:\n";
for(const std::string &label : unqueried)
std::cout << " -- " << label << "\n";
}
}
int main()
{
CompositeData composite;
composite.Insert<MyData1>();
composite.Insert<MyData2>();
composite.Insert<MyData3>();
composite.ResetQueries();
DoStuff(composite);
// The function DoStuff will print out that it does not know
// what to do with MyData3.
}
Returns
an ordered set of the names of unqueried data entries in this CompositeData.

◆ UnqueriedEntryCount()

std::size_t UnqueriedEntryCount ( ) const

Check how many data entries in this CompositeData have not been queried. See UnqueriedEntries() for more information about the "queried" flag. Runs with O(1) complexity.

Returns
the number of entries in this CompositeData which have not been queried.

◆ Unquery()

bool Unquery ( ) const

Returns true if this CompositeData has a Data-type object which was marked as queried, and that object is now marked as unqueried. If an object of that type does not exist or it was already unqueried, this returns false.

This function is const-qualified because the query flags are declared as mutable.

Example usage:

#include <cassert>
using namespace ignition::physics;
struct MyData
{
std::string myString;
};
int main()
{
CompositeData composite;
CompositeData::DataStatus status = composite.StatusOf<MyData>();
// An instance of MyData should not exist, be required, or be
// queried.
assert(!status.exists);
assert(!status.queried);
assert(!status.required);
composite.Insert<MyData>();
status = composite.StatusOf<MyData>();
// MyData should now be queried, because explicitly creating an
// object will mark it as queried.
assert(status.exists);
assert(status.queried);
// Turn off the "queried" flag for MyData.
composite.Unquery<MyData>();
status = composite.StatusOf<MyData>();
assert(status.exists);
// It should be unqueried because we turned off its query flag
// using Unquery<MyData>().
assert(!status.queried);
}
Template Parameters
DataThe type of data entry whose query flag should be cleared
Returns
true if the query flag is changing from queried to unqueried, otherwise false.

Member Data Documentation

◆ dataMap

MapOfData dataMap
protected

Map from the label of a data object type to its entry.

◆ numEntries

std::size_t numEntries
protected

Total number of data entries currently in this CompositeData. Note that this may differ from the size of dataMap, because some entries in dataMap will be referring to nullptrs.

◆ numQueries

std::size_t numQueries
mutableprotected

Total number of unique queries which have been performed since either construction or the last call to ResetQueries().


The documentation for this class was generated from the following file:
bool exists
If the data exists in the CompositeData, this will be true, otherwise it is false.
Definition: gz/physics/CompositeData.hh:558
STL class.
Data * Query(const QueryMode _mode=QueryMode::NORMAL)
Query this CompositeData for a Data-type entry. If it contains a Data-type object,...
Struct that describes the status of data.
Definition: gz/physics/CompositeData.hh:554
bool Unquery() const
Returns true if this CompositeData has a Data-type object which was marked as queried,...
std::set< std::string > AllEntries() const
Get an ordered set of all data entries in this CompositeData. Runs with O(N) complexity.
std::set< std::string > UnqueriedEntries() const
Get an ordered (alphabetical) set of the data entries in this CompositeData which have not been queri...
Data & Get()
Get a reference to a Data object. If an object of the Data type does not already exist in this Compos...
bool Remove()
This will remove a Data-type object from this CompositeData and delete it if one is present....
DataStatus StatusOf() const
Returns a DataStatus object that describes the status of the requested data type.
InsertResult< Data > InsertOrAssign(Args &&... _args)
Attempt to insert a Data-type entry. If a Data-type entry did not already exist, it will be construct...
The CompositeData class allows arbitrary data structures to be composed together, copied,...
Definition: gz/physics/CompositeData.hh:43
T endl(T... args)
void ResetQueries() const
Reset the query flags on all data entries. This will make it appear as though no entries have ever be...
Data & MakeRequired(Args &&..._args)
Marks the specified type of Data as required, creates one with the given arguments if it did not exis...
bool required
If the data is marked as required, this will be true, otherwise it is false.
Definition: gz/physics/CompositeData.hh:567
InsertResult< Data > Insert(Args &&..._args)
This will attempt to insert a new Data entry into the CompositeData object, forwarding _args to the c...
Definition: gz/physics/BoxShape.hh:28
bool queried
If the data was marked as queried BEFORE calling StatusOf (regardless of what QueryMode is used),...
Definition: gz/physics/CompositeData.hh:563