Loading...
Searching...
No Matches
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

## bson_cursor_find()

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

  c | is the cursor to move.
  name | is the key name to position to.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_find_next()

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

  c | is the cursor to move forward.
  name | is the key name to position to.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_free()

void bson_cursor_free | ( | bson_cursor * | c | ) |

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

Parameters

  c | is the cursor to free.

## bson_cursor_get_array()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_binary()

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

  c | is the cursor pointing at the appropriate element.
  subtype | is a pointer to store the binary subtype at.
  data | is a pointer to where the data shall be stored.
  size | is 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.

## bson_cursor_get_boolean()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_get_document()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_double()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_get_int32()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_get_int64()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_get_javascript()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_javascript_w_scope()

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

  c | is the cursor pointing at the appropriate element.
  js | is a pointer to a variable where the javascript code can be stored.
  scope | is 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.

## bson_cursor_get_oid()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_regex()

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

  c | is the cursor pointing at the appropriate element.
  regex | is a pointer to a variable where the regex can be stored.
  options | is 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.

## bson_cursor_get_string()

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

Get the value stored at the cursor, as string.

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_symbol()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is 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.

## bson_cursor_get_timestamp()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_get_utc_datetime()

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

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

Parameters

  c | is the cursor pointing at the appropriate element.
  dest | is a pointer to a variable where the value can be stored.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_key()

const gchar * bson_cursor_key | ( | const bson_cursor * | c | ) |

Determine the name of the current elements key.

Parameters

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

## bson_cursor_new()

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

  b | is the BSON object to create a cursor for.

Returns
  A newly allocated cursor, or NULL on error.

## bson_cursor_next()

gboolean bson_cursor_next | ( | bson_cursor * | c | ) |

Position the cursor to the next key.

Parameters

  c | is the cursor to move forward.

Returns
  TRUE on success, FALSE otherwise.

## bson_cursor_type()

bson_type bson_cursor_type | ( | const bson_cursor * | c | ) |

Determine the type of the current element.

Parameters

  c | is the cursor pointing at the appropriate element.

Returns
  The type of the element, or BSON_TYPE_NONE on error.

## bson_cursor_type_as_string()

const gchar * bson_cursor_type_as_string | ( | const bson_cursor * | c | ) |

Retrieve the type of the current element, as string.

Parameters

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

## bson_find()

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

  b | is the BSON object to create a cursor for.
  name | is the key name to position to.

Returns
  A newly allocated cursor, or NULL on error.