YARP
Yet Another Robot Platform
yarp::os::Bottle Class Reference

A simple collection of objects that can be described and transmitted in a portable way. More...

#include <yarp/os/Bottle.h>

+ Inheritance diagram for yarp::os::Bottle:

Detailed Description

A simple collection of objects that can be described and transmitted in a portable way.

Objects are stored in a list, which you can add to and access. It is handy to use until you feel the need to make your own more efficient formats for transmission.

Here's an example of using a Bottle:

/*
* Copyright (C) 2006-2019 Istituto Italiano di Tecnologia (IIT)
* Copyright (C) 2006-2010 RobotCub Consortium
* All rights reserved.
*
* This software may be modified and distributed under the terms of the
* BSD-3-Clause license. See the accompanying LICENSE file for details.
*/
#include <stdio.h>
#include <yarp/os/Bottle.h>
using namespace yarp::os;
int main() {
// create a bottle representing the list (5,"plus",2,"is")
Bottle b("5 plus 2 is");
// add an integer that is the sum of element 0 and 2
b.addInt32(b.get(0).asInt32()+b.get(2).asInt32());
// print the result -- "result: 5 plus 2 is 7"
printf("result: %s\n", b.toString().c_str());
return 0;
}

This class has a well-defined, documented representation in both binary and text form. The name of this class comes from the idea of throwing a "message in a bottle" into the network and hoping it will eventually wash ashore somewhere else. In the very early days of YARP, that is what communication felt like.

Examples:
bottle/main.cpp, carrier/carrier_stub.cpp, framerate/main.cpp, os/bottle_add.cpp, os/browse_bottle.cpp, os/buffered_port.cpp, os/database.cpp, os/make_count.cpp, os/simple_receiver.cpp, os/simple_sender.cpp, os/summer.cpp, os/view_count.cpp, port_power/ex0000_receiver.cpp, port_power/ex0001_sender.cpp, port_power/ex0100_receiver.cpp, port_power/ex0101_sender.cpp, port_power/ex0200_polling.cpp, port_power/ex0300_port_callback.cpp, port_power/ex0301_buffered_callback.cpp, port_power/ex0302_buffered_ext_callback.cpp, port_power/ex0400_expect_reply.cpp, port_power/ex0401_give_reply.cpp, port_power/ex0402_port_callback_reply.cpp, port_power/ex0403_bufferedport_callback_reply.cpp, and property/main.cpp.

Definition at line 72 of file Bottle.h.

Public Types

using size_type = size_t
 

Public Member Functions

 Bottle ()
 Constructor. More...
 
 Bottle (const std::string &text)
 Creates a bottle from a string. More...
 
 Bottle (const Bottle &rhs)
 Copy constructor. More...
 
 Bottle (std::initializer_list< yarp::os::Value > values)
 Initializer list constructor. More...
 
Bottleoperator= (const Bottle &bottle)
 Assignment operator. More...
 
virtual ~Bottle ()
 Destructor. More...
 
void clear ()
 Empties the bottle of any objects it contains. More...
 
void addInt (int x)
 Places an integer in the bottle, at the end of the list. More...
 
void addInt8 (std::int8_t x)
 Places a 8-bit integer in the bottle, at the end of the list. More...
 
void addInt16 (std::int16_t x)
 Places a 16-bit integer in the bottle, at the end of the list. More...
 
void addInt32 (std::int32_t x)
 Places a 32-bit integer in the bottle, at the end of the list. More...
 
void addInt64 (std::int64_t x)
 Places a 64-bit integer in the bottle, at the end of the list. More...
 
void addVocab (int x)
 Places a vocabulary item in the bottle, at the end of the list. More...
 
void addDouble (double x)
 Places a floating point number in the bottle, at the end of the list. More...
 
void addFloat32 (yarp::conf::float32_t x)
 Places a 32-bit floating point number in the bottle, at the end of the list. More...
 
void addFloat64 (yarp::conf::float64_t x)
 Places a 64-bit floating point number in the bottle, at the end of the list. More...
 
void addString (const char *str)
 Places a string in the bottle, at the end of the list. More...
 
void addString (const std::string &str)
 Places a string in the bottle, at the end of the list. More...
 
void add (const Value &value)
 Add a Value to the bottle, at the end of the list. More...
 
void add (Value *value)
 Add a Value to the bottle, at the end of the list. More...
 
BottleaddList ()
 Places an empty nested list in the bottle, at the end of the list. More...
 
PropertyaddDict ()
 Places an empty key/value object in the bottle, at the end of the list. More...
 
Value pop ()
 Removes a Value v from the end of the list and returns this value. More...
 
Valueget (size_type index) const
 Reads a Value v from a certain part of the list. More...
 
size_type size () const
 Gets the number of elements in the bottle. More...
 
void fromString (const std::string &text)
 Initializes bottle from a string. More...
 
void fromBinary (const char *buf, size_t len)
 Initializes bottle from a binary representation. More...
 
const char * toBinary (size_t *size=nullptr)
 Returns binary representation of bottle. More...
 
std::string toString () const override
 Gives a human-readable textual representation of the bottle. More...
 
bool write (ConnectionWriter &writer) const override
 Output a representation of the bottle to a network connection. More...
 
bool read (ConnectionReader &reader) override
 Set the bottle's value based on input from a network connection. More...
 
bool write (PortReader &reader, bool textMode=false)
 Copy the bottle's value to a object that can read a serialization. More...
 
bool read (const PortWriter &writer, bool textMode=false)
 Set the bottle's value based on input from a serializable object. More...
 
void onCommencement () const override
 This is called when the port is about to begin writing operations. More...
 
bool check (const std::string &key) const override
 Check if there exists a property of the given name. More...
 
Valuefind (const std::string &key) const override
 Gets a value corresponding to a given keyword. More...
 
BottlefindGroup (const std::string &key) const override
 Gets a list corresponding to a given keyword. More...
 
bool isNull () const override
 Checks if the object is invalid. More...
 
void copy (const Bottle &alt, size_type first=0, size_type len=npos)
 Copy all or part of another Bottle. More...
 
bool operator== (const Bottle &alt) const
 Equality test. More...
 
bool operator!= (const Bottle &alt) const
 Inequality test. More...
 
void append (const Bottle &alt)
 Append the content of the given bottle to the current list. More...
 
Bottle tail () const
 Get all but the first element of a bottle. More...
 
void hasChanged ()
 Declare that the content of the Bottle has been changed. More...
 
int getSpecialization ()
 Get numeric bottle code for this bottle. More...
 
- Public Member Functions inherited from yarp::os::Portable
virtual Type getType () const
 
- Public Member Functions inherited from yarp::os::PortReader
virtual ~PortReader ()
 Destructor. More...
 
virtual Type getReadType () const
 
- Public Member Functions inherited from yarp::os::PortWriter
virtual ~PortWriter ()
 Destructor. More...
 
virtual void onCompletion () const
 This is called when the port has finished all writing operations. More...
 
virtual yarp::os::Type getWriteType () const
 
- Public Member Functions inherited from yarp::os::Searchable
 Searchable ()
 Default constructor. More...
 
virtual ~Searchable ()
 Destructor. More...
 
virtual bool check (const std::string &key, const std::string &comment) const
 Check if there exists a property of the given name. More...
 
BottlefindGroup (const std::string &key, const std::string &comment) const
 Gets a list corresponding to a given keyword. More...
 
virtual bool check (const std::string &key, Value *&result, const std::string &comment="") const
 Gets a value corresponding to a given keyword. More...
 
virtual Value check (const std::string &key, const Value &fallback, const std::string &comment="") const
 Gets a value corresponding to a given keyword. More...
 

Static Public Member Functions

static BottlegetNullBottle ()
 A special Bottle with no content. More...
 
static std::string toString (int x)
 
static std::string describeBottleCode (int code)
 Convert a numeric bottle code to a string. More...
 
- Static Public Member Functions inherited from yarp::os::Portable
static bool copyPortable (PortWriter &writer, PortReader &reader)
 Copy one portable to another, via writing and reading. More...
 

Static Public Attributes

static const size_type npos = static_cast<Bottle::size_type>(-1)
 

Protected Member Functions

void setReadOnly (bool readOnly)
 

Friends

class yarp::os::NetworkBase
 

Member Typedef Documentation

◆ size_type

Definition at line 78 of file Bottle.h.

Constructor & Destructor Documentation

◆ Bottle() [1/4]

Bottle::Bottle ( )

Constructor.

The bottle is initially empty.

Definition at line 43 of file Bottle.cpp.

◆ Bottle() [2/4]

Bottle::Bottle ( const std::string &  text)
explicit

Creates a bottle from a string.

The string which should contain a textual form of the bottle, e.g. text = "10 -5.3 1.0 \"hello there"" would give a bottle with 4 elements: an integer, two floating point numbers, and a string.

Parameters
textthe textual form of the bottle to be interpreted.

Definition at line 53 of file Bottle.cpp.

◆ Bottle() [3/4]

Bottle::Bottle ( const Bottle rhs)

Copy constructor.

Parameters
bottleThe object to copy.

Definition at line 64 of file Bottle.cpp.

◆ Bottle() [4/4]

Bottle::Bottle ( std::initializer_list< yarp::os::Value values)

Initializer list constructor.

Parameters
[in]values,listof Value with which initialize the Bottle.

Definition at line 75 of file Bottle.cpp.

◆ ~Bottle()

Bottle::~Bottle ( )
virtual

Destructor.

Definition at line 98 of file Bottle.cpp.

Member Function Documentation

◆ add() [1/2]

void Bottle::add ( const Value value)

Add a Value to the bottle, at the end of the list.

Parameters
valuethe Value to add.
Examples:
os/database.cpp.

Definition at line 318 of file Bottle.cpp.

◆ add() [2/2]

void Bottle::add ( Value value)

Add a Value to the bottle, at the end of the list.

The object passed will be placed directly into the list, without copying. The Bottle will be responsible for deallocating it when appropriate.

Parameters
valuethe Value to add.

Definition at line 312 of file Bottle.cpp.

◆ addDict()

Property & Bottle::addDict ( )

Places an empty key/value object in the bottle, at the end of the list.

Returns
a reference to the newly added property.

Definition at line 170 of file Bottle.cpp.

◆ addDouble()

void yarp::os::Bottle::addDouble ( double  x)
inline

Places a floating point number in the bottle, at the end of the list.

Parameters
xthe number to add.
Warning
Unsafe, sizeof(double) is platform dependent. Use addFloat64 instead.

Definition at line 189 of file Bottle.h.

◆ addFloat32()

void Bottle::addFloat32 ( yarp::conf::float32_t  x)

Places a 32-bit floating point number in the bottle, at the end of the list.

Parameters
xthe number to add.

Definition at line 134 of file Bottle.cpp.

◆ addFloat64()

void Bottle::addFloat64 ( yarp::conf::float64_t  x)

Places a 64-bit floating point number in the bottle, at the end of the list.

Parameters
xthe number to add.
Examples:
os/summer.cpp.

Definition at line 140 of file Bottle.cpp.

◆ addInt()

void yarp::os::Bottle::addInt ( int  x)
inline

Places an integer in the bottle, at the end of the list.

Parameters
xthe integer to add.
Warning
Unsafe, sizeof(int) is platform dependent. Use addInt32 instead.

Definition at line 141 of file Bottle.h.

◆ addInt16()

void Bottle::addInt16 ( std::int16_t  x)

Places a 16-bit integer in the bottle, at the end of the list.

Parameters
xthe 16-bit integer to add.

Definition at line 116 of file Bottle.cpp.

◆ addInt32()

void Bottle::addInt32 ( std::int32_t  x)

Places a 32-bit integer in the bottle, at the end of the list.

Parameters
xthe 32-bit integer to add.
Examples:
os/bottle_add.cpp, os/make_count.cpp, os/simple_sender.cpp, port_power/ex0001_sender.cpp, port_power/ex0101_sender.cpp, and port_power/ex0400_expect_reply.cpp.

Definition at line 122 of file Bottle.cpp.

◆ addInt64()

void Bottle::addInt64 ( std::int64_t  x)

Places a 64-bit integer in the bottle, at the end of the list.

Parameters
xthe 64-bit integer to add.

Definition at line 128 of file Bottle.cpp.

◆ addInt8()

void Bottle::addInt8 ( std::int8_t  x)

Places a 8-bit integer in the bottle, at the end of the list.

Parameters
xthe 8-bit integer to add.

Definition at line 110 of file Bottle.cpp.

◆ addList()

Bottle & Bottle::addList ( )

Places an empty nested list in the bottle, at the end of the list.

The list itself is represented as a bottle.

Returns
a reference to the newly added list.
Examples:
bottle/main.cpp.

Definition at line 164 of file Bottle.cpp.

◆ addString() [1/2]

void Bottle::addString ( const char *  str)

◆ addString() [2/2]

void Bottle::addString ( const std::string &  str)

Places a string in the bottle, at the end of the list.

Parameters
strthe string to add.

Definition at line 158 of file Bottle.cpp.

◆ addVocab()

void Bottle::addVocab ( int  x)

Places a vocabulary item in the bottle, at the end of the list.

Parameters
xthe item to add.
Examples:
os/database.cpp.

Definition at line 146 of file Bottle.cpp.

◆ append()

void Bottle::append ( const Bottle alt)

Append the content of the given bottle to the current list.

Parameters
altthe content to add.
Examples:
port_power/ex0401_give_reply.cpp, port_power/ex0402_port_callback_reply.cpp, and port_power/ex0403_bufferedport_callback_reply.cpp.

Definition at line 362 of file Bottle.cpp.

◆ check()

bool Bottle::check ( const std::string &  key) const
overridevirtual

Check if there exists a property of the given name.

Parameters
keythe name to check for
Returns
true iff a property of the given name exists, even if it doesn't have a value associated with it

Implements yarp::os::Searchable.

Definition at line 259 of file Bottle.cpp.

◆ clear()

◆ copy()

void Bottle::copy ( const Bottle alt,
size_type  first = 0,
size_type  len = npos 
)

Copy all or part of another Bottle.

Parameters
altThe object to copy.
firstThe index of the first element to copy.
lenThe number of elements to copy (-1 for all).

Definition at line 248 of file Bottle.cpp.

◆ describeBottleCode()

std::string Bottle::describeBottleCode ( int  code)
static

Convert a numeric bottle code to a string.

Parameters
codethe code to convert
Returns
a string representation of the code's meaning

Definition at line 385 of file Bottle.cpp.

◆ find()

Value & Bottle::find ( const std::string &  key) const
overridevirtual

Gets a value corresponding to a given keyword.

Parameters
keyThe keyword to look for
Returns
A value corresponding to a given keyword. If there is no such value, then the isNull() method called on the result will be true. Otherwise, the value can be read by calling result.asInt32(), result.asString(), etc. as appropriate.

Implements yarp::os::Searchable.

Definition at line 269 of file Bottle.cpp.

◆ findGroup()

Bottle & Bottle::findGroup ( const std::string &  key) const
overridevirtual

Gets a list corresponding to a given keyword.

Parameters
keyThe keyword to look for
Returns
A list corresponding to a given keyword. If there is no such list, then the isNull() method called on the result will be true. Otherwise, the elements of the list can be read through result.get(index) where result.get(0) is the keyword, and result.get(i) for i>=1 are the "real" elements of the list.

Implements yarp::os::Searchable.

Examples:
property/main.cpp.

Definition at line 284 of file Bottle.cpp.

◆ fromBinary()

void Bottle::fromBinary ( const char *  buf,
size_t  len 
)

Initializes bottle from a binary representation.

Parameters
bufthe binary form of the bottle to be interpreted.
lenthe length of the binary form.

Definition at line 198 of file Bottle.cpp.

◆ fromString()

void Bottle::fromString ( const std::string &  text)

Initializes bottle from a string.

The string should contain a textual form of the bottle, e.g. text = "10 -5.3 1.0 \"hello there"" would give a bottle with 4 elements: an integer, two floating point numbers, and a string.

Parameters
textthe textual form of the bottle to be interpreted.
Examples:
carrier/carrier_stub.cpp, os/buffered_port.cpp, and os/portable_pair.cpp.

Definition at line 186 of file Bottle.cpp.

◆ get()

Value & Bottle::get ( size_type  index) const

Reads a Value v from a certain part of the list.

Methods like v.isInt32() or v.isString() can be used to check the type of the result. Methods like v.asInt32() or v.asString() can be used to access the result as a particular type.

Parameters
indexthe part of the list to read from.
Returns
the Value v; if the index lies outside the range of elements present, then v.isNull() will be true.
Examples:
os/bottle_add.cpp, os/browse_bottle.cpp, os/database.cpp, os/summer.cpp, os/view_count.cpp, and property/main.cpp.

Definition at line 228 of file Bottle.cpp.

◆ getNullBottle()

Bottle & Bottle::getNullBottle ( )
static

A special Bottle with no content.

Returns
the special invalid "null" Bottle.

Definition at line 324 of file Bottle.cpp.

◆ getSpecialization()

int Bottle::getSpecialization ( )

Get numeric bottle code for this bottle.

Returns
the numeric code

Definition at line 243 of file Bottle.cpp.

◆ hasChanged()

void Bottle::hasChanged ( )

Declare that the content of the Bottle has been changed.

It is important to call this if you modify an individual element of the Bottle through assignment, so that serialization happens correctly.

Definition at line 238 of file Bottle.cpp.

◆ isNull()

bool Bottle::isNull ( ) const
overridevirtual

Checks if the object is invalid.

Returns
True if the object is invalid or "null".

Reimplemented from yarp::os::Searchable.

Reimplemented in NullBottle.

Definition at line 352 of file Bottle.cpp.

◆ onCommencement()

void Bottle::onCommencement ( ) const
overridevirtual

This is called when the port is about to begin writing operations.

After this point, the write method may be called zero, once, or many times by YARP depending on the mix of formats and protocols in use.

Reimplemented from yarp::os::PortWriter.

Definition at line 217 of file Bottle.cpp.

◆ operator!=()

bool Bottle::operator!= ( const Bottle alt) const

Inequality test.

Parameters
altthe value to compare against.
Returns
true iff the values are not equal.

Definition at line 357 of file Bottle.cpp.

◆ operator=()

Bottle & Bottle::operator= ( const Bottle bottle)

Assignment operator.

Parameters
bottleThe object to copy.
Returns
the Bottle itself.

Definition at line 89 of file Bottle.cpp.

◆ operator==()

bool Bottle::operator== ( const Bottle alt) const

Equality test.

Parameters
altthe value to compare against.
Returns
true iff the values are equal.

Definition at line 330 of file Bottle.cpp.

◆ pop()

Value Bottle::pop ( )

Removes a Value v from the end of the list and returns this value.

Returns
the value popped from the end of the bottle.

Definition at line 176 of file Bottle.cpp.

◆ read() [1/2]

bool Bottle::read ( ConnectionReader reader)
overridevirtual

Set the bottle's value based on input from a network connection.

Parameters
readerthe interface to the network connection for reading
Returns
true iff the bottle was read successfully.

Implements yarp::os::Portable.

Examples:
port_power/ex0300_port_callback.cpp, port_power/ex0402_port_callback_reply.cpp, and port_power/ex0403_bufferedport_callback_reply.cpp.

Definition at line 222 of file Bottle.cpp.

◆ read() [2/2]

bool Bottle::read ( const PortWriter writer,
bool  textMode = false 
)

Set the bottle's value based on input from a serializable object.

Must be serialized in standard Bottle-compatible format.

Parameters
writerthe serializable object.
textModetrue if text serialization should be used.
Returns
true iff the bottle was read successfully.

Definition at line 343 of file Bottle.cpp.

◆ setReadOnly()

void Bottle::setReadOnly ( bool  readOnly)
protected

Definition at line 421 of file Bottle.cpp.

◆ size()

size_t Bottle::size ( ) const

Gets the number of elements in the bottle.

Returns
number of elements in the bottle.
Examples:
framerate/main.cpp, os/browse_bottle.cpp, os/summer.cpp, port_power/ex0400_expect_reply.cpp, and property/main.cpp.

Definition at line 233 of file Bottle.cpp.

◆ tail()

Bottle Bottle::tail ( ) const

Get all but the first element of a bottle.

Returns
a bottle containing all but the first element of the current bottle.

Definition at line 370 of file Bottle.cpp.

◆ toBinary()

const char * Bottle::toBinary ( size_t *  size = nullptr)

Returns binary representation of bottle.

Lifetime is until next modification of bottle.

Parameters
sizeif non-null, the referenced variable is set to the buffer size.
Returns
pointer to a buffer holding the binary representation of the bottle.

Definition at line 204 of file Bottle.cpp.

◆ toString() [1/2]

◆ toString() [2/2]

std::string Bottle::toString ( int  x)
static

Definition at line 380 of file Bottle.cpp.

◆ write() [1/2]

bool Bottle::write ( ConnectionWriter writer) const
overridevirtual

Output a representation of the bottle to a network connection.

Parameters
writerthe interface to the network connection for writing
Returns
true iff the representation was written successfully.

Implements yarp::os::Portable.

Examples:
port_power/ex0402_port_callback_reply.cpp, and port_power/ex0403_bufferedport_callback_reply.cpp.

Definition at line 212 of file Bottle.cpp.

◆ write() [2/2]

bool Bottle::write ( PortReader reader,
bool  textMode = false 
)

Copy the bottle's value to a object that can read a serialization.

Must be serialized in standard Bottle-compatible format.

Parameters
readerthe serializable object.
textModetrue if text serialization should be used.
Returns
true iff the bottle was written successfully.

Definition at line 335 of file Bottle.cpp.

Friends And Related Function Documentation

◆ yarp::os::NetworkBase

friend class yarp::os::NetworkBase
friend

Definition at line 461 of file Bottle.h.

Member Data Documentation

◆ npos

const Bottle::size_type Bottle::npos = static_cast<Bottle::size_type>(-1)
static

Definition at line 81 of file Bottle.h.


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