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
t() :: %ICouch.Collection{byte_size: integer, contents: %{optional(doc_id) => {ICouch.Document.t, meta}}}
Link to this section 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.
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.
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.
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.
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.
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.
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.
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
.
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).
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.
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.
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.
put(coll :: t, ICouch.Document.t | {ICouch.Document.t, meta}) :: t
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.
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.
Warning: if the document does not exist, returns coll
unchanged.
Returns all documents as list.
to_list_meta(coll :: t) :: [ICouch.Document.t]
Returns all documents and meta data as list of tuples.