Key Expressions

Classes and functions for processing key expressions. See zenoh abstractions and Key Expression RFC for detailed explanation of key expression concept.

Key expression can be registered in the zenoh::Session object with zenoh::Session::declare_keyexpr() method. The unique id is internally assinged to the key expression string in this case.

There is a subtle difference between zenoh-c and zenoh-pico implementations of key expressions which affects the key expression API. In the zenoh-c the key expresssion structure stores both the assigned id and the original key expression string. On the contrary, for declared key expressions the zenoh-pico keeps only the unique id in the key expression instance. The string representation is avaliable through the zenoh::KeyExprView::resolve() method only, which accesses the zenoh::Session instance.

Therefore in zenoh-pico case the text compare operations between the KeyExprView objects will return error result for declared key expressions.

For that reason the operations without explicit error handling are disabled for zenoh-pico. The methods which automatically performs the necessary resolving are provided instead: zenoh::Session::keyexpr_equals(), zenoh::Session::keyexpr_includes(), zenoh::Session::keyexpr_intersects().

inline bool zenoh::keyexpr_canonize(std::string &s, ErrNo &error)

Make a string containing a key expression canonical.

Parameters:

s – std::string with key expression
error – error code returned if the key expression is invalid

Returns:

true if the key expression was canonized, false otherwise

inline bool zenoh::keyexpr_canonize(std::string &s)

Make a string containing a key expression canonical.

Parameters:: s – std::string with key expression

inline bool zenoh::keyexpr_is_canon(const std::string_view &s, ErrNo &error)

Check if a string containing a key expression is canonical.

Parameters:

s – std::string_view with key expression
error – error code returned if the key expression is invalid

Returns:

true if the key expression is canonical, false otherwise

inline bool zenoh::keyexpr_is_canon(const std::string_view &s)

Check if a string containing a key expression is canonical.

Parameters:: s – std::string_view with key expression
Returns:: true if the key expression is canonical, false otherwise

inline zenoh::KeyExpr zenoh::keyexpr_concat(const zenoh::KeyExprView &k, const std::string_view &s)

Concatenate the key expression and a string.

Parameters:

k – the key expression
s – std::string_view representing a key expression

Returns:

Newly allocated key expression zenoh::KeyExpr

Note

zenoh-c only

inline zenoh::KeyExpr zenoh::keyexpr_join(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Join two key expressions, inserting a separator between them.

Parameters:

a – Key expression
b – Key expressio

Returns:

Newly allocated key expression zenoh::KeyExpr

Note

zenoh-c only

inline bool zenoh::keyexpr_equals(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the two key expressions are equal.

Parameters:

a – Key expression
b – Key expression
error – Error code returned by ::z_keyexpr_equals (value < -1 if any of the key expressions is not valid)

Returns:

true the key expressions are equal

inline bool zenoh::keyexpr_equals(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the two key expressions are equal.

Parameters:

a – Key expression
b – Key expression

Returns:

true the key expressions are equal

inline bool zenoh::keyexpr_includes(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the key expression includes another key expression, i.e. if the set defined by the key expression contains the set defined by the other key expression.

Parameters:

a – Key expression
b – Key expression
error – Error code returned by ::z_keyexpr_includes (value < -1 if any of the key expressions is not valid)

Returns:

true the key expression includes the other key expression

inline bool zenoh::keyexpr_includes(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the key expression includes another key expression, i.e. if the set defined by the key expression contains the set defined by the other key expression.

Parameters:

a – Key expression
b – Key expression

Returns:

true the key expression includes the other key expression

inline bool zenoh::keyexpr_intersects(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the key expression intersects with another key expression, i.e. there exists at least one key which is contained in both of the sets defined by the key expressions.

Parameters:

a – Key expression
b – Key expression
error – Error code returned by ::z_keyexpr_intersects (value < -1 if any of the key expressions is not valid)

Returns:

true the key expression intersects with the other key expression

inline bool zenoh::keyexpr_intersects(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the key expression intersects with another key expression, i.e. there exists at least one key which is contained in both of the sets defined by the key expressions.

Parameters:

a – Key expression
b – Key expression

Returns:

true the key expression intersects with the other key expression

struct KeyExprUnchecked: Empty type used to distinguish checked and unchecked constructing of KeyExprView.

struct KeyExprView : public zenohcxx::Copyable<::z_keyexpr_t>

The non-owning read-only view to a key expression in Zenoh. See details about key expression syntax in the Key Expressions RFC.

Constructors

inline KeyExprView(std::nullptr_t): Constructs an uninitialized instance.

inline KeyExprView(const char *name): Constructs an instance from a null-terminated string representing a key expression.

inline KeyExprView(const char *name, zenoh::KeyExprUnchecked)

Constructs an instance from a null-terminated string representing a key expression withot validating it In debug mode falis on assert if passed string is not a valid key expression.

Parameters:

name – the null-terminated string representing a key expression
_unchecked – the empty type used to distinguish checked and unchecked construncting of KeyExprView

inline KeyExprView(const std::string &name)

Constructs an instance from a std::string representing a key expression.

Parameters:: name – the string representing a key expression

inline KeyExprView(const std::string_view &name)

Constructs an instance from std::string_view representing a key expression.

Parameters:: name – the std::string_view representing a key expression

Note

zenoh-c only. Zenoh-pico supports only null-terminated key expression strings

inline KeyExprView(const std::string_view &name, zenoh::KeyExprUnchecked)

Constructs an instance from std::string_view representing a key expression without validating it.

Parameters:: name – the std::string_view representing a key expression

Note

zenoh-c only. Zenoh-pico supports only null-terminated key expression strings

Operators

inline bool operator==(const std::string_view &v) const

Equality operator between a key expression and a string.

Parameters:: v – std::string_view representing a key expression
Returns:: true if the key expression and the string are equal

inline bool operator!=(const std::string_view &v) const

Inequality operator between a key expression and a string.

Parameters:: v – std::string_view representing a key expression
Returns:: true if the key expression and the string are not equal

Methods

inline bool check() const

Checks if the key expression is valid.

Returns:: true if the key expression is valid

inline zenoh::BytesView as_bytes() const

Return the key BytesView on the key expression.

Returns:: BytesView structure pointing to the key expression

inline std::string_view as_string_view() const

Return the key expression as a std::string_view

Returns:: std::string_view representing the key expression

zenoh::Str resolve(const zenoh::Session &s) const

Get string representation for key expression created with zenoh::Session::declare_keyexpr

Parameters:: s – zenoh::Session object
Returns:: string representation of the key expression

Note

zenoh-pico only

zenoh::KeyExpr concat(const std::string_view &s) const: see zenoh::keyexpr_concat

Note

zenoh-c only

zenoh::KeyExpr join(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_join

Note

zenoh-c only

bool equals(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_equals

bool includes(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_includes

bool intersects(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_intersects

bool equals(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_equals

bool includes(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_includes

bool intersects(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_intersects

class KeyExpr : public zenohcxx::Owned<::z_owned_keyexpr_t>

Owned key expression. See details about key expression syntax in the Key Expressions RFC.

Constructors

inline explicit KeyExpr(std::nullptr_t): Create an uninitialized instance.

inline explicit KeyExpr(const char *name): Create a new instance from a null-terminated string.

Methods

inline zenoh::KeyExprView as_keyexpr_view() const

Get the key expression value.

Returns:: KeyExprView referencing the key expression value in the object

inline zenoh::BytesView as_bytes() const

Get the key expression value.

Returns:: BytesView referencing the key expression value in the object

inline std::string_view as_string_view() const

Get the key expression value.

Returns:: std::string_view referencing the key expression value in the object

Operators

inline operator zenoh::KeyExprView() const

Get the key expression value.

Returns:: KeyExprView referencing the key expression value in the object

inline bool operator==(const std::string_view &v)

Equality operator.

Parameters:: v – the std::string_view to compare with
Returns:: true if the key expression is equal to the string

zenoh::KeyExpr concat(const std::string_view &s) const: see zenoh::keyexpr_concat

Note

zenoh-c only

zenoh::KeyExpr join(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_join

Note

zenoh-c only

bool equals(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_equals

bool includes(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_includes

bool intersects(const zenoh::KeyExprView &v) const: see zenoh::keyexpr_intersects

bool equals(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_equals

bool includes(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_includes

bool intersects(const zenoh::KeyExprView &v, ErrNo &error) const: see zenoh::keyexpr_intersects