caf::message_builder Class Reference

Provides a convenient interface for createing message objects from a series of values using the member function append. More...

#include <message_builder.hpp>

Public Member Functions
	message_builder (const message_builder &)=delete
message_builder &	operator= (const message_builder &)=delete
template<class Iter >
	message_builder (Iter first, Iter last)
	Creates a new instance and immediately calls append(first, last).
message_builder &	append (uniform_value what)
	Adds what to the elements of the buffer.
template<class Iter >
message_builder &	append (Iter first, Iter last)
	Appends all values in range [first, last).
template<class T >
message_builder &	append (T x)
	Adds x to the elements of the buffer.
message	to_message () const
	Converts the buffer to an actual message object without invalidating this message builder (nor clearing it). More...
message	move_to_message ()
	Converts the buffer to an actual message object and transfers ownership of the data to it, leaving this object in an invalid state. More...
message	extract (message_handler f) const
	Filters this message by applying slices of it to handler and returns the remaining elements of this operation. More...
message::cli_res	extract_opts (std::vector< message::cli_arg > xs, message::help_factory f=nullptr) const
	A simplistic interface for using extract to parse command line options. More...
optional< message >	apply (message_handler handler)
	Returns handler(*this). More...
void	clear ()
	Removes all elements from the buffer.
bool	empty () const
	Returns whether the buffer is empty.
size_t	size () const
	Returns the number of elements in the buffer.

Detailed Description

Provides a convenient interface for createing message objects from a series of values using the member function append.

Member Function Documentation

optional<message> caf::message_builder::apply

(

message_handler

handler

)

Returns handler(*this).

message caf::message_builder::extract

(

message_handler

f

)

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.

message::cli_res caf::message_builder::extract_opts	(	std::vector< message::cli_arg >	xs,
		message::help_factory	f = nullptr
	)		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

xs	List of argument descriptors.
f	Optional factory function to generate help text (overrides the default generator).

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_argument

if no name or more than one long name is set

message caf::message_builder::move_to_message

(

)

Converts the buffer to an actual message object and transfers ownership of the data to it, leaving this object in an invalid state.

Warning

Calling any member function on this object afterwards is undefined behavior (dereferencing a nullptr)

message caf::message_builder::to_message

(

)

const

Converts the buffer to an actual message object without invalidating this message builder (nor clearing it).

---

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

• libcaf_core/caf/message_builder.hpp