ICouch v0.5.0 ICouch.Collection View Source

Collection of documents useful for batch tasks.

This module helps collecting documents together for batch uploading. It keeps track of the document byte sizes to allow a size cap and supports replacing a document already in the collection. Furthermore it is possible to associate meta data with documents (e.g. a sequence number).

There are implementations for the Enumerable and Collectable protocol for your convenience.

All functions with the _meta suffix return the document and meta data as 2-tuple, unless otherwise specified.

Link to this section Summary

Functions

Returns the byte size of all documents in the collection as if they were encoded entirely in JSON (including attachments in Base64)

Returns the number of documents in the collection

Deletes a document in coll, referenced by its ID or itself

Returns all document IDs as list

Returns a list of tuples pairing document IDs and their rev values

Returns a list of tuples with document IDs, their rev values and metadata

Returns whether the collection is empty

Fetches the document of a specific doc_id in the given coll

Fetches the document and its meta data for a specific doc_id in the given coll

Gets the document for a specific doc_id in coll

Gets the document for a specific doc_id and updates it, all in one pass

Gets the document and its meta data for a specific doc_id and updates it, all in one pass

Gets the document and its meta data for a specific doc_id in coll

Checks if a document exists within the collection

Initialize a collection struct

Returns and removes a document from coll, referenced by its ID or itself

Returns and removes a document and its meta data from coll, referenced by its ID or itself

Puts a document into the collection, replacing an existing document if needed

Puts a document with meta data into the collection, replacing an existing document and meta data if needed

Replaces meta data of the document specified by doc_id in the collection

Returns all documents as list

Returns all documents and meta data as list of tuples

Link to this section Types

Link to this type doc_rev() View Source
doc_rev() :: String.t | nil
Link to this type t() View Source
t() :: %ICouch.Collection{byte_size: integer, contents: %{optional(doc_id) => {ICouch.Document.t, meta}}}

Link to this section Functions

Link to this function byte_size(collection) View Source
byte_size(coll :: t) :: integer

Returns the byte size of all documents in the collection as if they were encoded entirely in JSON (including attachments in Base64).

Link to this function count(collection) View Source
count(coll :: t) :: integer

Returns the number of documents in the collection.

Link to this function delete(coll, key) View Source
delete(coll :: t, key :: doc_id | ICouch.Document.t) :: t

Deletes a document in coll, referenced by its ID or itself.

If the document does not exist, returns coll unchanged.

Returns all document IDs as list.

Link to this function doc_revs(collection) View Source
doc_revs(coll :: t) :: [{doc_id, doc_rev}]

Returns a list of tuples pairing document IDs and their rev values.

Link to this function doc_revs_meta(collection) View Source
doc_revs_meta(coll :: t) :: [{doc_id, doc_rev, meta}]

Returns a list of tuples with document IDs, their rev values and metadata.

Link to this function empty?(collection) View Source
empty?(coll :: t) :: boolean

Returns whether the collection is empty.

Link to this function fetch(collection, doc_id) View Source
fetch(coll :: t, doc_id) :: {:ok, ICouch.Document.t} | :error

Fetches the document of a specific doc_id in the given coll.

If coll contains the document with the given doc_id, then {:ok, doc} is returned. If coll doesn’t contain the document, :error is returned.

Part of the Access behavior.

Link to this function fetch_meta(collection, doc_id) View Source
fetch_meta(coll :: t, doc_id) ::
  {:ok, {ICouch.Document.t, meta}} |
  :error

Fetches the document and its meta data for a specific doc_id in the given coll.

If coll contains the document with the given doc_id, then {:ok, {doc, meta}} is returned. If coll doesn’t contain the document, :error is returned.

Link to this function get(collection, doc_id, default \\ nil) View Source
get(coll :: t, doc_id, default :: any) ::
  ICouch.Document.t |
  any

Gets the document for a specific doc_id in coll.

If coll contains the document with the given doc_id, then the document is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Part of the Access behavior.

Link to this function get_and_update(coll, doc_id, fun) View Source
get_and_update(coll :: t, doc_id, (ICouch.Document.t | nil -> {get, ICouch.Document.t | {ICouch.Document.t, meta}} | :pop)) :: {get, t} when get: term

Gets the document for a specific doc_id and updates it, all in one pass.

fun is called with the current document under doc_id in coll (or nil if the document is not present in coll) and must return a two-element tuple: the “get” document (the retrieved document, which can be operated on before being returned) and the new document to be stored under doc_id in the resulting new collection. fun may also return :pop, which means the document shall be removed from coll and returned (making this function behave like Collection.pop(coll, doc_id).

The returned value is a tuple with the “get” document returned by fun and a new collection with the updated document under doc_id.

Not that it is possible to return a document plus meta data from fun.

Part of the Access behavior.

Link to this function get_and_update_meta(coll, doc_id, fun) View Source
get_and_update_meta(coll :: t, doc_id, ({ICouch.Document.t, meta} | nil -> {get, ICouch.Document.t | {ICouch.Document.t, meta}} | :pop)) :: {get, t} when get: term

Gets the document and its meta data for a specific doc_id and updates it, all in one pass.

fun is called with the current document and meta data under doc_id in coll (or nil if the document is not present in coll) and must return a two-element tuple: the “get” meta data (the retrieved meta data, which can be operated on before being returned) and the new meta data to be stored under doc_id in the resulting new collection. fun may also return :pop, which means the document shall be removed from coll and its meta data returned (making this function behave like Collection.pop_meta(coll, doc_id).

The returned value is a tuple with the “get” document and meta data returned by fun and a new collection with the updated document and meta data under doc_id.

Link to this function get_meta(collection, doc_id, default \\ nil) View Source
get_meta(coll :: t, doc_id, default) ::
  {ICouch.Document.t, meta} |
  default when default: term

Gets the document and its meta data for a specific doc_id in coll.

If coll contains the document with the given doc_id, then the document and its meta data is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Link to this function member?(arg1, doc1) View Source
member?(coll :: t, doc_id | ICouch.Document.t | {doc_id, doc_rev}) :: boolean

Checks if a document exists within the collection.

If a string is given as parameter, checks if a document with that ID exists. If a 2-tuple of two strings is given, the first element is the document ID and the second element the revision to check. Otherwise a document or a 2-tuple of document and meta data can be given.

Documents are tested using ICouch.Document.equal?/2 if they exist. Meta data is compared using ==.

Initialize a collection struct.

Link to this function pop(coll, key, default \\ nil) View Source
pop(coll :: t, key :: doc_id | ICouch.Document.t, default) :: {ICouch.Document.t | default, t} when default: term

Returns and removes a document from coll, referenced by its ID or itself.

If the document is present in coll, {doc, new_coll} is returned where new_coll is the result of removing the document from coll. If the document is not present in coll, {default, coll} is returned.

Link to this function pop_meta(coll, key, default \\ nil) View Source
pop_meta(coll :: t, key :: doc_id | ICouch.Document.t, default) :: {{ICouch.Document.t, meta} | default, t} when default: term

Returns and removes a document and its meta data from coll, referenced by its ID or itself.

If the document is present in coll, {{doc, meta}, new_coll} is returned where new_coll is the result of removing the document from coll. If the document is not present in coll, {default, coll} is returned.

Puts a document into the collection, replacing an existing document if needed.

Also accepts a 2-tuple of a document and meta data; meta data is set to nil if not given.

Link to this function put(coll, doc, meta) View Source
put(coll :: t, ICouch.Document.t, meta) :: t

Puts a document with meta data into the collection, replacing an existing document and meta data if needed.

Link to this function set_meta(coll, doc_id, meta) View Source
set_meta(coll :: t, doc_id, meta) :: t

Replaces meta data of the document specified by doc_id in the collection.

Warning: if the document does not exist, returns coll unchanged.

Link to this function to_list(collection) View Source
to_list(coll :: t) :: [ICouch.Document.t]

Returns all documents as list.

Link to this function to_list_meta(collection) View Source
to_list_meta(coll :: t) :: [ICouch.Document.t]

Returns all documents and meta data as list of tuples.