aGrUM  0.13.2
gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler Class Reference

the (unsafe) handler for the tabular databases More...

#include <agrum/learning/IDatabaseTable.h>

+ Inheritance diagram for gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler:
+ Collaboration diagram for gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler:

Public Member Functions

Constructors / Destructors
 Handler (const IDatabaseTable< T_DATA, ALLOC > &db)
 default constructor More...
 
 Handler (const Handler &h)
 copy constructor More...
 
 Handler (Handler &&h)
 move constructor More...
 
virtual ~Handler ()
 destructor More...
 
Operators
virtual Handleroperator= (const Handler &)
 copy operator More...
 
virtual Handleroperator= (Handler &&)
 move operator More...
 
virtual Handleroperator++ () final
 makes the operator point to the next row in the database More...
 
virtual Handleroperator-- () final
 makes the operator point to the previous row in the database More...
 
virtual Handleroperator+= (unsigned int i) final
 advances the handler by i rows in the database More...
 
virtual Handleroperator-= (unsigned int i) final
 moves back the handler by i rows in the database More...
 
virtual bool operator== (const Handler &handler) const final
 checks whether two handlers point to the same row in the database More...
 
virtual bool operator!= (const Handler &handler) const final
 checks whether two handlers point to different rows in the database More...
 
virtual const_reference operator* () const final
 returns the current row pointed to by the handler (unsafe version) More...
 
virtual const_pointer operator-> () const final
 Dereferences the value pointed to by the handler (unsafe version) More...
 
Accessors / Modifiers
virtual std::size_t size () const final
 returns the number of rows managed by the handler More...
 
virtual std::size_t DBSize () const final
 returns the number of rows of the whole database More...
 
virtual const_reference rowSafe () const final
 returns the current row pointed to by the handler (safe version) More...
 
virtual reference rowSafe () final
 returns the current row pointed to by the handler (safe version) More...
 
virtual const_reference row () const final
 returns the current row pointed to by the handler (unsafe version) More...
 
virtual reference row () final
 returns the current row pointed to by the handler (unsafe version) More...
 
virtual void nextRow () final
 makes the handler point to the next row, equivalent to operator++ More...
 
virtual std::size_t numRow () const final
 the number of the current row (0 = the 1st row managed by the handler) More...
 
virtual bool hasRows () const final
 indicates whether the handler has reached its end or not More...
 
virtual void reset () final
 puts the handler to the beginning of the database's area it handles More...
 
virtual Handler begin () const
 returns a new handler that points to the beginning of the database's area of the current handler More...
 
virtual Handler end () const
 returns a new handler that points to the end of the database's area of the current handler More...
 
virtual void setRange (std::size_t begin, std::size_t end) final
 sets the area in the database the handler will handle More...
 
virtual std::pair< std::size_t, std::size_t > range () const final
 returns the current range of the handler [begin,end) More...
 
virtual const DBVector< std::string > & variableNames () const final
 returns the names of the variables More...
 
virtual std::size_t nbVariables () const final
 returns the number of variables (columns) of the database More...
 

Public Types

template<typename TX_DATA >
using DBVector = std::vector< TX_DATA, ALLOC< TX_DATA > >
 
template<typename TX_DATA >
using Row = DBRow< TX_DATA, ALLOC >
 
template<typename TX_DATA >
using Matrix = std::vector< DBRow< TX_DATA, ALLOC >, ALLOC< DBRow< TX_DATA, ALLOC > > >
 
using iterator_category = std::random_access_iterator_tag
 Types for STL compliance. More...
 
using value_type = typename DBHandler< T_DATA, ALLOC >::value_type
 Types for STL compliance. More...
 
using reference = value_type &
 Types for STL compliance. More...
 
using const_reference = const value_type &
 Types for STL compliance. More...
 
using pointer = value_type *
 Types for STL compliance. More...
 
using const_pointer = const value_type *
 Types for STL compliance. More...
 
using difference_type = std::ptrdiff_t
 Types for STL compliance. More...
 
using allocator_type = ALLOC< T_DATA >
 Types for STL compliance. More...
 
using size_type = std::size_t
 Types for STL compliance. More...
 

Detailed Description

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
class gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler

the (unsafe) handler for the tabular databases

The IDatabaseTable class is provided with two types of handlers: unsafe handlers and safe ones. Compared to the former, the safe handlers incur a small overhead during their creation. But safe handlers are informed by their associated database when the structure of this one changes, i.e., when the number of rows/columns changes or when rows are added/removed, whereas unsafe handlers are not aware of such changes. For databases that are not affected by this kind of change, unsafe handlers should be used instead of safe ones because they are slightly faster. Both types of handlers are designed to be created in parallel by several threads.

Here is an example of how to use this class, illustrated on handlers for a RawDatabaseTable:

// create the database
database.setVariableNames( std::vector<std::string> {"v1","v2","v3"} );
// add one row to the database
database.insertRow( row );
// create a handler.
// by default, the handlers range over the whole database, which
// currently contains only one row
// here, we add 95 new rows into the database
for ( int i = 0; i < 95; ++i ) database.insertRow( row );
// due to the addition of the rows, the (unsafe) handler still thinks
// there is only one row
std::cout << handler.size (); // displays 1 (handler's range)
std::cout << handler.DBSize (); // displays 96 (database's size)
// change the range of rows handled by the DBHandler
std::cout << handler.setRange ( 1, 40 ); // now parses rows [1,40)
std::cout << handler.size (); // displays 39: rows 1,...,39
std::cout << handler.DBSize (); // displays 96: database's size
std::cout << handler.numRow (); // displays 0: the handler currently
// points on the first row of its managed area [1,40)
// move the handler to the next row
std::cout << handler.numRow (); // displays 1: the handler points now
// on the second row of its managed area. This corresponds to the third
// DBRow of the database since the range of handler is [1,40)
++handler; // move again to the next row
std::cout << handler.numRow (); // displays 2
handler += 4; // advances the pointer by 4 rows
std::cout << handler.numRow (); // displays 6
// get the DBRow pointed to by the handler: this is the 7th DBRow
// of the database
const auto& xrow7 = handler.row (); // get the DBRow, unsafe version
const auto& yrow7 = handler.rowSafe (); // get the DBRow, safe version
const std::vector<gum::learning::DBCell>& xrow = xrow7.row ();
const double xweight = xrow27.weight ();
// another way to access the row
const auto& zrow7 = *handler; // get the DBRow, unsafe version
// check whether there exist other rows managed by the handler after
// the current row
bool has_rows = handler.hasRows (); // true: there remains 33 rows
// makes the handler point again on the 2nd row of the database
handler.reset (); // the handler points to the beginning of its area
std::cout << handler.numRow (); // displays 0: the handler currently
// points on the first row of its managed area [1,40)
// see the variables' names, i.e., the names of the database's columns
const auto& vars = handler.variableNames();
// parse all the rows managed
for ( auto end = handler.end (); handler != end; ++handler )
std::cout << handler.row ().weight () << std::endl;
// another possibility:
for ( const auto& row : handler )
std::cout << row.weight () << std::endl;

Definition at line 368 of file IDatabaseTable.h.

Member Typedef Documentation

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::allocator_type = ALLOC< T_DATA >

Types for STL compliance.

Definition at line 379 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::const_pointer = const value_type*

Types for STL compliance.

Definition at line 377 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::const_reference = const value_type&

Types for STL compliance.

Definition at line 375 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
template<typename TX_DATA >
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::DBVector = std::vector< TX_DATA, ALLOC< TX_DATA > >

Definition at line 384 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::difference_type = std::ptrdiff_t

Types for STL compliance.

Definition at line 378 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::iterator_category = std::random_access_iterator_tag

Types for STL compliance.

Definition at line 372 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
template<typename TX_DATA >
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::Matrix = std::vector< DBRow< TX_DATA, ALLOC >, ALLOC< DBRow< TX_DATA, ALLOC > > >

Definition at line 391 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::pointer = value_type*

Types for STL compliance.

Definition at line 376 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::reference = value_type&

Types for STL compliance.

Definition at line 374 of file IDatabaseTable.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
template<typename TX_DATA >
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::Row = DBRow< TX_DATA, ALLOC >

Definition at line 387 of file IDatabaseTable.h.

template<typename T_DATA , template< typename > class ALLOC = std::allocator>
using gum::learning::DBHandler< T_DATA, ALLOC >::size_type = std::size_t
inherited

Types for STL compliance.

Definition at line 128 of file DBHandler.h.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
using gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::value_type = typename DBHandler< T_DATA, ALLOC >::value_type

Types for STL compliance.

Definition at line 373 of file IDatabaseTable.h.

Constructor & Destructor Documentation

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::Handler ( const IDatabaseTable< T_DATA, ALLOC > &  db)

default constructor

Parameters
dbthe database on which the handler will point to. By default, the range of the handler is the whole database.
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::Handler ( const Handler h)

copy constructor

Parameters
hthe handler we wish to copy
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::Handler ( Handler &&  h)

move constructor

Parameters
hthe handler we wish to move
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::~Handler ( )
virtual

destructor

Member Function Documentation

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::begin ( ) const
virtual

returns a new handler that points to the beginning of the database's area of the current handler

Warning
The handler returned manages precisely the same area as the handler on which begin() is called.
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::DBSize ( ) const
finalvirtual

returns the number of rows of the whole database

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::end ( ) const
virtual

returns a new handler that points to the end of the database's area of the current handler

Warning
The handler returned manages precisely the same area as the handler on which end() is called.
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual bool gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::hasRows ( ) const
finalvirtual

indicates whether the handler has reached its end or not

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::nbVariables ( ) const
finalvirtual

returns the number of variables (columns) of the database

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual void gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::nextRow ( )
finalvirtual

makes the handler point to the next row, equivalent to operator++

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::numRow ( ) const
finalvirtual

the number of the current row (0 = the 1st row managed by the handler)

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual bool gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator!= ( const Handler handler) const
finalvirtual

checks whether two handlers point to different rows in the database

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual const_reference gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator* ( ) const
finalvirtual

returns the current row pointed to by the handler (unsafe version)

Warning
The method does not check whether the handler already points to the end of the area it manages. It is thus faster than method rowSafe () but, when you call it, you must be sure that the row actually exists, i.e., that the handler has not reached its end.
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator++ ( )
finalvirtual

makes the operator point to the next row in the database

if the pointer has already reached the end of the area managed by the handler, nothing happens. In particular, no exception is raised

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator+= ( unsigned int  i)
finalvirtual

advances the handler by i rows in the database

if, applying this move would make the handler reach the end of the area managed by the handler, then the handler is kept at the end of the area, i.e., after the last element of the area.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator-- ( )
finalvirtual

makes the operator point to the previous row in the database

if the pointer is already at the beginning of the area managed by the handler, nothing happens. In particular, no exception is raised

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator-= ( unsigned int  i)
finalvirtual

moves back the handler by i rows in the database

if, applying this move would make the handler reach the beginning of the area managed by the handler, then the handler is kept at the beginning of the area, i.e., at the first element of the area.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual const_pointer gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator-> ( ) const
finalvirtual

Dereferences the value pointed to by the handler (unsafe version)

Warning
The method does not check whether the handler already points to the end of its area. It is thus faster than method rowSafe () but, when you call it, you must be sure that the row actually exists, i.e., that the handler has not reached its end.
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator= ( const Handler )
virtual
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual Handler& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator= ( Handler &&  )
virtual
template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual bool gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::operator== ( const Handler handler) const
finalvirtual

checks whether two handlers point to the same row in the database

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual std::pair< std::size_t, std::size_t > gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::range ( ) const
finalvirtual

returns the current range of the handler [begin,end)

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual void gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::reset ( )
finalvirtual

puts the handler to the beginning of the database's area it handles

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual const_reference gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::row ( ) const
finalvirtual

returns the current row pointed to by the handler (unsafe version)

Warning
The method does not check whether the handler already points to the end of its area. It is thus faster than method rowSafe () but, when you call it, you must be sure that the row actually exists, i.e., that the handler has not reached its end.

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual reference gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::row ( )
finalvirtual

returns the current row pointed to by the handler (unsafe version)

Warning
The method does not check whether the handler already points to the end of its area. It is thus faster than method rowSafe () but, when you call it, you must be sure that the row actually exists, i.e., that the handler has not reached its end.

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual const_reference gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::rowSafe ( ) const
finalvirtual

returns the current row pointed to by the handler (safe version)

Exceptions
OutOfBoundsif the handler points to the end of its area

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual reference gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::rowSafe ( )
finalvirtual

returns the current row pointed to by the handler (safe version)

Exceptions
OutOfBoundsif the handler points to the end of its area

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual void gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::setRange ( std::size_t  begin,
std::size_t  end 
)
finalvirtual

sets the area in the database the handler will handle

In addition to setting the area that will be parsed by the handler, this method makes the handler point to the beginning of the area.

Parameters
beginthe first row to be handled
endthe handler handles rows in interval [begin,end). Thus, the endth row is not included in the set of rows handled.
Warning
if begin is greater than end, these values are swapped.
Exceptions
NullElementis raised if the handler does not point to any database
SizeErroris raised if end is greater than the number of rows of the database

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual std::size_t gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::size ( ) const
finalvirtual

returns the number of rows managed by the handler

A handler needs not necessarily handle all the rows of the database. For instance, RecordCounters cut the database into several pieces and assign each piece to a handler. Then each handler is used in parallel to perform countings only on their subset of the database. The size reported by method "size" is therefore the number of rows managed by the handler. If you wish to retrieve the size of the whole database, then use method DBSize instead.

Implements gum::learning::DBHandler< T_DATA, ALLOC >.

template<typename T_DATA, template< typename > class ALLOC = std::allocator>
virtual const DBVector< std::string >& gum::learning::IDatabaseTable< T_DATA, ALLOC >::Handler::variableNames ( ) const
finalvirtual

returns the names of the variables

Implements gum::learning::DBHandler< T_DATA, ALLOC >.


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