Class Sequence

Base abstract class for VM assisted sequences.

class Sequence

more...

Summary

append()Adds an item at the end of the sequence.
back()Returns the last item in the Sequence.
clear()Removes all the items from the Sequence.
comp()Appends elements to this sequence through a filter.
empty()Checks if the Sequence is empty or not.
first()Returns an iterator to the first element of the Sequence.
front()Returns the first item in the Sequence.
last()Returns an iterator to the last element of the Sequence.
prepend()Adds an item in front of the sequence

Detailed description

Base abstract class for VM assisted sequences.

This class is meant to provide common methods to VM-assisted (that is, language level) sequence classes. You can't derive directly from this class unless you're writing a native module, but you can derive from script-visible classes children of this one.

Methods

append()

Adds an item at the end of the sequence.

Sequence.append( item )

itemThe item to be added.

If the sequence is sorted, the position at which the item is inserted is determined by the internal ordering; otherwise the item is appended at the end of the sequence.

back()

Returns the last item in the Sequence.

Sequence.back( )

Returns:The last item in the Sequence.
Raises:
AccessErrorif the Sequence is empty.

This method overloads the BOM method back. If the Sequence is not empty, it returns the last element.

clear()

Removes all the items from the Sequence.

Sequence.clear( )

comp()

Appends elements to this sequence through a filter.

Sequence.comp( source, [filter] )

sourceA sequence, a range or a callable generating items.
filterA filtering function receiving one item at a time.
Returns:This sequence.

This method adds one item at a time to this Sequence.

If source is a range, (must not be open), all the values generated by the range will be appended, considering range direction and step.

If source is a sequence (array, dictionary, or any other object providing the sequence interface), all the values in the item will be appended to this Sequence.

If source is a callable item, it is called repeatedly to generate the sequence. All the items it returns will be appended, untill it declares being terminated by returning an oob(0). The function is called atomically, so it can't perform coroutine swithces or any form of wait.

If a filter callable is provided, all the items that should be appended are first passed to to it; the item returned by the callable will be used instead of the item provided in source. The filter may return an out of band 1 to skip the item from source, or an out of band 0 to stop the processing altogether. The filter callable receives also the forming sequence as the second parameter so that it account for it or manage it dynamically during the filter step.

For example, the following comprehension creates a dictionary associating a letter of the alphabet to each element in the source sequence, discarding elements with spaces and terminating when a "" mark is found. The filter function uses the second parameter to determine how many items have been added, and return a different element each time.

   dict = [=>].comp(
      // the source
      .[ 'bananas' 'skip me' 'apples' 'oranges' '<end>' 'melons' ],
      // the filter
      { element, dict =>
        if " " in element: return oob(1)
        if "<end>" == element: return oob(0)
        return [ "A" / len(dict), element ]   // (1)
      }
   )

   // (1): "A" / number == chr( ord("A") + number )

This method actually adds each item in the comprehension to the sequence or sequence-compatible item in self. This means that comprehension needs not to be performed on a new, empty sequence; it may be also used to integrate more data in already existing sequences.

empty()

Checks if the Sequence is empty or not.

Sequence.empty( )

Returns:True if the Sequence is empty, false if contains some elements.

first()

Returns an iterator to the first element of the Sequence.

Sequence.first( )

Returns:An iterator.

Returns an iterator to the first element of the Sequence. If the Sequence is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the Sequence.

front()

Returns the first item in the Sequence.

Sequence.front( )

Returns:The first item in the Sequence.
Raises:
AccessErrorif the Sequence is empty.

This method overloads the BOM method front. If the Sequence is not empty, it returns the first element.

last()

Returns an iterator to the last element of the Sequence.

Sequence.last( )

Returns:An iterator.

Returns an iterator to the last element of the Sequence. If the Sequence is empty, an invalid iterator will be returned, but an insertion on that iterator will succeed and append an item to the Sequence.

prepend()

Adds an item in front of the sequence

Sequence.prepend( item )

itemThe item to be added.

If the sequence is sorted, the position at which the item is inserted is determined by the internal ordering; otherwise the item is prepended in front of the sequence.


Made with faldoc 2.1.0