gum::learning::IDatabaseTable< T_DATA >::HandlerSafe Class Reference

the safe handler of the tabular databases More...

#include <agrum/BN/learning/IDatabaseTable.h>

Inheritance diagram for gum::learning::IDatabaseTable< T_DATA >::HandlerSafe:

Collaboration diagram for gum::learning::IDatabaseTable< T_DATA >::HandlerSafe:

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

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

Detailed Description

template<typename T_DATA>
class gum::learning::IDatabaseTable< T_DATA >::HandlerSafe

the safe handler of 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
gum::learning::RawDatabaseTable<> database;
database.setVariableNames( std::vector<std::string> {"v1","v2","v3"} );
 
// add one row to the database
gum::learning::DBRow<gum::learning::DBCell>
  row( 3, gum::learning::DBCell(2) );
database.insertRow( row );
 
// create a handler.
typename gum::learning::RawDatabaseTable<>::HandlerSafe handler(database);
// 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 safe handler updates its range
// and its area is now [0,96)
std::cout << handler.size ();   // displays 96 (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
handler.nextRow();
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
handler.reset ();
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 693 of file IDatabaseTable.h.

Member Typedef Documentation

const_pointer

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::const_pointer = const value_type*

Types for STL compliance.

Definition at line 702 of file IDatabaseTable.h.

const_reference

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::const_reference = const value_type&

Types for STL compliance.

Definition at line 700 of file IDatabaseTable.h.

DBVector

template<typename T_DATA>

template<typename TX_DATA>

using gum::learning::IDatabaseTable< T_DATA >::Handler::DBVector = std::vector< TX_DATA >

inherited

Definition at line 392 of file IDatabaseTable.h.

difference_type

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::difference_type = std::ptrdiff_t

Types for STL compliance.

Definition at line 703 of file IDatabaseTable.h.

iterator_category

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::iterator_category = std::random_access_iterator_tag

Types for STL compliance.

Definition at line 697 of file IDatabaseTable.h.

Matrix

template<typename T_DATA>

template<typename TX_DATA>

using gum::learning::IDatabaseTable< T_DATA >::Handler::Matrix = std::vector< DBRow< TX_DATA > >

inherited

Definition at line 398 of file IDatabaseTable.h.

pointer

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::pointer = value_type*

Types for STL compliance.

Definition at line 701 of file IDatabaseTable.h.

reference

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::reference = value_type&

Types for STL compliance.

Definition at line 699 of file IDatabaseTable.h.

Row

template<typename T_DATA>

template<typename TX_DATA>

using gum::learning::IDatabaseTable< T_DATA >::Handler::Row = DBRow< TX_DATA >

inherited

Definition at line 395 of file IDatabaseTable.h.

size_type

template<typename T_DATA>

using gum::learning::DBHandler< T_DATA >::size_type = std::size_t

inherited

Types for STL compliance.

Definition at line 150 of file DBHandler.h.

value_type

template<typename T_DATA>

using gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::value_type = typename Handler::value_type

Types for STL compliance.

Definition at line 698 of file IDatabaseTable.h.

Constructor & Destructor Documentation

HandlerSafe() [1/3]

template<typename T_DATA>

gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::HandlerSafe

(

const IDatabaseTable< T_DATA > &

db

)

default constructor

Parameters

db	the database on which the handler will point to. By default, the range of the handler is the whole database.

References gum::learning::IDatabaseTable< T_DATA >::IDatabaseTable().

Referenced by HandlerSafe(), HandlerSafe(), operator=(), operator=(), operator=(), and operator=().

Here is the call graph for this function:

Here is the caller graph for this function:

HandlerSafe() [2/3]

template<typename T_DATA>

gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::HandlerSafe

(

const HandlerSafe &

h

)

copy constructor

References HandlerSafe().

Here is the call graph for this function:

HandlerSafe() [3/3]

template<typename T_DATA>

gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::HandlerSafe

(

HandlerSafe &&

h

)

move constructor

References HandlerSafe().

Here is the call graph for this function:

~HandlerSafe()

template<typename T_DATA>

virtual gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::~HandlerSafe ( )

virtual

destructor

Member Function Documentation

begin()

template<typename T_DATA>

virtual Handler gum::learning::IDatabaseTable< T_DATA >::Handler::begin ( ) const

virtualinherited

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.

References Handler(), and begin().

Referenced by begin().

Here is the call graph for this function:

Here is the caller graph for this function:

database()

template<typename T_DATA>

virtual const IDatabaseTable< T_DATA > & gum::learning::IDatabaseTable< T_DATA >::Handler::database ( ) const

virtualinherited

returns a pointer on the database

Exceptions

NullElement

is raised if the handler does not point toward any database.

References gum::learning::IDatabaseTable< T_DATA >::IDatabaseTable(), and database().

Referenced by database().

Here is the call graph for this function:

Here is the caller graph for this function:

DBSize()

template<typename T_DATA>

virtual std::size_t gum::learning::IDatabaseTable< T_DATA >::Handler::DBSize ( ) const

finalvirtualinherited

returns the number of rows of the whole database

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

References DBSize().

Referenced by DBSize().

Here is the call graph for this function:

Here is the caller graph for this function:

end()

template<typename T_DATA>

virtual Handler gum::learning::IDatabaseTable< T_DATA >::Handler::end ( ) const

virtualinherited

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.

References Handler(), and end().

Referenced by end().

Here is the call graph for this function:

Here is the caller graph for this function:

hasRows()

template<typename T_DATA>

virtual bool gum::learning::IDatabaseTable< T_DATA >::Handler::hasRows ( ) const

finalvirtualinherited

indicates whether the handler has reached its end or not

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

References hasRows().

Referenced by hasRows().

Here is the call graph for this function:

Here is the caller graph for this function:

nbVariables()

template<typename T_DATA>

virtual std::size_t gum::learning::IDatabaseTable< T_DATA >::Handler::nbVariables ( ) const

finalvirtualinherited

returns the number of variables (columns) of the database

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

References nbVariables().

Referenced by nbVariables().

Here is the call graph for this function:

Here is the caller graph for this function:

nextRow()

template<typename T_DATA>

virtual void gum::learning::IDatabaseTable< T_DATA >::Handler::nextRow ( )

finalvirtualinherited

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

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

References nextRow().

Referenced by nextRow().

Here is the call graph for this function:

Here is the caller graph for this function:

numRow()

template<typename T_DATA>

virtual std::size_t gum::learning::IDatabaseTable< T_DATA >::Handler::numRow ( ) const

finalvirtualinherited

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

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

References numRow().

Referenced by numRow().

Here is the call graph for this function:

Here is the caller graph for this function:

operator!=()

template<typename T_DATA>

virtual bool gum::learning::IDatabaseTable< T_DATA >::Handler::operator!= ( const Handler & handler ) const

finalvirtualinherited

checks whether two handlers point to different rows in the database

References Handler(), and gum::learning::IDatabaseTable< T_DATA >::handler().

Here is the call graph for this function:

operator*()

template<typename T_DATA>

virtual const_reference gum::learning::IDatabaseTable< T_DATA >::Handler::operator* ( ) const

finalvirtualinherited

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.

operator++()

template<typename T_DATA>

virtual Handler & gum::learning::IDatabaseTable< T_DATA >::Handler::operator++ ( )

finalvirtualinherited

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

References Handler().

Here is the call graph for this function:

operator+=()

template<typename T_DATA>

virtual Handler & gum::learning::IDatabaseTable< T_DATA >::Handler::operator+= ( const std::size_t i )

finalvirtualinherited

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.

References Handler().

Here is the call graph for this function:

operator--()

template<typename T_DATA>

virtual Handler & gum::learning::IDatabaseTable< T_DATA >::Handler::operator-- ( )

finalvirtualinherited

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

References Handler().

Here is the call graph for this function:

operator-=()

template<typename T_DATA>

virtual Handler & gum::learning::IDatabaseTable< T_DATA >::Handler::operator-= ( const std::size_t i )

finalvirtualinherited

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.

References Handler().

Here is the call graph for this function:

operator->()

template<typename T_DATA>

virtual const_pointer gum::learning::IDatabaseTable< T_DATA >::Handler::operator-> ( ) const

finalvirtualinherited

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.

operator=() [1/4]

template<typename T_DATA>

virtual HandlerSafe & gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::operator= ( const Handler & )

virtual

copy operator

Reimplemented from gum::learning::IDatabaseTable< T_DATA >::Handler.

References gum::learning::IDatabaseTable< T_DATA >::Handler::Handler(), and HandlerSafe().

Here is the call graph for this function:

operator=() [2/4]

template<typename T_DATA>

virtual HandlerSafe & gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::operator= ( const HandlerSafe & )

virtual

copy operator

References HandlerSafe().

Here is the call graph for this function:

operator=() [3/4]

template<typename T_DATA>

virtual HandlerSafe & gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::operator= ( Handler && )

virtual

move operator

Reimplemented from gum::learning::IDatabaseTable< T_DATA >::Handler.

References gum::learning::IDatabaseTable< T_DATA >::Handler::Handler(), HandlerSafe(), and gum::learning::IDatabaseTable< T_DATA >::IDatabaseTable().

Here is the call graph for this function:

operator=() [4/4]

template<typename T_DATA>

virtual HandlerSafe & gum::learning::IDatabaseTable< T_DATA >::HandlerSafe::operator= ( HandlerSafe && )

virtual

move operator

References HandlerSafe().

Here is the call graph for this function:

operator==()

template<typename T_DATA>

virtual bool gum::learning::IDatabaseTable< T_DATA >::Handler::operator== ( const Handler & handler ) const

finalvirtualinherited

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

References Handler(), and gum::learning::IDatabaseTable< T_DATA >::handler().

Here is the call graph for this function:

range()

template<typename T_DATA>

virtual std::pair< std::size_t, std::size_t > gum::learning::IDatabaseTable< T_DATA >::Handler::range ( ) const

finalvirtualinherited

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

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

References range().

Referenced by range().

Here is the call graph for this function:

Here is the caller graph for this function:

reset()

template<typename T_DATA>

virtual void gum::learning::IDatabaseTable< T_DATA >::Handler::reset ( )

finalvirtualinherited

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

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

References reset().

Referenced by reset().

Here is the call graph for this function:

Here is the caller graph for this function:

row() [1/2]

template<typename T_DATA>

virtual const_reference gum::learning::IDatabaseTable< T_DATA >::Handler::row ( ) const

finalvirtualinherited

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 >.

References row().

Referenced by row(), and row().

Here is the call graph for this function:

Here is the caller graph for this function:

row() [2/2]

template<typename T_DATA>

virtual reference gum::learning::IDatabaseTable< T_DATA >::Handler::row ( )

finalvirtualinherited

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 >.

References row().

Here is the call graph for this function:

rowSafe() [1/2]

template<typename T_DATA>

virtual const_reference gum::learning::IDatabaseTable< T_DATA >::Handler::rowSafe ( ) const

finalvirtualinherited

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

Exceptions

OutOfBounds

if the handler points to the end of its area

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

References rowSafe().

Referenced by rowSafe(), and rowSafe().

Here is the call graph for this function:

Here is the caller graph for this function:

rowSafe() [2/2]

template<typename T_DATA>

virtual reference gum::learning::IDatabaseTable< T_DATA >::Handler::rowSafe ( )

finalvirtualinherited

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

Exceptions

OutOfBounds

if the handler points to the end of its area

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

References rowSafe().

Here is the call graph for this function:

setRange()

template<typename T_DATA>

virtual void gum::learning::IDatabaseTable< T_DATA >::Handler::setRange ( std::size_t first, std::size_t last )

finalvirtualinherited

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

first	the first row to be handled
last	the handler handles rows in interval [first,last). Thus, the endth row is not included in the set of rows handled.

Warning

if first is greater than last, these values are swapped.

Exceptions

NullElement	is raised if the handler does not point to any database
SizeError	is raised if end is greater than the number of rows of the database

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

References setRange().

Referenced by setRange().

Here is the call graph for this function:

Here is the caller graph for this function:

size()

template<typename T_DATA>

virtual std::size_t gum::learning::IDatabaseTable< T_DATA >::Handler::size ( ) const

finalvirtualinherited

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 counts 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 >.

References size().

Referenced by size().

Here is the call graph for this function:

Here is the caller graph for this function:

variableNames()

template<typename T_DATA>

virtual const DBVector< std::string > & gum::learning::IDatabaseTable< T_DATA >::Handler::variableNames ( ) const

finalvirtualinherited

returns the names of the variables

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

References variableNames().

Referenced by variableNames().

Here is the call graph for this function:

Here is the caller graph for this function:

---

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

• agrum/base/database/IDatabaseTable.h