# Wrapper for `mongoc_cursor_t`.
#
# `mongoc_cursor_t` provides access to a MongoDB query cursor.
# It wraps up the wire protocol negotation required to initiate a query and
# retreive an unknown number of documents.
#
# Cursors are lazy, meaning that no network traffic occurs until the first call
# to mongoc_cursor_next().
#
# At that point we can:
# * Retreive more records with repeated calls to `mongoc_cursor_next()`.
# * Test for more records with `mongoc_cursor_more()`.
# * Retrieve the document under the cursor with `mongoc_cursor_current()`.
#
# See [`mongoc_cursor_t`](http://api.mongodb.org/c/current/mongoc_cursor_t.html).
extern class NativeMongoCursor `{ mongoc_cursor_t* `}

	# Wrapper for `mongoc_cursor_current()`.
	#
	# Fetches the cursors current document or NULL if there has been an error.
	fun current: NativeBSON `{
		// As said in documentation, BSON objects should not be freed manually.
		bson_t* bson = (bson_t*) mongoc_cursor_current(self);
		// Copy BSON so we can let the GC free it automatically.
		return bson_copy(bson);
	`}

	# Wrapper for `mongoc_cursor_next()`.
	#
	# This function shall iterate the underlying cursor, setting `current` to the next
	# document.
	#
	# This function is a blocking function.
	fun next: Bool `{
		const bson_t *doc;
		return mongoc_cursor_next(self, &doc);
	`}

	# Wrapper for `mongoc_cursor_destroy()`.
	#
	# This instance should not be used beyond this point!
	fun destroy `{ mongoc_cursor_destroy(self); `}
end