ICouch v0.6.2 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()
View Sourcet() :: %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, key)
View Sourcedelete(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(collection, doc_id)
View Sourcefetch(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(collection, doc_id)
View Sourcefetch_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(collection, doc_id, default \\ nil)
View Sourceget(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, doc_id, fun)
View Sourceget_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, doc_id, fun)
View Sourceget_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(collection, doc_id, default \\ nil)
View Sourceget_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).
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, key, default \\ nil)
View Sourcepop(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, key, default \\ nil)
View Sourcepop_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, doc)
View Sourceput(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.
put(coll, doc, meta)
View Sourceput(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.
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(collection)
View Sourceto_list_meta(coll :: t()) :: [ICouch.Document.t()]
Returns all documents and meta data as list of tuples.