libcaf  0.15.3
Classes | Public Types | Public Member Functions | Static Public Member Functions | Related Functions | List of all members
caf::message Class Reference

Describes a fixed-length, copy-on-write, type-erased tuple with elements of any type. More...

#include <message.hpp>

Classes

struct  cli_arg
 Stores the name of a command line option ("<long name>[,<short name>]") along with a description and a callback. More...
 
struct  cli_res
 Stores the result of message::extract_opts. More...
 

Public Types

using raw_ptr = detail::message_data *
 Raw pointer to content.
 
using data_ptr = detail::message_data::cow_ptr
 Copy-on-write pointer to content.
 
using help_factory = std::function< std::string(const std::vector< cli_arg > &)>
 Function object for generating CLI argument help text.
 

Public Member Functions

 message (none_t) noexcept
 
 message (const message &) noexcept=default
 
messageoperator= (const message &) noexcept=default
 
 message (message &&) noexcept
 
messageoperator= (message &&) noexcept
 
 message (data_ptr ptr) noexcept
 
messageoperator+= (const message &x)
 Concatenates *this and x.
 
void * get_mutable (size_t p)
 Returns a mutable pointer to the element at position p.
 
template<class T >
T & get_mutable_as (size_t p)
 Returns the value at position p as mutable reference of type T.
 
optional< messageapply (message_handler handler)
 Returns handler(*this).
 
void force_unshare ()
 Forces the message to copy its content if there are more than one references to the content. More...
 
data_ptrvals ()
 Returns a mutable reference to the content. More...
 
void swap (message &other) noexcept
 Exchanges content of this and other.
 
void reset (raw_ptr new_ptr=nullptr, bool add_ref=true) noexcept
 Assigns new content.
 
message drop (size_t n) const
 Creates a new message with all but the first n values.
 
message drop_right (size_t n) const
 Creates a new message with all but the last n values.
 
message slice (size_t pos, size_t n) const
 Creates a new message of size n starting at the element at position p.
 
message extract (message_handler handler) const
 Filters this message by applying slices of it to handler and returns the remaining elements of this operation. More...
 
cli_res extract_opts (std::vector< cli_arg > xs, const help_factory &f=nullptr, bool no_help=false) const
 A simplistic interface for using extract to parse command line options. More...
 
const void * at (size_t p) const noexcept
 Returns a const pointer to the element at position p.
 
const data_ptrvals () const noexcept
 Returns a reference to the content.
 
const data_ptrcvals () const noexcept
 Returns a reference to the content.
 
uint32_t type_token () const noexcept
 Returns a type hint for the pattern matching engine.
 
bool shared () const noexcept
 Returns whether there are more than one references to the content.
 
size_t size () const noexcept
 Returns the size of this message.
 
message take (size_t n) const
 Creates a new message from the first n values.
 
message take_right (size_t n) const
 Creates a new message from the last n values.
 
bool empty () const
 Returns true if `size() == 0, otherwise false.
 
template<class T >
const T & get_as (size_t p) const
 Returns the value at position p as const reference of type T.
 
template<class T >
bool match_element (size_t p) const noexcept
 Queries whether the element at position p is of type T.
 
template<class... Ts>
bool match_elements () const noexcept
 Queries whether the types of this message are Ts....
 
std::pair< uint16_t, const std::type_info * > type (size_t pos) const noexcept
 Queries the run-time type information for the element at position pos.
 
bool match_element (size_t pos, uint16_t n, const std::type_info *p) const noexcept
 Checks whether the type of the stored value at position pos matches type number n and run-time type information p. More...
 
bool match_elements (detail::type_list<>) const noexcept
 
template<class T , class... Ts>
bool match_elements (detail::type_list< T, Ts... >) const noexcept
 

Static Public Member Functions

template<class... Ts>
static message concat (const Ts &...xs)
 Creates a new message by concatenating xs....
 
static message copy (const type_erased_tuple &xs)
 Creates a new message by copying all elements in a type-erased tuple.
 

Related Functions

(Note that these are not member functions.)

template<class T , class... Ts>
std::enable_if< !std::is_same< message, typename std::decay< T >::type >::value||(sizeof...(Ts) >) message::type make_message (T &&x, Ts &&...xs)
 Returns a new message containing the values (x, xs...).
 
message make_message (message other)
 Returns a copy of other.
 
message make_message ()
 Returns an empty message.
 
error inspect (serializer &sink, message &msg)
 
error inspect (deserializer &source, message &msg)
 
std::string to_string (const message &msg)
 
message operator+ (const message &lhs, const message &rhs)
 

Detailed Description

Describes a fixed-length, copy-on-write, type-erased tuple with elements of any type.

Member Function Documentation

message caf::message::extract ( message_handler  handler) const

Filters this message by applying slices of it to handler and returns the remaining elements of this operation.

Slices are generated in the sequence [0, size), [0, size-1), ... , [1, size-1), ..., [size-1, size). Whenever a slice matches, it is removed from the message and the next slice starts at the same index on the reduced message.

For example:

  • ~~~ auto msg = make_message(1, 2.f, 3.f, 4); // extract float and integer pairs auto msg2 = msg.extract({ [](float, float) { }, [](int, int) { } }); assert(msg2 == make_message(1, 4));
  • ~~~

    Step-by-step explanation:

    • Slice 1: (1, 2.f, 3.f, 4), no match
    • Slice 2: (1, 2.f, 3.f), no match
    • Slice 3: (1, 2.f), no match
    • Slice 4: (1), no match
    • Slice 5: (2.f, 3.f, 4), no match
    • Slice 6: (2.f, 3.f), match; new message is (1, 4)
    • Slice 7: (4), no match

    Slice 7 is (4), i.e., does not contain the first element, because the match on slice 6 occurred at index position 1. The function extract iterates a message only once, from left to right.

cli_res caf::message::extract_opts ( std::vector< cli_arg xs,
const help_factory f = nullptr,
bool  no_help = false 
) const

A simplistic interface for using extract to parse command line options.

Usage example:

  • ~~~ int main(int argc, char** argv) { uint16_t port; string host = "localhost"; auto res = message_builder(argv + 1, argv + argc).extract_opts({ {"port,p", "set port", port}, {"host,H", "set host (default: localhost)", host}, {"verbose,v", "enable verbose mode"} }); if (!res.error.empty()) { cerr << res.error << endl; return 1; } if (res.opts.count("help") > 0) { // CLI arguments contained "-h", "--help", or "-?" (builtin); cout << res.helptext << endl; return 0; } if (!res.remainder.empty()) { // ... extract did not consume all CLI arguments ... } if (res.opts.count("verbose") > 0) { // ... enable verbose mode ... } // ... }
  • ~~~
    Parameters
    xsList of argument descriptors.
    fOptional factory function to generate help text (overrides the default generator).
    no_helpSuppress generation of default-generated help option.
    Returns
    A struct containing remainder (i.e. unmatched elements), a set containing the names of all used arguments, and the generated help text.
    Exceptions
    std::invalid_argumentif no name or more than one long name is set
void caf::message::force_unshare ( )

Forces the message to copy its content if there are more than one references to the content.

bool caf::message::match_element ( size_t  pos,
uint16_t  n,
const std::type_info *  p 
) const
noexcept

Checks whether the type of the stored value at position pos matches type number n and run-time type information p.

data_ptr& caf::message::vals ( )

Returns a mutable reference to the content.

Callers are responsible for unsharing content if necessary.

Friends And Related Function Documentation

error inspect ( serializer sink,
message msg 
)
related
error inspect ( deserializer source,
message msg 
)
related
message operator+ ( const message lhs,
const message rhs 
)
related
std::string to_string ( const message msg)
related

The documentation for this class was generated from the following files: