dtl


IndexedDBView <View, IdxContainer, HashOrNoHash>

Category: containers Component type: type

Description

The IndexedDBView Container is a refinement of a Unique Associative Container with the property that elements may be bound to an underlying database and may be indexed by one or more criteria. Each index stores (and sorts or hashes) references to the data in an underlying container built by a ContainerFactory.

Definition

Defined in the IndexedDBView.h header file.

Refinement of

Unique Associative Container

Associated types

In addition to those defined by Unique Associative Container:

Argument object type IndexedDBView::Args

Nested class for arguments object used to pass parameters to the DBView constructor.

Accessors to set arguments in an Args object (all return *this as an Args &):

  • view(const View &view) - corresponds to view parameter in main constructor - no default value
  • indexes(const string &IndexNamesAndFields) - corresponds to IndexNamesAndFields parameter in main constructor - must be set for IndexedDBView to be valid
  • bound(BoundMode bm) - corresponds to bm parameter in main constructor - default value: UNBOUND
  • key(KeyMode km) - corresponds to km parameter in main constructor - default value: USE_ALL_FIELDS
  • params(const SetParamsFn IndexedDBViewParams) - corresponds to IndexedDBViewParams parameter in main constructor - default value: DefaultSetParams<ParamObj>()
  • fetch_mode(FetchMode fm) - corresponds to fm parameter in main constructor - default value: DEFAULT_FETCH_MODE (defined in dtl_config.h - Note that for code using older versions of DTL, you may need to #define DEFAULT_FETCH_MODE to be SINGLE_FETCH or explicitly set your view to use SINGLE_FETCH if bulk_copy() throws)
  • fetch_records(size_t fr) - corresponds to fr parameter in main constructor - default value: 100

To set the arguments, default construct an Args object and then successively apply accessors to this object. The parameters you reference will be set to the passed in values, all others will receive their default values. For example, to construct a indexed view of Example objects that references a DBView named view, has a unique primary key from a column named INT_VALUE and has a function for the indexed view to set the query parameters named ExampleSetParams, you would say:

typedef DBView<Example> DBV;
DBV view(DBV::Args().tables("DB_EXAMPLE").conn(myConn));
IndexedDBView<DBV> indexed_view(

   IndexedDBView<DBV>::Args().view(view).indexes("Unique PrimaryKey; INT_VALUE").params(cb_ptr_fun(ExampleSetParams))

);

The Args class is designed to emulate named arguments so you don't have to pass arguments around that just use their default values. The constructor call above would have to explicitly pass 3 arguments with their corresponding default values, which is tedious, hard to read, and very error prone.

 

Example

// "Example" class to hold rows from our database table

class Example

{

  public:                                        // tablename.columnname:

	int exampleInt;                         // DB_EXAMPLE.INT_VALUE

	string exampleStr;                      // DB_EXAMPLE.STRING_VALUE

	double exampleDouble;                   // DB_EXAMPLE.DOUBLE_VALUE

	long exampleLong;                       // DB_EXAMPLE.EXAMPLE_LONG

	TIMESTAMP_STRUCT exampleDate;           // DB_EXAMPLE.EXAMPLE_DATE



	Example(int exInt, const string &exStr, double exDouble, long exLong,

		const TIMESTAMP_STRUCT &exDate) :

	   exampleInt(exInt), exampleStr(exStr), exampleDouble(exDouble), exampleLong(exLong),

	   exampleDate(exDate)

	{ }



};



// Parameter object to hold parameters for dynamic SQL query below 

class ParamObjExample

{

    public:

	int lowIntValue;

	int highIntValue;

	string strValue;

	TIMESTAMP_STRUCT dateValue;

};



// Create an association between table columns and fields in our object

class BCAExampleObj

{

public:

	void operator()(BoundIOs &boundIOs, Example &rowbuf)

    	{

	   boundIOs["INT_VALUE"]	== rowbuf.exampleInt;

	   boundIOs["STRING_VALUE"]	== rowbuf.exampleStr;

	   boundIOs["DOUBLE_VALUE"]	== rowbuf.exampleDouble;

	   boundIOs["EXAMPLE_LONG"]	== rowbuf.exampleLong;

	   boundIOs["EXAMPLE_DATE"]	== rowbuf.exampleDate;

	}

};



// Create an association between query parameters and fields in our parameters object

class BPAExampleObj

{

public:

	void operator()(BoundIOs &boundIOs, ParamObjExample &paramObj)

	{

	  boundIOs[0] == paramObj.lowIntValue;

	  boundIOs[1] == paramObj.highIntValue;

	  boundIOs[2] == paramObj.strValue;

	  boundIOs[3] == paramObj.dateValue;

	}



};



// Set parameters function for Example ... used by IndexedDBView<Example> to set dynamic query parameters

// Dynamic query parameters are indicated by (?) in our query string for the IndexedDBView

void SetParamsExample(ParamObjExample &params)

{

	// set parameter values

	params.lowIntValue = 2;

	params.highIntValue = 8;

	params.strValue = "Example";

	

	TIMESTAMP_STRUCT paramDate = {2000, 1, 1, 0, 0, 0, 0};

	params.dateValue = paramDate;

}





// Example of using an IndexDBView to read, insert and update records in a container / database

void IndexedViewExample()

{

	typedef DBView<Example, ParamObjExample> DBV;



	DBV view("DB_EXAMPLE",   BCAExampleObj(), 

	  "WHERE INT_VALUE BETWEEN (?) AND (?) OR "

	  "STRING_VALUE = (?) OR EXAMPLE_DATE <= (?) ORDER BY EXAMPLE_LONG",

	  BPAExampleObj());



	IndexedDBView<DBV> indexed_view(view, "UNIQUE PrimaryIndex; STRING_VALUE; AlternateIndex; EXAMPLE_LONG, EXAMPLE_DATE", 

	  BOUND, USE_ALL_FIELDS, cb_ptr_fun(SetParamsExample));

   		



	// Find the item where the STRING_VALUE matches the string "Foozle"

	IndexedDBView<DBV>::iterator idxview_it = indexed_view.find(string("Foozle"));

		



	// Update the item with the key of "Foozle", to read "Fizzle" instead

	if (idxview_it != indexed_view.end()) {

		Example replacement;

		replacement = *idxview_it;

		replacement.exampleStr = "Fizzle";

		indexed_view.replace(idxview_it, replacement);

	}



	// Now find a second set of items using AlternateIndex

	// The STL convention for equal_range is to return a pair consisting of:  

	// 1. an iterator referring to the beginning of the list of found items

	// 2. an iterator pointing to the end of the list of found items. 

	// We will remove all items in this range.

	const TIMESTAMP_STRUCT date_criteria = {2000, 1, 1, 0, 0, 0, 0};

	long long_criteria = 33;

	pair<IndexedDBView<DBV>::iterator, IndexedDBView<DBV>::iterator> pr = 

		indexed_view.equal_range_AK ("AlternateIndex", long_criteria, date_criteria);



	idxview_it = pr.first;



	cout << "*** Size before erase calls: " << indexed_view.size() << " ***"

	     << endl;

		

	// Remove all items that match the criteria in our equal_range_AK lookup

	while (idxview_it != pr.second)

	{

		// As iterator is invalidated upon an erase(), use a

		// temporary iterator to point to DataObj to erase.

		// Increment idxview_it before we erase so it will still be valid

		// when we erase the DataObj.

		IndexedDBView<DBV>::iterator deleteMe = idxview_it;



		idxview_it++;



		indexed_view.erase(deleteMe);



	}



	cout << "*** Size after erase calls: " << indexed_view.size() << " ***"

	     << endl;





	// Finally, insert a new item into the container

	pair<IndexedDBView<DBV>::iterator, bool> ins_pr;



	ins_pr = indexed_view.insert(Example(459, "Unique String #1", 3.4, 1, date_criteria));



	cout << "insertion succeded = " << (ins_pr.second == true ? "true": "false") << endl;



}

Public Base Classes

None.

Template parameters

Parameter Description Default
View The type of the SQL view (usually a DBView instantiation which will be used as the underlying view for the IndexedDBView).  
IdxContainer The type of the underlying associative container used by each index to maintain its sorted collection of references to the data stored in the indexed view.

On STLPort and GCC: hash_multiset<DataObj *, hash_functor<DataObj>, eq_functor<DataObj> >

All other configurations: multiset<DataObj *, lt_functor<DataObj> >
HashOrNoHash

Type of tag structure which specifies whether the IdxContainer is hashed or not. This parameter must be either HASH or NO_HASH.

 On STLPort and GCC: HASH
All other configurations: NO_HASH

 

Notation

X A type that is a model of IndexedDBView
a Object of type X
t Object of type X::value_type
k Object of type X::key_type
p, q Object of type X::iterator
f1, f2, ..., fn A primitive C type such as int, double, float,... or STL string
s A STL string

Valid expressions

In addition to the expressions defined in Unique Associative Container, the following expressions must be valid.

Name Expression Type requirements Return type
Main constructor 
X a( 

 DBView<...> &view, 

 const string &IndexNamesAndFields,

 BoundMode bm = UNBOUND, 

 KeyMode km = USE_ALL_FIELDS, 

 SetParamsFn IndexedDBViewParam = DefaultSetParams<ParamObj>(),

 FetchMode fm = DEFAULT_FETCH_MODE, size_t fr = 100)
   
Main constructor accepting an arguments object X a(const Args &args)    
Find alternate key a.find_AK(s, k)   const_iterator
Equal range alternate key a.equal_range_AK(s, k)   pair<const_iterator, const_iterator>.
Find using key fields a.find(f1, ..., fn)   const_iterator
Equal range using key fields a.equal_range(f1, ..., fn)   pair<const_iterator, const_iterator>
Find using alternate key fields a.find_AK(s, f1, ..., fn)   const_iterator
Equal range using alternate key fields a.equal_range_AK(s, f1, ..., fn)   pair<const_iterator, const_iterator>
Replace element a.replace(p, k)   pair<const_iterator, bool>

Expression semantics

Name Expression Precondition Semantics Postcondition
Main constructor 
X a(&view, 

  &IndexNamesAndFields, 

  bm, km, IndexedDBViewParam,

  fm, fr)
  Creates an empty container bound to the DBView referenced by view. Creates named indexes on all rows fetched from DBView using the IndexedDBView of index defintions in IndexNamesAndFields.

IndexNamesAndFields takes the form "UNIQUE IndexName1; IndexField1,IndexField2; IndexName2; IndexField3, IndexField4, IndexField5". The first index in the list is used as the primary index for the default find() method. The UNIQUE keyword is optional and may be specified before any index name to indicate that keyfields in this index represent a unique key that must be checked against before any records are inserted or replaced in the container.

bm = { UNBOUND, BOUND }. If the mode for IndexedDBView to BOUND, any changes made to elements in the container will be written back to the database. If the mode is UNBOUND, any changes made are not written back to the database.

km = { USE_ALL_FIELDS, USE_PK_FIELDS_ONLY, USE_AUTO_KEY }. This affects what criteria are sent to the database for use in updating or deleting records in BOUND mode. If km in IndexedDBView is set to USE_ALL_FIELDS then any updates or deletes sent to the database will use all fields specified in the DBView object in the criteria for the underlying SQL UPDATE or SQL DELETE statement. If km USE_PK_FIELDS_ONLY then only fields that are in the primary index as defined by IndexNamesAndFields will be used to update or delete records in the database. If km is USE_AUTO_KEY: a. if the underlying DBView supports autokeys (which is only possible for DynamicDBView's with the use of a DBMS that implements autokeys), only the object in question is updated or deleted, b. otherwise, the key mode is coerced to USE_ALL_FIELDS as either the underlying DBView or the DBMS don't support autokeys.

IndexedDBViewParam. Function object that is called when the routine executes a fetch against the DBView to retrieve records from the database. This is used by IndexedDBView to set any parameters that are needed by the DBView object's query. If you already have a set of parameters in a ParamObj then you can easily create this function object by calling SetParamsFromClass<ParamObj>(params).

fm = { SINGLE_FETCH, BULK_FETCH }. Mode used to fetch the objects in the view. Conventional fetching used if SINGLE_FETCH set. If BULK_FETCH passed in, the view uses bulk_copy() to grab the elements. However, if DataObj == variant_row, fetch mode coerced to SINGLE_FETCH..

fr is the number of objects to grab in each call to bulk_copy() if in BULK_FETCH mode.

The size of the container is 0. Rows are not fetched until an attempt is made to call methods in the container.
Main constructor accepting an arguments object X a(const Args &args) !args.INF.empty()

Same as above, with the parameters specified in an Args object.

See description of Args nested type above for use.

  
Find alternate key a.find_AK(s,k)   Returns an iterator pointing to an element whose key is the same as k, with a key match determined by using the index name in s, or a.end() if no such element exists. Either the return value is a.end(), or else the return value has a key that is the same as k.
Equal range alternate key a.equal_range_AK(s, k)   Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k, with a key match determined by using the index name in s. If no elements have the same key as k, the return value is an empty range. If p is a dereferenceable iterator in a, then either p lies in the range [P.first, P.second), or else *p has a key that is not the same as k.
Find using key fields a.find(f1, ..., fn)   Returns an iterator pointing to an element whose key fields match the values given by f1,..., fn, with a key match determined by using the primary index, or a.end() if no such element exists. Key fields are matched in the order that was given in the constructor for a. Either the return value is a.end(), or else the return value has a key that is the same as f1, .. fn..
Equal range using key fields a.equal_range(f1, ...,fn)   Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k, with a key match determined by using the primary index. Key fields are matched in the order that was given in the constructor for a. If no elements have the same key as k, the return value is an empty range. If p is a dereferenceable iterator in a, then either p lies in the range [P.first, P.second), or else *p has a key that is not the same as k.
Find using alternate key fields a.find_AK(s, f1, ..., fn)   Returns an iterator pointing to an element whose key fields match the values given by f1,..., fn, with a key match determined by using the index name in s, or a.end() if no such element exists. Key fields are matched in the order that was given in the constructor for a. Either the return value is a.end(), or else the return value has a key that is the same as f1, .. fn..
Equal range using alternate key fields a.equal_range_AK(s, f1, ...,fn)   Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k, with a key match determined by using the index name in s. Key fields are matched in the order that was given in the constructor for a. If no elements have the same key as k, the return value is an empty range. If p is a dereferenceable iterator in a, then either p lies in the range [P.first, P.second), or else *p has a key that is not the same as k.
Replace element a.replace(p, k)  p is a dereferenceable iterator in a. Replaces the element in the container pointed to by p with the new value in k. The return value is a pair P. P.first is an iterator pointing to the element whose key is the same as the key of k. P.second is a bool: it is true if p was actually updated in a, and false if p was not updated in a, i.e. if a already contained an element not equal to p with the same key as k. This uniqueness constraint is checked against all UNIQUE indexes specified in the IndexNamesAndFields parameter of the constructor. P.first is a dereferenceable iterator. *(P.first) has the same key as k.

Members

Member Where defined Description
value_type Container The type of object, T, stored in the IndexedDBView.
key_type Associative Container The key type associated with value_type.
pointer Container Pointer to T.
reference Container Reference to T
const_reference Container Const reference to T
size_type Container An unsigned integral type.
difference_type Container A signed integral type.
iterator Container Iterator used to iterate through a IndexedDBView.
const_iterator Container Const iterator used to iterate through a IndexedDBView. (Iterator and const_iterator are the same type.)
reverse_iterator Reversible Container Iterator used to iterate backwards through a IndexedDBView.
const_reverse_iterator Reversible Container Const iterator used to iterate backwards through a IndexedDBView. (Reverse_iterator and const_reverse_iterator are the same type.)
iterator begin() Container Returns an iterator pointing to the beginning of the IndexedDBView.
const_iterator begin() const Container Returns a const_iterator pointing to the beginning of the IndexedDBView.
iterator end() Container Returns an iterator pointing to the end of the IndexedDBView.
const_iterator end() const Container Returns a const_iterator pointing to the end of the IndexedDBView.
reverse_iterator rbegin() Reversible Container Returns a reverse_iterator pointing to the beginning of the reversed IndexedDBView.
const_reverse_iterator rbegin() const Reversible Container Returns a const_reverse_iterator pointing to the beginning of the reversed IndexedDBView.
reverse_iterator rend() Reversible Container Returns a reverse_iterator pointing to the end of the reversed IndexedDBView.
const_reverse_iterator rend() const Reversible Container Returns a const_reverse_iterator pointing to the end of the reversed IndexedDBView.
iterator begin_AK(const string &IndexNm) Container Returns an iterator pointing to the beginning of the DBIndex 's list for the index name passed in.
const_iterator begin_AK(const string &IndexNm) const Container Returns a const_iterator pointing to the beginning of the DBIndex 's list for the index name passed in.
iterator end_AK(const string &IndexNm) Container Returns an iterator pointing to the end of the DBIndex 's list for the index name passed in.
const_iterator end_AK(const string &IndexNm) const Container Returns a const_iterator pointing to the end of the DBIndex 's list for the index name passed in.
reverse_iterator rbegin_AK(const string &IndexNm) Reversible Container Returns a reverse_iterator pointing to the beginning of the reversed DBIndex 's list for the index name passed in.
const_reverse_iterator rbegin_AK(const string &IndexNm) const Reversible Container Returns a const_reverse_iterator pointing to the beginning of the reversed DBIndex 's list for the index name passed in.
reverse_iterator rend_AK(const string &IndexNm) Reversible Container Returns a reverse_iterator pointing to the end of the reversed DBIndex 's list for the index name passed in.
const_reverse_iterator rend_AK(const string &IndexNm) const Reversible Container Returns a const_reverse_iterator pointing to the end of the reversed DBIndex 's list for the index name passed in.
size_type size() const Container Returns the size of the IndexedDBView.
size_type max_size() const Container Returns the largest possible size of the IndexedDBView.
bool empty() const Container true if the IndexedDBView's size is 0. 
X a( 

 DBView<...> &view, 

 const string &IndexNamesAndFields,

 BoundMode bm = UNBOUND, 

 KeyMode km = USE_ALL_FIELDS, 

 SetParamsFn IndexedDBViewParam = DefaultSetParams<ParamObj>())
Container Creates an empty IndexedDBView.
IndexedDBView(const IndexedDBView&) Container The copy constructor.
IndexedDBView& operator=(const IndexedDBView&) Container The assignment operator
void swap(IndexedDBView&) Container Swaps the contents of two IndexedDBView's. 

pair<iterator, bool>

insert(const value_type& x)
Unique Associative Container Inserts x into the IndexedDBView. 

iterator insert(iterator pos, 

                const value_type& x)
Unique Sorted Associative Container Inserts x into the IndexedDBView, using pos as a hint to where it will be inserted. 

template <class InputIterator>

void insert(InputIterator, 

InputIterator)
Unique Sorted Associative Container Inserts a range into the IndexedDBView.
void erase(iterator pos) Associative Container Erases the element pointed to by pos.
size_type erase(const key_type& k) Associative Container Erases the element whose key is k.
void erase(iterator first, iterator last) Associative Container Erases all elements in a range.
void clear() Associative Container Erases all of the elements.
iterator find(const key_type& k) const Associative Container Finds an element whose key is k.
iterator find(f1, f2, ..., fn) const IndexedDBView Finds an element whose key fields match f1,...fn.
iterator find_AK(const string &s, const key_type& k) const IndexedDBView Finds an element whose alternate key as specified in the index name s, is k.
iterator find_AK(s, f1, f2, ..., fn) const IndexedDBView Finds an element whose key fields match f1,...fn as specified in the index name s.
size_type count(const key_type& k) const Unique Associative Container Counts the number of elements whose key is k.
size_type count_AK(const string &s, const key_type& k) const Unique Associative Container Counts the number of elements whose key is k for the key named s. 

pair<iterator, iterator> 

equal_range(const key_type& k) const
Sorted Associative Container Finds a range containing all elements whose key is k. 

pair<iterator, iterator> 

equal_range(f1, ..., fn) const
IndexedDBView Finds a range containing all elements whose key fields match f1, ..., fn. 

pair<iterator, iterator> 

equal_range_AK(const string &s,

const key_type& k) const
IndexedDBView Finds a range containing all elements whose key is k, using the alternate index specified in s. 

pair<iterator, iterator> 

equal_range_AK(s, f1, ..., fn) const
IndexedDBView Finds a range containing all elements whose key fields match f1, ..., fn using the alternate index specified in s.
template<class UserHandler> const UserHandler & get_io_handler(UserHandler *dummy) const DBView Returns the current IOHandler for the underlying DBView cast to the actual type of the handler based on the dummy pointer passed in. If the dynamic cast of the IOHandler object fails, an exception will be thrown.
IOHandler<DataObj, ParamObj> &get_io_handler() const DBView Returns the current IOHandler for the underlying DBView as a raw IOHandler object. You must cast to the actual type of the handler to be able to access any of your handler's public members. 

bool operator==(const IndexedDBView&, 

                const IndexedDBView&)
Forward Container Tests two IndexedDBView's for equality. This is a global function, not a member function. 

bool operator<(const IndexedDBView&, 

               const IndexedDBView&)
Forward Container Lexicographical comparison. This is a global function, not a member function.
DataObj GetDataObj() const IndexedDBView Returns a prototype DataObj with its structure built if necessary (needed in the case of variant_row).

See also

Associative Container, Multiple Associative Container, Unique Sorted Associative Container, Multiple Sorted Associative Container

[DTL Home]

Copyright © 2002, Michael Gradman and Corwin Joy.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Corwin Joy and Michael Gradman make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

SourceForge Logo

This site written using the ORB. [The ORB]