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

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.

Link to this function

put(coll, doc)

View Source
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.

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.