blob::iter - Blob - Iterator base class, common API
Welcome to the Blob project, written by Andreas Kupries.
For availability please read Blob - How To Get The Sources.
While this package, from its name, looks like the public entrypoint of iterators over blob stores, it is not. This package is internal, providing the base class for all the others implementing actual iterator backends.
The following sections are of interest only to developers intending to extend or modify the system, then. Everybody else can skip this document.
This section lists and describes all the public methods of a proper and functional blob iterator. Some of them may have to be implemented by the derived class for a specific kind of storage.
Note further that not all of the public methods are for general use.
This method associates the property_value with the blob specified by its uuid. The result of the method is the empty string. An error is thrown if the uuid is already associated with a value. This means that each uuid can only be associated with a single value, although each value can have multiple uuids associated with it.
This method removes the specified uuids from the iterator. The result of the method is the empty string. Unknown uuids are ignored. If a removed uuid is the current uuid the iterator is stepped forward to the next entry in sequence, as per the iterator's direction and ordering configuration.
This method removes all uuid from the iterator. After the call the instance is empty. The result of the method is the empty string.
This is an abstract method. Derived classes have to implement it.
This method is a bulk variant of add, see above. It expects a list of (uuid,value) pairs as argument and makes the necessary associations.
The result of the method is the empty string. An error is thrown if any of the specified uuids is already associated with a value, before any changes are made.
This method resets the cursor of the iterator to the start position (as per the direction/ordering of the iterator). The result of the method is an empty string.
This is an abstract method. Derived classes have to implement it.
This method reverses the direction of the iterator. The result of the method is an empty string.
This is an abstract method. Derived classes have to implement it.
This method moves the cursor forward by n entries, in the current direction. The result of the method is a boolean value which indicates if the step moved beyond the end of the iterator (true), or not (false). The step-length n must be an integer > 0.
This is an abstract method. Derived classes have to implement it.
This method moves the cursor backward by n entries, against the current direction. The result of the method is a boolean value which indicates if the step moved before the start of the iterator (true), or not (false). The step-length n must be an integer > 0.
This is an abstract method. Derived classes have to implement it.
This method moves the cursor of the iterator to the specified absolute location. See method location below for the method which returns such locations, and their format.
This is an abstract method. Derived classes have to implement it.
This method sets the direction of iterator relative to the sorting order of the values. The possible arguments are increasing and descreasing. The result of the method is the empty string.
This is an abstract method. Derived classes have to implement it.
This method locates the value associated with uuid and returns it as its result. An error is thrown if uuid is not known to the instance.
This method returns a boolean value indicating if the uuid is known to the iterator (true), or not (false).
This is an abstract method. Derived classes have to implement it.
This method determines the number of uuid/value associations stored in the iterator and returns that number as the result of the method.
This is an abstract method. Derived classes have to implement it.
This method takes the n entries of the iterator starting at the cursor and going forward, and retrurns them as its result. The result is a list of entries, each entry represented by a (uuid,value) pair. The entries are stored in the order they were taken from the iterator.
The cursor is not moved. This is the responsibility of the methods next and previous.
This is an abstract method. Derived classes have to implement it.
This method determines the current direction of the iterator relative to the sort order and returns it as its result. The two possible results are increasing and decreasing
This is an abstract method. Derived classes have to implement it.
This method determines the location of the cursor and returns it as its result. The format of the result is a pair of values, a location code, and details, in this order. The possible location codes are
The cursor is before the start of the content. The detail value is the empty string.
The cursor is behind the end of the content. The detail value is the empty string.
The cursor is at a specific entry in the iterator. The detail value specifies that entry. It is a pair denoting the current property value, and the uuid, in this order.
This is an abstract method. Derived classes have to implement it.
This method retrieves the iterator content and returns it as a list of (uuid,value)-pairs. This is the same format as taken by method data! as input.
This is an abstract method. Derived classes have to implement it.
This method copies the contents of the instance to the iterator instance dst. Any preexisting content of the destination instance is replaced with the information from this iterator. The targeted instance has to support the methods reset, clear, direction!, data!, and to. The result of the method is the empty string.
This method copies the contents of iterator src to this iterator. Any preexisting content of this iterator is replaced with the information from the source. The source instance has to support the methods direction, data, and location. The result of the method is the empty string.
This section lists and describes all the methods a derived class has to override to be a proper and functional blob store. This is not quite a subset of the methods listed in the Public API above, because it also contains a number of private and semi-private methods.
These are the public methods a derived class has to implement to become a functional blob store. Their detailed descriptions can be found in section Public API above.
This method is used by the standard implementation of method add to associates the value with the blob specified by its uuid. The method does not have to concern itself with validation of its uuid argument. This has been done already by the caller.
The derived class has to implement it and return an empty string.
This method is used by the standard implementation of method get to locate the value associated with uuid. The method does not have to concern itself with validation of its uuid argument. This has been done already by the caller.
The derived class has to implement it and return the value associated with the uuid.
This method is used by the standard implementation of method remove to remove the uuid and its value from the iterator. The method does not have to concern itself with validation of its uuid argument. This has been done already by the caller.
The derived class has to implement it and return the empty string.
This method is used by the standard implementation of method remove to determine if the uuid is at the current location of the cursor.
The derived class has to implement it and return a boolean value. true if uuid is at the current cursor lcoation, and false otherwise.
Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Blob Tickets.
Please also report any ideas you may have for enhancements of either package(s) and/or documentation.
Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries