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-2018 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 70 of file Bottle.h.

Public Member Functions

 Bottle ()
 Constructor. More...
 
 Bottle (const std::string &text)
 Creates a bottle from a string. More...
 
 Bottle (const Bottle &bottle)
 Copy 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_t index) const
 Reads a Value v from a certain part of the list. More...
 
size_t 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...
 
virtual bool check (const std::string &key) const override
 Check if there exists a property of the given name. More...
 
virtual 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...
 
virtual bool isNull () const override
 Checks if the object is invalid. More...
 
void copy (const Bottle &alt, int first=0, int len=-1)
 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...
 

Protected Member Functions

void setReadOnly (bool readOnly)
 

Private Attributes

yarp::os::impl::BottleImpl *const implementation
 

Friends

class yarp::os::NetworkBase
 
class yarp::os::impl::Storable
 
class yarp::os::impl::StoreList
 
class yarp::os::impl::BottleImpl
 

Constructor & Destructor Documentation

◆ Bottle() [1/3]

Bottle::Bottle ( )

Constructor.

The bottle is initially empty.

Definition at line 40 of file Bottle.cpp.

◆ Bottle() [2/3]

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 48 of file Bottle.cpp.

◆ Bottle() [3/3]

Bottle::Bottle ( const Bottle bottle)

Copy constructor.

Parameters
bottleThe object to copy.

Definition at line 57 of file Bottle.cpp.

◆ ~Bottle()

Bottle::~Bottle ( )
virtual

Destructor.

Definition at line 73 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 295 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 289 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 147 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 170 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 111 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 117 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 125 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 93 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 99 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 105 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 87 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 141 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 135 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 123 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 339 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 236 of file Bottle.cpp.

◆ clear()

◆ copy()

void Bottle::copy ( const Bottle alt,
int  first = 0,
int  len = -1 
)

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 225 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 362 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 246 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 261 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 175 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 163 of file Bottle.cpp.

◆ get()

Value & Bottle::get ( size_t  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 205 of file Bottle.cpp.

◆ getNullBottle()

Bottle & Bottle::getNullBottle ( )
static

A special Bottle with no content.

Returns
the special invalid "null" Bottle.

Definition at line 301 of file Bottle.cpp.

◆ getSpecialization()

int Bottle::getSpecialization ( )

Get numeric bottle code for this bottle.

Returns
the numeric code

Definition at line 220 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 215 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 329 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 194 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 334 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 66 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 307 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 153 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 199 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 320 of file Bottle.cpp.

◆ setReadOnly()

void Bottle::setReadOnly ( bool  readOnly)
protected

Definition at line 398 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 210 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 347 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 181 of file Bottle.cpp.

◆ toString() [1/2]

◆ toString() [2/2]

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

Definition at line 357 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 189 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 312 of file Bottle.cpp.

Friends And Related Function Documentation

◆ yarp::os::impl::BottleImpl

friend class yarp::os::impl::BottleImpl
friend

Definition at line 442 of file Bottle.h.

◆ yarp::os::impl::Storable

friend class yarp::os::impl::Storable
friend

Definition at line 440 of file Bottle.h.

◆ yarp::os::impl::StoreList

friend class yarp::os::impl::StoreList
friend

Definition at line 441 of file Bottle.h.

◆ yarp::os::NetworkBase

friend class yarp::os::NetworkBase
friend

Definition at line 439 of file Bottle.h.

Member Data Documentation

◆ implementation

yarp::os::impl::BottleImpl* const yarp::os::Bottle::implementation
private

Definition at line 443 of file Bottle.h.


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