|
| | MatchExpression (std::string varName, BoolMatch condition, bool value) |
| | Creates a new MatchExpression instance checking a boolean condition.
|
| | MatchExpression (std::string varName, NumberMatch condition, double value) |
| | Creates a new MatchExpression instance checking a numeric condition.
|
| | MatchExpression (std::string varName, StringMatch condition, std::string value) |
| | Creates a new MatchExpression instance checking a string condition.
|
| MatchExpression & | And (std::string varName, BoolMatch condition, bool value) & |
| | Concatenates a new boolean condition to this expression using the logical AND operator.
|
| MatchExpression & | And (std::string varName, NumberMatch condition, double value) & |
| | Concatenates a new numeric condition to this expression using the logical AND operator.
|
| MatchExpression & | And (std::string varName, StringMatch condition, std::string value) & |
| | Concatenates a new string condition to this expression using the logical AND operator.
|
| MatchExpression & | Or (std::string varName, BoolMatch condition, bool value) & |
| | Concatenates a new boolean condition to this expression using the logical OR operator.
|
| MatchExpression & | Or (std::string varName, NumberMatch condition, double value) & |
| | Concatenates a new numeric condition to this expression using the logical OR operator.
|
| MatchExpression & | Or (std::string varName, StringMatch condition, std::string value) & |
| | Concatenates a new string condition to this expression using the logical OR operator.
|
| MatchExpression && | And (std::string varName, BoolMatch condition, bool value) && |
| MatchExpression && | And (std::string varName, NumberMatch condition, double value) && |
| MatchExpression && | And (std::string varName, StringMatch condition, std::string value) && |
| MatchExpression && | Or (std::string varName, BoolMatch condition, bool value) && |
| MatchExpression && | Or (std::string varName, NumberMatch condition, double value) && |
| MatchExpression && | Or (std::string varName, StringMatch condition, std::string value) && |
| const std::vector< Condition > & | conditions () const |
| | Returns the conditions making up this expression, in evaluation order.
|
| std::string | toString () const |
| | Returns a string representation of the matching expression, e.g.
|
The MatchExpression class represents a matching expression used to compare custom variables or predefined properties when searching for users or Rooms.
Matching expressions are built like "if" statements in any common programming language. They work like queries in a database and can be used to search for Rooms or users using custom criteria: an expression can compare predefined properties of the Room and user entities (see the RoomProperties and UserProperties constants), but also custom Room or User Variables.
Additionally:
-
any number of conditions can be linked together with the logical AND and OR operators by chaining calls to And() and Or();
-
searching through nested data structures such as SFSObject and SFSArray can be done via a very simple dot-syntax.
Example
A simple matching expression made of two concatenated conditions: it compares the custom "rank" and "country" User Variables to the passed values. This expression could be used during the creation of a Game Room, to filter the users that the server should take into account when sending the invitations to join the game (only italian users with a ranking greater than 5 - whatever this number means to our game):
auto exp = MatchExpression("rank", NumberMatch::GREATER_THAN, 5).And("country", StringMatch::EQUALS, "Italy");
Example
An expression made of three concatenated conditions which compare two predefined Room properties and the custom "isGameStarted" Room Variable to the passed values; this could be used to retrieve all the Game Rooms still waiting for players to join them:
auto exp = MatchExpression(RoomProperties::IS_GAME, BoolMatch::EQUALS, true)
.And(RoomProperties::HAS_FREE_PLAYER_SLOTS, BoolMatch::EQUALS, true)
.And("isGameStarted", BoolMatch::EQUALS, false);
Example
An expression comparing a nested property in a complex data structure; an SFSObject called "avatarData" (could be a User Variable for example) contains the "shield" object (a nested SFSObject) which in turn contains, among others, the "inUse" property, which could be used to retrieve all users whose avatars are currently equipped with a shield:
auto exp = MatchExpression("avatarData.shield.inUse", BoolMatch::EQUALS, true);
Example
Similar to the previous one, but involving an SFSArray. The "avatarData" object contains the "weapons" SFSArray, from which the expression retrieves the fourth element (that .3 means "give me the element at index == 3") that we know being the weapon the user avatar has in his right hand. Again, this element is an SFSObject containing, among the others, the "name" property, which can be compared to the passed string. This example could be used to retrieve all users whose avatars have the Narsil sword in the right hand:
auto exp = MatchExpression("avatarData.weapons.3.name", StringMatch::EQUALS, "Narsil");
NOTE on evaluation order: the server evaluates the conditions strictly left to right, with no operator precedence: each condition is combined with the result accumulated so far. This means that A OR B AND C is evaluated as (A OR B) AND C, and not as A OR (B AND C) as the usual precedence rules would suggest.
NOTE on chaining: And() and Or() append to the expression they are called on and hand it back, so a chain always yields the whole expression, not its last condition. Assign the result of a chain started on a temporary to a value (auto exp = ...), never to a reference: the temporary is destroyed at the end of the full expression and binding a reference to it would leave that reference dangling.
- See also
- RoomProperties
-
UserProperties
-
BoolMatch
-
NumberMatch
-
StringMatch
1.18.0