User Manual

Class uiink::Query

Wrapper around ink_query.

This allows you to find a Data object in a list that matches given field value(s).

For an overview of the Query API, see: http://uiink.com/docs/query_api/

This API will do a heap allocation if you match against more than five fields at once. For five or fewer fields the list of fields is stored on the stack.

Methods

Query(Data& parent, Ident list_field)
~Query()
Query(Query&& that)
Query& operator=(Query&& that)
Query& match_int(Ident field, int v)
Query& match_bool(Ident field, bool v)
Query& match_string(Ident field, const String& v)

Matches a string (with reference counting)

Query& match_string(Ident field, ink_str v)

Matches a string (with reference counting)

Query& match_string(Ident field, const char* v)

Matches a string (creating a copy)

Query& match_string(Ident field, const std::string& v)

Matches a string (creating a copy)

Query& match_string_reference(Ident field, const char* v)

Matches a string (without creating a copy)

Note that with this method the Query object stores the pointer. The contents of the string must be valid for the lifetime of the Query.

In case of doubt, use Query::match_string(), which is less error prone.

Query& match_ident(Ident field, Ident v)
Query& match_color(Ident field, uint32_t v)
Data get()

Return the first Data that matches this Query, creating it if it doesn't exist.

If a new entry had to be created, it will be automatically populated with the field values of this Query.

If this is called inside of Data::rebuild(), the returned Data object will not be removed when the rebuild ends.

Examples

using namespace uiink;
Data root = Ink().source("main");

Data first = root.query("entries").match_string("label", "Hello World!").get();
// For the first time we query, a new entry was created:
TEST_ASSERT(first.get_std_string("label") == "Hello World!");

Data second = root.query("entries").match_string("label", "Hello World!").get();
// The second time we query for the same match, the same entry is returned:
TEST_ASSERT(first == second);

Data maybe_get()

Return the first Data that matches this Query.

If no entry in the list matches the Query, a null Data will be returned. (The bool operator will return false on it.)

If this is called inside of Data::rebuild(), the returned Data object will not be removed when the rebuild ends.

Examples

using namespace uiink;
Data root = Ink().source("main");

Data first = root.query("entries").match_string("label", "Hello World!").maybe_get();
TEST_ASSERT_FALSE(first); // No match

root.append("entries").set_string("label", "Hello World!");

Data second = root.query("entries").match_string("label", "Hello World!").maybe_get();
TEST_ASSERT(second);

void remove()

Remove all Data objects that match this Query.

Examples

using namespace uiink;
Data root = Ink().source("main");

root.append("entries").set_string("label", "Hello World!");
TEST_ASSERT(root.get_child("entries", 0)); // entry was added

root.query("entries").match_string("label", "Hello World!").remove();
TEST_ASSERT_FALSE(root.get_child("entries", 0)); // entry was removed