protozero::pbf_writer Class Reference

`#include <pbf_writer.hpp>`

Inheritance diagram for protozero::pbf_writer:
[legend]

## Public Member Functions

| pbf_writer (std::string &data) noexcept
| pbf_writer () noexcept=default
| pbf_writer (pbf_writer &parent_writer, pbf_tag_type tag, std::size_t size=0)
| pbf_writer (const pbf_writer &)=delete
| A pbf_writer object can not be copied.
pbf_writer & | operator= (const pbf_writer &)=delete
| A pbf_writer object can not be copied.
| pbf_writer (pbf_writer &&other) noexcept
pbf_writer & | operator= (pbf_writer &&other) noexcept
bool | valid () const noexcept
void | swap (pbf_writer &other) noexcept
void | reserve (std::size_t size)
void | commit ()
void | rollback ()
Scalar field writer functions
void | add_bool (pbf_tag_type tag, bool value)
void | add_enum (pbf_tag_type tag, int32_t value)
void | add_int32 (pbf_tag_type tag, int32_t value)
void | add_sint32 (pbf_tag_type tag, int32_t value)
void | add_uint32 (pbf_tag_type tag, uint32_t value)
void | add_int64 (pbf_tag_type tag, int64_t value)
void | add_sint64 (pbf_tag_type tag, int64_t value)
void | add_uint64 (pbf_tag_type tag, uint64_t value)
void | add_fixed32 (pbf_tag_type tag, uint32_t value)
void | add_sfixed32 (pbf_tag_type tag, int32_t value)
void | add_fixed64 (pbf_tag_type tag, uint64_t value)
void | add_sfixed64 (pbf_tag_type tag, int64_t value)
void | add_float (pbf_tag_type tag, float value)
void | add_double (pbf_tag_type tag, double value)
void | add_bytes (pbf_tag_type tag, const char *value, std::size_t size)
void | add_bytes (pbf_tag_type tag, const data_view &value)
void | add_bytes (pbf_tag_type tag, const std::string &value)
void | add_bytes (pbf_tag_type tag, const char *value)
template<typename... Ts>
void | add_bytes_vectored (pbf_tag_type tag, Ts &&... values)
void | add_string (pbf_tag_type tag, const char *value, std::size_t size)
void | add_string (pbf_tag_type tag, const data_view &value)
void | add_string (pbf_tag_type tag, const std::string &value)
void | add_string (pbf_tag_type tag, const char *value)
void | add_message (pbf_tag_type tag, const char *value, std::size_t size)
void | add_message (pbf_tag_type tag, const data_view &value)
void | add_message (pbf_tag_type tag, const std::string &value)
Repeated packed field writer functions
template<typename InputIterator >
void | add_packed_bool (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_enum (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_int32 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_sint32 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_uint32 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_int64 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_sint64 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_uint64 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_fixed32 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_sfixed32 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_fixed64 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_sfixed64 (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_float (pbf_tag_type tag, InputIterator first, InputIterator last)
template<typename InputIterator >
void | add_packed_double (pbf_tag_type tag, InputIterator first, InputIterator last)

## Friends

template<typename T >
class | detail::packed_field_varint
template<typename T >
class | detail::packed_field_svarint
template<typename T >
class | detail::packed_field_fixed

## Detailed Description

The pbf_writer is used to write PBF formatted messages into a buffer.

Almost all methods in this class can throw an std::bad_alloc exception if the std::string used as a buffer wants to resize.

## Constructor & Destructor Documentation

## pbf_writer() [1/4]

protozero::pbf_writer::pbf_writer | ( | std::string & | data | ) |

inline explicit noexcept

Create a writer using the given string as a data store. The pbf_writer stores a reference to that string and adds all data to it. The string doesn't have to be empty. The pbf_writer will just append data.

## pbf_writer() [2/4]

protozero::pbf_writer::pbf_writer | ( |  | ) |

default noexcept

Create a writer without a data store. In this form the writer can not be used!

## pbf_writer() [3/4]

protozero::pbf_writer::pbf_writer | ( | pbf_writer & | parent_writer,
|  | pbf_tag_type | tag,
|  | std::size_t | size = `0`
| ) |  |

inline

Construct a pbf_writer for a submessage from the pbf_writer of the parent message.

Parameters

  parent_writer | The pbf_writer
  tag | Tag (field number) of the field that will be written
  size | Optional size of the submessage in bytes (use 0 for unknown). Setting this allows some optimizations but is only possible in a few very specific cases.

## pbf_writer() [4/4]

protozero::pbf_writer::pbf_writer | ( | pbf_writer && | other | ) |

inline noexcept

A pbf_writer object can be moved. After this the other pbf_writer will be invalid.

## Member Function Documentation

## add_bool()

void protozero::pbf_writer::add_bool | ( | pbf_tag_type | tag,
|  | bool | value
| ) |  |

inline

Add "bool" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_bytes() [1/4]

void protozero::pbf_writer::add_bytes | ( | pbf_tag_type | tag,
|  | const char * | value,
|  | std::size_t | size
| ) |  |

inline

Add "bytes" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Pointer to value to be written
  size | Number of bytes to be written

## add_bytes() [2/4]

void protozero::pbf_writer::add_bytes | ( | pbf_tag_type | tag,
|  | const data_view & | value
| ) |  |

inline

Add "bytes" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_bytes() [3/4]

void protozero::pbf_writer::add_bytes | ( | pbf_tag_type | tag,
|  | const std::string & | value
| ) |  |

inline

Add "bytes" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_bytes() [4/4]

void protozero::pbf_writer::add_bytes | ( | pbf_tag_type | tag,
|  | const char * | value
| ) |  |

inline

Add "bytes" field to data. Bytes from the value are written until a null byte is encountered. The null byte is not added.

Parameters

  tag | Tag (field number) of the field
  value | Pointer to zero-delimited value to be written

## add_bytes_vectored()

template<typename... Ts>

void protozero::pbf_writer::add_bytes_vectored | ( | pbf_tag_type | tag,
|  | Ts &&... | values
| ) |  |

inline

Add "bytes" field to data using vectored input. All the data in the 2nd and further arguments is "concatenated" with only a single copy into the final buffer.

This will work with objects of any type supporting the data() and size() methods like std::string or protozero::data_view.

Example:

std::string data1 = "abc";
std::string data2 = "xyz";
writer.add_bytes_vectored(1, data1, data2);

Template Parameters

  Ts | List of types supporting data() and size() methods.

Parameters

  tag | Tag (field number) of the field
  values | List of objects of types Ts with data to be appended.

## add_double()

void protozero::pbf_writer::add_double | ( | pbf_tag_type | tag,
|  | double | value
| ) |  |

inline

Add "double" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_enum()

void protozero::pbf_writer::add_enum | ( | pbf_tag_type | tag,
|  | int32_t | value
| ) |  |

inline

Add "enum" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_fixed32()

void protozero::pbf_writer::add_fixed32 | ( | pbf_tag_type | tag,
|  | uint32_t | value
| ) |  |

inline

Add "fixed32" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_fixed64()

void protozero::pbf_writer::add_fixed64 | ( | pbf_tag_type | tag,
|  | uint64_t | value
| ) |  |

inline

Add "fixed64" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_float()

void protozero::pbf_writer::add_float | ( | pbf_tag_type | tag,
|  | float | value
| ) |  |

inline

Add "float" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_int32()

void protozero::pbf_writer::add_int32 | ( | pbf_tag_type | tag,
|  | int32_t | value
| ) |  |

inline

Add "int32" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_int64()

void protozero::pbf_writer::add_int64 | ( | pbf_tag_type | tag,
|  | int64_t | value
| ) |  |

inline

Add "int64" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_message() [1/3]

void protozero::pbf_writer::add_message | ( | pbf_tag_type | tag,
|  | const char * | value,
|  | std::size_t | size
| ) |  |

inline

Add "message" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Pointer to message to be written
  size | Length of the message

## add_message() [2/3]

void protozero::pbf_writer::add_message | ( | pbf_tag_type | tag,
|  | const data_view & | value
| ) |  |

inline

Add "message" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written. The value must be a complete message.

## add_message() [3/3]

void protozero::pbf_writer::add_message | ( | pbf_tag_type | tag,
|  | const std::string & | value
| ) |  |

inline

Add "message" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written. The value must be a complete message.

## add_packed_bool()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_bool | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed bool" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to bool.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_double()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_double | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed double" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to double.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_enum()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_enum | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed enum" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_fixed32()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_fixed32 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed fixed32" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to uint32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_fixed64()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_fixed64 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed fixed64" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to uint64_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_float()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_float | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed float" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to float.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_int32()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_int32 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed int32" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_int64()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_int64 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed int64" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int64_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_sfixed32()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_sfixed32 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed sfixed32" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_sfixed64()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_sfixed64 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed sfixed64" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int64_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_sint32()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_sint32 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed sint32" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_sint64()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_sint64 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed sint64" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to int64_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_uint32()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_uint32 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed uint32" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to uint32_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_packed_uint64()

template<typename InputIterator >

void protozero::pbf_writer::add_packed_uint64 | ( | pbf_tag_type | tag,
|  | InputIterator | first,
|  | InputIterator | last
| ) |  |

inline

Add "repeated packed uint64" field to data.

Template Parameters

  InputIterator | A type satisfying the InputIterator concept. Dereferencing the iterator must yield a type assignable to uint64_t.

Parameters

  tag | Tag (field number) of the field
  first | Iterator pointing to the beginning of the data
  last | Iterator pointing one past the end of data

## add_sfixed32()

void protozero::pbf_writer::add_sfixed32 | ( | pbf_tag_type | tag,
|  | int32_t | value
| ) |  |

inline

Add "sfixed32" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_sfixed64()

void protozero::pbf_writer::add_sfixed64 | ( | pbf_tag_type | tag,
|  | int64_t | value
| ) |  |

inline

Add "sfixed64" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_sint32()

void protozero::pbf_writer::add_sint32 | ( | pbf_tag_type | tag,
|  | int32_t | value
| ) |  |

inline

Add "sint32" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_sint64()

void protozero::pbf_writer::add_sint64 | ( | pbf_tag_type | tag,
|  | int64_t | value
| ) |  |

inline

Add "sint64" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_string() [1/4]

void protozero::pbf_writer::add_string | ( | pbf_tag_type | tag,
|  | const char * | value,
|  | std::size_t | size
| ) |  |

inline

Add "string" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Pointer to value to be written
  size | Number of bytes to be written

## add_string() [2/4]

void protozero::pbf_writer::add_string | ( | pbf_tag_type | tag,
|  | const data_view & | value
| ) |  |

inline

Add "string" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_string() [3/4]

void protozero::pbf_writer::add_string | ( | pbf_tag_type | tag,
|  | const std::string & | value
| ) |  |

inline

Add "string" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_string() [4/4]

void protozero::pbf_writer::add_string | ( | pbf_tag_type | tag,
|  | const char * | value
| ) |  |

inline

Add "string" field to data. Bytes from the value are written until a null byte is encountered. The null byte is not added.

Parameters

  tag | Tag (field number) of the field
  value | Pointer to value to be written

## add_uint32()

void protozero::pbf_writer::add_uint32 | ( | pbf_tag_type | tag,
|  | uint32_t | value
| ) |  |

inline

Add "uint32" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## add_uint64()

void protozero::pbf_writer::add_uint64 | ( | pbf_tag_type | tag,
|  | uint64_t | value
| ) |  |

inline

Add "uint64" field to data.

Parameters

  tag | Tag (field number) of the field
  value | Value to be written

## commit()

void protozero::pbf_writer::commit | ( |  | ) |

inline

Commit this submessage. This does the same as when the pbf_writer goes out of scope and is destructed.

Precondition
  Must be a pbf_writer of a submessage, ie one opened with the pbf_writer constructor taking a parent message.

Postcondition
  The pbf_writer is invalid and can't be used any more.

## operator=()

pbf_writer& protozero::pbf_writer::operator= | ( | pbf_writer && | other | ) |

inline noexcept

A pbf_writer object can be moved. After this the other pbf_writer will be invalid.

## reserve()

void protozero::pbf_writer::reserve | ( | std::size_t | size | ) |

inline

Reserve size bytes in the underlying message store in addition to whatever the message store already holds. So unlike the `std::string::reserve()` method this is not an absolute size, but additional memory that should be reserved.

Parameters

  size | Number of bytes to reserve in underlying message store.

## rollback()

void protozero::pbf_writer::rollback | ( |  | ) |

inline

Cancel writing of this submessage. The complete submessage will be removed as if it was never created and no fields were added.

Precondition
  Must be a pbf_writer of a submessage, ie one opened with the pbf_writer constructor taking a parent message.

Postcondition
  The pbf_writer is invalid and can't be used any more.

## swap()

void protozero::pbf_writer::swap | ( | pbf_writer & | other | ) |

inline noexcept

Swap the contents of this object with the other.

Parameters

  other | Other object to swap data with.

## valid()

bool protozero::pbf_writer::valid | ( |  | ) | const

inline noexcept

Check if this writer is valid. A writer is invalid if it was default constructed, moved from, or if commit() has been called on it. Otherwise it is valid.

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

- include/protozero/pbf_writer.hpp