YARP  2.3.70.2
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:

Public Member Functions

 Bottle ()
 Constructor. More...
 
 Bottle (const ConstString &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 addInt64 (const YARP_INT64 &x)
 Places a 64 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 addString (const char *str)
 Places a string in the bottle, at the end of the list. More...
 
void addString (const ConstString &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 (int index) const
 Reads a Value v from a certain part of the list. More...
 
int size () const
 Gets the number of elements in the bottle. More...
 
void fromString (const ConstString &text)
 Initializes bottle from a string. More...
 
void fromBinary (const char *buf, int len)
 Initializes bottle from a binary representation. More...
 
const char * toBinary (size_t *size=YARP_NULLPTR)
 Returns binary representation of bottle. More...
 
ConstString toString () const YARP_OVERRIDE
 Gives a human-readable textual representation of the bottle. More...
 
bool write (ConnectionWriter &writer) YARP_OVERRIDE
 Output a representation of the bottle to a network connection. More...
 
bool read (ConnectionReader &reader) YARP_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 (PortWriter &writer, bool textMode=false)
 Set the bottle's value based on input from a serializable object. More...
 
void onCommencement () YARP_OVERRIDE
 This is called when the port is about to begin writing operations. More...
 
virtual bool check (const ConstString &key) const YARP_OVERRIDE
 Check if there exists a property of the given name. More...
 
virtual Valuefind (const ConstString &key) const YARP_OVERRIDE
 Gets a value corresponding to a given keyword. More...
 
BottlefindGroup (const ConstString &key) const YARP_OVERRIDE
 Gets a list corresponding to a given keyword. More...
 
virtual bool isNull () const YARP_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)
 Equality test. More...
 
bool operator!= (const Bottle &alt)
 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...
 
YARP_DEPRECATED void add (const char *txt)
 
- Public Member Functions inherited from yarp::os::Portable
virtual Type getType ()
 
- Public Member Functions inherited from yarp::os::PortReader
virtual ~PortReader ()
 Destructor. More...
 
virtual Type getReadType ()
 
- Public Member Functions inherited from yarp::os::PortWriter
virtual ~PortWriter ()
 Destructor. More...
 
virtual void onCompletion ()
 This is called when the port has finished all writing operations. More...
 
virtual Type getWriteType ()
 
- Public Member Functions inherited from yarp::os::Searchable
 Searchable ()
 Default constructor. More...
 
virtual ~Searchable ()
 Destructor. More...
 
virtual bool check (const ConstString &key, const ConstString &comment) const
 Check if there exists a property of the given name. More...
 
BottlefindGroup (const ConstString &key, const ConstString &comment) const
 Gets a list corresponding to a given keyword. More...
 
virtual bool check (const ConstString &key, Value *&result, const ConstString &comment="") const
 Gets a value corresponding to a given keyword. More...
 
virtual Value check (const ConstString &key, const Value &fallback, const ConstString &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 ConstString toString (int x)
 
static ConstString 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)
 

Static Private Member Functions

static void fini ()
 

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
 

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) 2010 RobotCub Consortium
* Author: Paul Fitzpatrick
* CopyPolicy: Released under the terms of the LGPLv2.1 or later, see LGPL.TXT
*/
#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.addInt(b.get(0).asInt()+b.get(2).asInt());
// 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 57 of file Bottle.h.

Constructor & Destructor Documentation

◆ Bottle() [1/3]

Bottle::Bottle ( )

Constructor.

The bottle is initially empty.

Definition at line 34 of file Bottle.cpp.

◆ Bottle() [2/3]

Bottle::Bottle ( const ConstString 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 42 of file Bottle.cpp.

◆ Bottle() [3/3]

Bottle::Bottle ( const Bottle bottle)

Copy constructor.

Parameters
bottleThe object to copy.

Definition at line 51 of file Bottle.cpp.

◆ ~Bottle()

Bottle::~Bottle ( )
virtual

Destructor.

Definition at line 67 of file Bottle.cpp.

Member Function Documentation

◆ add() [1/3]

void Bottle::add ( const Value value)

◆ add() [2/3]

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

◆ add() [3/3]

void Bottle::add ( const char *  txt)
Deprecated:
since YARP 2.3.65

Definition at line 391 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 123 of file Bottle.cpp.

◆ addDouble()

void Bottle::addDouble ( double  x)

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

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

Definition at line 99 of file Bottle.cpp.

◆ addInt()

void Bottle::addInt ( int  x)

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

Parameters
xthe integer to add.
Examples:
os/bottle_add.cpp, os/make_count.cpp, and os/simple_sender.cpp.

Definition at line 81 of file Bottle.cpp.

◆ addInt64()

void Bottle::addInt64 ( const YARP_INT64 &  x)

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

Parameters
xthe 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 117 of file Bottle.cpp.

◆ addString() [1/2]

void Bottle::addString ( const char *  str)

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

Parameters
strthe string to add.
Examples:
bottle/main.cpp, os/make_count.cpp, os/simple_sender.cpp, and os/summer.cpp.

Definition at line 105 of file Bottle.cpp.

◆ addString() [2/2]

void Bottle::addString ( const ConstString str)

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

Parameters
strthe string to add.

Definition at line 111 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 93 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 325 of file Bottle.cpp.

◆ check()

bool Bottle::check ( const ConstString key) const
virtual

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

◆ describeBottleCode()

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

◆ find()

Value & Bottle::find ( const ConstString key) const
virtual

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.asInt(), result.asString(), etc. as appropriate.

Implements yarp::os::Searchable.

Definition at line 222 of file Bottle.cpp.

◆ findGroup()

Bottle & Bottle::findGroup ( const ConstString key) const
virtual

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

◆ fini()

void Bottle::fini ( )
staticprivate

Definition at line 285 of file Bottle.cpp.

◆ fromBinary()

void Bottle::fromBinary ( const char *  buf,
int  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 151 of file Bottle.cpp.

◆ fromString()

void Bottle::fromString ( const ConstString 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 139 of file Bottle.cpp.

◆ get()

Value & Bottle::get ( int  index) const

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

Methods like v.isInt() or v.isString() can be used to check the type of the result. Methods like v.asInt() 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 181 of file Bottle.cpp.

◆ getNullBottle()

Bottle & Bottle::getNullBottle ( )
static

A special Bottle with no content.

Returns
the special invalid "null" Bottle.

Definition at line 277 of file Bottle.cpp.

◆ getSpecialization()

int Bottle::getSpecialization ( )

Get numeric bottle code for this bottle.

Returns
the numeric code

Definition at line 196 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 191 of file Bottle.cpp.

◆ isNull()

bool Bottle::isNull ( ) const
virtual

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

◆ onCommencement()

void Bottle::onCommencement ( )
virtual

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

◆ operator!=()

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

Inequality test.

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

Definition at line 320 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 60 of file Bottle.cpp.

◆ operator==()

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

Equality test.

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

Definition at line 293 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 129 of file Bottle.cpp.

◆ read() [1/2]

bool Bottle::read ( ConnectionReader reader)
virtual

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

◆ read() [2/2]

bool Bottle::read ( 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 306 of file Bottle.cpp.

◆ setReadOnly()

void Bottle::setReadOnly ( bool  readOnly)
protected

Definition at line 384 of file Bottle.cpp.

◆ size()

int 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 186 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 333 of file Bottle.cpp.

◆ toBinary()

const char * Bottle::toBinary ( size_t *  size = YARP_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 157 of file Bottle.cpp.

◆ toString() [1/2]

◆ toString() [2/2]

ConstString Bottle::toString ( int  x)
static

Definition at line 343 of file Bottle.cpp.

◆ write() [1/2]

bool Bottle::write ( ConnectionWriter writer)
virtual

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

Friends And Related Function Documentation

◆ yarp::os::impl::BottleImpl

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

Definition at line 396 of file Bottle.h.

◆ yarp::os::impl::Storable

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

Definition at line 394 of file Bottle.h.

◆ yarp::os::impl::StoreList

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

Definition at line 395 of file Bottle.h.

◆ yarp::os::NetworkBase

friend class yarp::os::NetworkBase
friend

Definition at line 393 of file Bottle.h.

Member Data Documentation

◆ implementation

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

Definition at line 397 of file Bottle.h.


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