libmongo-client 0.1.4
Functions
Cursor & Retrieval
BSON

This section documents the cursors, and the data retrieval functions. More...

Collaboration diagram for Cursor & Retrieval:

Functions

bson_cursor * bson_cursor_new (const bson *b)
 Create a new cursor.
bson_cursor * bson_find (const bson *b, const gchar *name)
 Create a new cursor positioned at a given key.
void bson_cursor_free (bson_cursor *c)
 Delete a cursor, and free up all resources used by it.
gboolean bson_cursor_next (bson_cursor *c)
 Position the cursor to the next key.
gboolean bson_cursor_find_next (bson_cursor *c, const gchar *name)
 Move the cursor to a given key, past the current one.
gboolean bson_cursor_find (bson_cursor *c, const gchar *name)
 Move the cursor to a given key.
bson_type bson_cursor_type (const bson_cursor *c)
 Determine the type of the current element.
const gchar * bson_cursor_type_as_string (const bson_cursor *c)
 Retrieve the type of the current element, as string.
const gchar * bson_cursor_key (const bson_cursor *c)
 Determine the name of the current elements key.
gboolean bson_cursor_get_string (const bson_cursor *c, const gchar **dest)
 Get the value stored at the cursor, as string.
gboolean bson_cursor_get_double (const bson_cursor *c, gdouble *dest)
 Get the value stored at the cursor, as a double.
gboolean bson_cursor_get_document (const bson_cursor *c, bson **dest)
 Get the value stored at the cursor, as a BSON document.
gboolean bson_cursor_get_array (const bson_cursor *c, bson **dest)
 Get the value stored at the cursor, as a BSON array.
gboolean bson_cursor_get_binary (const bson_cursor *c, bson_binary_subtype *subtype, const guint8 **data, gint32 *size)
 Get the value stored at the cursor, as binary data.
gboolean bson_cursor_get_oid (const bson_cursor *c, const guint8 **dest)
 Get the value stored at the cursor, as an ObjectID.
gboolean bson_cursor_get_boolean (const bson_cursor *c, gboolean *dest)
 Get the value stored at the cursor, as a boolean.
gboolean bson_cursor_get_utc_datetime (const bson_cursor *c, gint64 *dest)
 Get the value stored at the cursor, as an UTC datetime.
gboolean bson_cursor_get_regex (const bson_cursor *c, const gchar **regex, const gchar **options)
 Get the value stored at the cursor, as a regexp.
gboolean bson_cursor_get_javascript (const bson_cursor *c, const gchar **dest)
 Get the value stored at the cursor, as javascript code.
gboolean bson_cursor_get_symbol (const bson_cursor *c, const gchar **dest)
 Get the value stored at the cursor, as a symbol.
gboolean bson_cursor_get_javascript_w_scope (const bson_cursor *c, const gchar **js, bson **scope)
 Get the value stored at the cursor, as javascript code w/ scope.
gboolean bson_cursor_get_int32 (const bson_cursor *c, gint32 *dest)
 Get the value stored at the cursor, as a 32-bit integer.
gboolean bson_cursor_get_timestamp (const bson_cursor *c, gint64 *dest)
 Get the value stored at the cursor, as a timestamp.
gboolean bson_cursor_get_int64 (const bson_cursor *c, gint64 *dest)
 Get the value stored at the cursor, as a 64-bit integer.

Detailed Description

This section documents the cursors, and the data retrieval functions.

Each and every function here operates on finished BSON objects, and will return with an error if passed an open object.

Data can be retrieved from cursors, which in turn point to a specific part of the BSON object.

The idea is to place the cursor to the appropriate key first, then retrieve the data stored there. Trying to retrieve data that is of different type than what the cursor is results in an error.

Functions to iterate to the next key, and retrieve the current keys name are also provided.


Function Documentation

gboolean bson_cursor_find ( bson_cursor *  c,
const gchar *  name 
)

Move the cursor to a given key.

Like bson_cursor_find_next(), this function will start scanning the BSON object at the current position. If the key is not found after it, it will wrap over and search up to the original position.

Parameters:
cis the cursor to move.
nameis the key name to position to.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 935 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_find_next ( bson_cursor *  c,
const gchar *  name 
)

Move the cursor to a given key, past the current one.

Scans the BSON object past the current key, in search for the specified one, and positions the cursor there if found, leaves it in place if not.

Parameters:
cis the cursor to move forward.
nameis the key name to position to.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 945 of file bson.c.

Here is the call graph for this function:

void bson_cursor_free ( bson_cursor *  c)

Delete a cursor, and free up all resources used by it.

Parameters:
cis the cursor to free.

Definition at line 800 of file bson.c.

Here is the caller graph for this function:

gboolean bson_cursor_get_array ( const bson_cursor *  c,
bson **  dest 
)

Get the value stored at the cursor, as a BSON array.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be a newly allocated, finished object: it is the responsibility of the caller to free it.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1058 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_binary ( const bson_cursor *  c,
bson_binary_subtype subtype,
const guint8 **  data,
gint32 *  size 
)

Get the value stored at the cursor, as binary data.

Parameters:
cis the cursor pointing at the appropriate element.
subtypeis a pointer to store the binary subtype at.
datais a pointer to where the data shall be stored.
sizeis a pointer to store the size at.
Note:
The data pointer will be pointing to an internal structure, it must not be freed or modified.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1082 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_boolean ( const bson_cursor *  c,
gboolean *  dest 
)

Get the value stored at the cursor, as a boolean.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1113 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_document ( const bson_cursor *  c,
bson **  dest 
)

Get the value stored at the cursor, as a BSON document.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be a newly allocated, finished object: it is the responsibility of the caller to free it.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1034 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_double ( const bson_cursor *  c,
gdouble *  dest 
)

Get the value stored at the cursor, as a double.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1020 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_int32 ( const bson_cursor *  c,
gint32 *  dest 
)

Get the value stored at the cursor, as a 32-bit integer.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1212 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_int64 ( const bson_cursor *  c,
gint64 *  dest 
)

Get the value stored at the cursor, as a 64-bit integer.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1240 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_javascript ( const bson_cursor *  c,
const gchar **  dest 
)

Get the value stored at the cursor, as javascript code.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be set to point to an internal structure, and must not be freed or modified by the caller.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1156 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_javascript_w_scope ( const bson_cursor *  c,
const gchar **  js,
bson **  scope 
)

Get the value stored at the cursor, as javascript code w/ scope.

Parameters:
cis the cursor pointing at the appropriate element.
jsis a pointer to a variable where the javascript code can be stored.
scopeis a pointer to a variable where the scope can be stored.
Note:
The scope pointer will be a newly allocated, finished BSON object: it is the responsibility of the caller to free it.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1182 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_oid ( const bson_cursor *  c,
const guint8 **  dest 
)

Get the value stored at the cursor, as an ObjectID.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be set to point to an internal structure, and must not be freed or modified by the caller.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1100 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_regex ( const bson_cursor *  c,
const gchar **  regex,
const gchar **  options 
)

Get the value stored at the cursor, as a regexp.

Parameters:
cis the cursor pointing at the appropriate element.
regexis a pointer to a variable where the regex can be stored.
optionsis a pointer to a variable where the options can be stored.
Note:
Both the regex and options pointers will be set to point to an internal structure, and must not be freed or modified by the caller.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1141 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_string ( const bson_cursor *  c,
const gchar **  dest 
)

Get the value stored at the cursor, as string.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be set to point to an internal structure, and must not be freed or modified by the caller.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1007 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_get_symbol ( const bson_cursor *  c,
const gchar **  dest 
)

Get the value stored at the cursor, as a symbol.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Note:
The dest pointer will be set to point to an internal structure, and must not be freed or modified by the caller.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1169 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_timestamp ( const bson_cursor *  c,
gint64 *  dest 
)

Get the value stored at the cursor, as a timestamp.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1226 of file bson.c.

Here is the call graph for this function:

gboolean bson_cursor_get_utc_datetime ( const bson_cursor *  c,
gint64 *  dest 
)

Get the value stored at the cursor, as an UTC datetime.

Parameters:
cis the cursor pointing at the appropriate element.
destis a pointer to a variable where the value can be stored.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 1126 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

const gchar* bson_cursor_key ( const bson_cursor *  c)

Determine the name of the current elements key.

Parameters:
cis the cursor pointing at the appropriate element.
Returns:
The name of the key, or NULL on error.
Note:
The name is a pointer to an internal string, one must NOT free it.

Definition at line 989 of file bson.c.

bson_cursor* bson_cursor_new ( const bson *  b)

Create a new cursor.

Creates a new cursor, and positions it to the beginning of the supplied BSON object.

Parameters:
bis the BSON object to create a cursor for.
Returns:
A newly allocated cursor, or NULL on error.

Definition at line 786 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

gboolean bson_cursor_next ( bson_cursor *  c)

Position the cursor to the next key.

Parameters:
cis the cursor to move forward.
Returns:
TRUE on success, FALSE otherwise.

Definition at line 863 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

bson_type bson_cursor_type ( const bson_cursor *  c)

Determine the type of the current element.

Parameters:
cis the cursor pointing at the appropriate element.
Returns:
The type of the element, or BSON_TYPE_NONE on error.

Definition at line 971 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

const gchar* bson_cursor_type_as_string ( const bson_cursor *  c)

Retrieve the type of the current element, as string.

Parameters:
cis the cursor pointing at the appropriate element.
Returns:
The type of the element, as string, or NULL on error.
Note:
The string points to an internal structure, it should not be freed or modified.

Definition at line 980 of file bson.c.

Here is the call graph for this function:

bson_cursor* bson_find ( const bson *  b,
const gchar *  name 
)

Create a new cursor positioned at a given key.

Creates a new cursor, and positions it to the supplied key within the BSON object.

Parameters:
bis the BSON object to create a cursor for.
nameis the key name to position to.
Returns:
A newly allocated cursor, or NULL on error.

Definition at line 955 of file bson.c.

Here is the call graph for this function:

Here is the caller graph for this function:

 All Data Structures Files Functions Variables Enumerations Enumerator Defines