Main point of access to EJDB. More...

#include <ejdb.hpp>

Public Member Functions
	db () noexcept=default
	Default constructor. Result is a null EJDB handle.

bool	close (std::error_code &ec) noexcept
	Closes the currently open EJDB database. More...

void	close ()
	Closes the currently open EJDB database. More...

collection	create_collection (const std::string &name, std::error_code &ec)
	Returns an existing, or otherwise newly created, collection, named `name`. More...

collection	create_collection (const std::string &name)
	Returns an existing, or otherwise newly created, collection, named `name`. More...

query	create_query (const std::vector< char > &doc, std::error_code &ec)
	Create a query from a BSON document. More...

query	create_query (const std::vector< char > &doc)
	Create a query from a BSON document. More...

std::error_code	error () const noexcept
	Returns last error that occurred. More...

collection	get_collection (const std::string &name, std::error_code &ec) const
	Returns an existing collection named `name`, or a default constructed ejdb::collection. More...

collection	get_collection (const std::string &name) const
	Returns an existing collection named `name`, or a default constructed ejdb::collection. More...

const std::vector< collection >	get_collections () const
	Returns all existing collections.

bool	is_open () const noexcept
	Returns whether the db object refers to a valid and open EJDB database.

std::vector< char >	metadata (std::error_code &ec)
	Returns description of the EJDB database. More...

std::vector< char >	metadata ()
	Returns description of the EJDB database. More...

bool	open (const std::string &path, db_mode mode, std::error_code &ec)
	Opens EJDB database at `path`. More...

void	open (const std::string &path, db_mode mode)
	Opens EJDB database at `path`. More...

	operator bool () const noexcept
	Returns whether a valid EJDB handle is contained within.

bool	remove_collection (const std::string &name, bool unlink_file, std::error_code &ec)
	Removes a collection named `name`, or do nothing if `name` does not exist. More...

void	remove_collection (const std::string &name, bool unlink_file)
	Removes a collection named `name`, or do nothing if `name` does not exist. More...

bool	sync (std::error_code &ec) noexcept
	Synchronise the EJDB database to disk. More...

void	sync ()
	Synchronise the EJDB database to disk. More...

Static Public Member Functions
static std::error_code	error (std::weak_ptr< EJDB >) noexcept
	Returns last error that occurred. More...

Detailed Description

Main point of access to EJDB.

Uses a shared implementation, i.e. copies of a db object operate on the same EJDB handle.

Member Function Documentation

bool ejdb::db::close ( std::error_code & ec )

noexcept

Closes the currently open EJDB database.

Parameters

[out] ec Set to an appropriate error code on failure.

Returns: true on success, false on failure.

void ejdb::db::close ( )

Closes the currently open EJDB database.

Exceptions

std::system_error with appropriate error code and message on failure.

See also: db::close

collection ejdb::db::create_collection	(	const std::string &	name,
		std::error_code &	ec
	)

Returns an existing, or otherwise newly created, collection, named name.

Parameters

	name	Name of collection to fetch or create.
[out]	ec	Set to an appropriate error code on failure.

Returns: Valid collection on success, invalid collection on failure.

collection ejdb::db::create_collection ( const std::string & name )

Returns an existing, or otherwise newly created, collection, named name.

Parameters

name	Name of collection to fetch or create.

Returns: Valid collection on success, throws on failure.

Exceptions

std::system_error with appropriate error code and message on failure.

query ejdb::db::create_query	(	const std::vector< char > &	doc,
		std::error_code &	ec
	)

Create a query from a BSON document.

EJDB's query documentation follows.

EJDB queries inspired by MongoDB (mongodb.org) and follows same philosophy.

Supported queries:
- Simple matching of String OR Number OR Array value:
  - {'fpath' : 'val', ...}
- $not Negate operation.
  - {'fpath' : {'$not' : val}} //Field not equal to val
  - {'fpath' : {'$not' : {'$begin' : prefix}}} //Field not begins with val
- $begin String starts with prefix
  - {'fpath' : {'$begin' : prefix}}
- $gt, $gte (>, >=) and $lt, $lte for number types:
  - {'fpath' : {'$gt' : 42}, ...}
- $bt Between for number types:
  - {'fpath' : {'$bt' : [num1, num2]}}
- $in String OR Number OR Array val matches to value in specified array:
  - {'fpath' : {'$in' : [val1, val2, val3]}}
- $nin - Not IN
- $strand String tokens OR String array val matches all tokens in specified array:
  - {'fpath' : {'$strand' : [val1, val2, val3]}}
- $stror String tokens OR String array val matches any token in specified array:
  - {'fpath' : {'$stror' : [val1, val2, val3]}}
- $exists Field existence matching:
  - {'fpath' : {'$exists' : true|false}}
- $icase Case insensitive string matching:
  - {'fpath' : {'$icase' : 'val1'}} //icase matching
    
    Ignore case matching with '$in' operation:
  - {'name' : {'$icase' : {'$in' : ['théâtre - театр', 'hello world']}}}
    
    For case insensitive matching you can create special index of type: JBIDXISTR
- $elemMatch The $elemMatch operator matches more than one component within an array element.
  - { 'some_array.fpath': { '$elemMatch': { 'value1' : 1, 'value2' : { '$gt': 1 } } } }
    
    Restriction: only one $elemMatch allowed in context of one array field.
- $and, $or joining:
  - {..., '$and' : [subq1, subq2, ...] }
  - {..., '$or' : [subq1, subq2, ...] }
    
    Example:
    {'z' : 33, '$and' : [ {'$or' : [{'a' : 1}, {'b' : 2}]}, {'$or' : [{'c' : 5}, {'d' : 7}]} ] }
- Mongodb operator supported. (http://docs.mongodb.org/manual/reference/projection/positional/#proj._S_)
- Mongodb positional $ update operator supported. (http://docs.mongodb.org/manual/reference/operator/positional/)
Queries can be used to update records:
- $set Field set operation.
  - {.., '$set' : {'fpath1' : val1, 'fpathN' : valN}}
- $upsert Atomic upsert. If matching records are found it will be '$set' operation, otherwise new record will be inserted with fields specified by argment object.
  - {.., '$upsert' : {'fpath1' : val1, 'fpathN' : valN}}
- $inc Increment operation. Only number types are supported.
  - {.., '$inc' : {'fpath1' : 5, ..., 'fpath2' : 2}
- $dropall In-place record removal operation.
  - {.., '$dropall' : true}
- $addToSet Atomically adds value to the array only if its not in the array already. If containing array is missing it will be created.
  - {.., '$addToSet' : {'fpath' : val1, 'fpathN' : valN, ...}}
- $addToSetAll Batch version if $addToSet
  - {.., '$addToSetAll' : {'fpath' : [values to add, ...], ...}}
- $pull Atomically removes all occurrences of value from field, if field is an array.
  - {.., '$pull' : {'fpath' : val1, 'fpathN' : valN, ...}}
- $pullAll Batch version of $pull
  - {.., '$pullAll' : {'fpath' : [values to remove, ...], ...}}
Collection joins supported in the following form:
{..., '$do' : {'fpath' : {'$join' : 'collectionname'}} }

Where 'fpath' value points to object's OIDs from 'collectionname'. Its value can be OID, string representation of OID or array of this pointers.

Note: It is better to execute update queries with collection::execute_query<query_search_mode::count_only> to avoid unnecessarily fetching data.; Negate operations: $not and $nin do not use indexes so they can be slow in comparison to other matching operations.; Only one index can be used in search query operation.

Parameters

	doc	BSON query object.
[out]	ec	Set to an appropriate error code on failure.

Returns: Valid query on success, invalid query on failure.

query ejdb::db::create_query ( const std::vector< char > & doc )

Create a query from a BSON document.

Same as create_query, throws exception instead of setting an std::error_code on failure.

Parameters

doc	BSON query object.

Exceptions

std::system_error with appropriate error code and message on failure.

See also: create_query

std::error_code ejdb::db::error ( ) const

noexcept

Returns last error that occurred.

Returns: std::error_code representing last error, or std::errc::operation_not_permitted (EPERM) if EJDB handle is invalid.

std::error_code ejdb::db::error ( std::weak_ptr< EJDB > db )

staticnoexcept

Returns last error that occurred.

Parameters

db	weak_ptr to an EJDB handle.

Returns: std::error_code representing last error, or std::errc::operation_not_permitted (EPERM) if db refers to destroyed handle.

collection ejdb::db::get_collection	(	const std::string &	name,
		std::error_code &	ec
	)		const

Returns an existing collection named name, or a default constructed ejdb::collection.

Parameters

	name	Name of collection to fetch.
[out]	ec	Set to an appropriate error code on failure.

Returns: Valid collection on success, default collection on failure.

collection ejdb::db::get_collection ( const std::string & name ) const

Returns an existing collection named name, or a default constructed ejdb::collection.

Parameters

name	Name of collection to fetch.

Returns: Valid collection on success, default constructed collection when none matching name found, throws on failure.

Exceptions

std::system_error with appropriate error code and message on failure.

std::vector< char > ejdb::db::metadata ( std::error_code & ec )

Returns description of the EJDB database.

Parameters

[out] ec Set to an appropriate error code on failure.

Returns: Valid BSON document on success, empty vector on failure.

std::vector< char > ejdb::db::metadata ( )

Returns description of the EJDB database.

Returns: Valid BSON document.

Exceptions

std::system_error with appropriate error code and message on failure.

bool ejdb::db::open	(	const std::string &	path,
		db_mode	mode,
		std::error_code &	ec
	)

Opens EJDB database at path.

Parameters

	path	Location on filesystem where an EJDB databaes exists.
	mode	Bitwise-ORed flags to determine how to open the database.
[out]	ec	Set to an appropriate error code on failure.

Returns: true on success, false on failure.

void ejdb::db::open	(	const std::string &	path,
		db_mode	mode
	)

Opens EJDB database at path.

Parameters

path	Location on filesystem where an EJDB databaes exists.
mode	Bitwise-ORed flags to determine how to open the database.

Exceptions

std::system_error with appropriate error code and message on failure.

See also: db::open

bool ejdb::db::remove_collection	(	const std::string &	name,
		bool	unlink_file,
		std::error_code &	ec
	)

Removes a collection named name, or do nothing if name does not exist.

Parameters

	name	Name of collection to remove.
	unlink_file	Whether to remove associated files, i.e. db collection file, indexes, etc.
[out]	ec	Set to an appropriate error code on failure.

Returns: true on success, false on failure.

void ejdb::db::remove_collection	(	const std::string &	name,
		bool	unlink_file
	)

Removes a collection named name, or do nothing if name does not exist.

Parameters

name	Name of collection to remove.
unlink_file	Whether to remove associated files, i.e. db collection file, indexes, etc.

Exceptions

std::system_error with appropriate error code and message on failure.

bool ejdb::db::sync ( std::error_code & ec )

noexcept

Synchronise the EJDB database to disk.

Parameters

[out] ec Set to an appropriate error code on failure.

Returns: true on success, false on failure.

void ejdb::db::sync ( )

Synchronise the EJDB database to disk.

Exceptions

std::system_error with appropriate error code and message on failure.

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

/home/chris/projects/ejpp/include/ejpp/ejdb.hpp
/home/chris/projects/ejpp/src/ejpp/ejdb.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation