Home
Getting Started
Current Status
Documentation
- frostc
- Syntax
  - Keywords
  - Statements
    - Assignment
    - Method Calls
    - if
    - for
    - while
    - do
    - loop
    - break
    - continue
    - return
    - assert
    - unreachable
    - match
    - try
  - Expressions
  - Annotations
  - Comments
  - Documentation Comments
  - Error Handling
- Classes
  - Interfaces
  - Choices
  - Values
  - Immutability
  - Packages
    - Uses
  - Generics
  - Bare Code
- Methods
- Fields
- Types
- Variables and Constants
- Memory
  - Weak References
- Threads
API Documentation
- frostcollections Array Collection CollectionView CollectionWriter DefaultHashMap HashKey HashMap HashSet IdentityMap IdentitySet ImmutableArray Iterable Iterator List ListView ListWriter Map MapView MapWriter Stack core Bit Char16 Char32 Char8 Comparable Equatable Error Formattable Immutable Int Int16 Int32 Int64 Int8 Matcher Maybe MutableString Index MutableValue Object Range Real32 Real64 RegularExpression SteppedRange String Index Match System Process UInt UInt16 UInt32 UInt64 UInt8 Value Weak io ByteOrder Console File IndentedOutputStream InputStream LineNumberInputStream MemoryInputStream MemoryOutputStream OutputStream PushbackInputStream math Random XorShift128Plus threads Lock MessageQueue Notifier ScopedLock Thread time Timer unsafe Pointer UnsafeMessageQueue

frost.collections

Interface Iterator<T>

Returns a collection of objects one at a time. Iterators are valid for loop targets.

Source Code:: View Source

Field Summary

done:Bit: True if this iterator has no more elements to return.
enumeration:Iterator<(frost.core.Int, frost.collections.Iterator.T)>: Returns an iterator which reads from this iterator and returns (index, value) tuples.

Inherited Fields:

toString

Instance Method Summary

next():T: Returns the next element from the iterator.
count():Int: Scans through the Iterator until the end, returning the number of elements traversed over.
filter(predicate:(T)=>(Bit)):Iterator<T>: Returns a new Iterator which reads from this Iterator, skipping over values which do not match the predicate.
-- index operator -- [](range:Range<Int?>):Iterator<T>: Returns an Iterator which traverses a subrange of this Iterator.
-- index operator -- [](range:SteppedRange<Int?, Int>):Iterator<T>: As [](Range<Int?>), but additionally handles a step.
all():Array<T>: Scans through the Iterator until the end, collecting all of the traversed elements into an Array.
apply(m:(T)=&>()): Scans through the Iterator until the end, calling the specified method on each object returned.
fold(f:(T, T)=>(T)):T: Successively applies a binary function to 'fold' the elements returned by the iterator down to a single value.
fold(f:(T, T)=>(T), start:T):T: As fold((T, T)=>(T)), but additionally takes a starting value for the fold operation.
map<U>(f:(T)=&>(U)):Iterator<U>: Returns a new iterator which reads from this iterator and applies a method to transform the results.

Fields

property done:Bit

True if this iterator has no more elements to return.

property enumeration:Iterator<(frost.core.Int, frost.collections.Iterator.T)>

Returns an iterator which reads from this iterator and returns (index, value) tuples. For example,

for (i, v) in ["A", "B", "C"].iterator.enumeration {
    Console.printLine("\{i}: \{v}")
}

Try it!

will display:

0: A
1: B
2: C

Instance Methods

@pre(!done)

method next

():T

Returns the next element from the iterator.

@default
@post(get_done())

method count

():Int

Scans through the Iterator until the end, returning the number of elements traversed over.

@default

function filter

(predicate:(T)=>(Bit)
):Iterator<T>

Returns a new Iterator which reads from this Iterator, skipping over values which do not match the predicate. As the new Iterator internally reads from this Iterator, you should not interact with an Iterator after calling filter on it.

Parameters:: predicate - value of type (T)=>(Bit)

-- index operator --
@default
@pre(range.min == null | range.min! >= 0 & range.max == null | range.max! >= 0)

function []

(range:Range<Int?>
):Iterator<T>

Returns an Iterator which traverses a subrange of this Iterator. As the new Iterator internally reads from this Iterator, you should not interact with an Iterator after calling range on it.

Example:

base[..10].map(x => x * x)

Try it!

This produces an iterator which squares the first ten numbers produced by the base iterator.

The range iterator will never read past the end of the base iterator. If the base iterator does not produce enough elements to finish the range, iteration will simply end at that point.

Parameters:: range - value of type Range<Int?>

-- index operator --
@default
@pre(range.start == null | range.start! >= 0 & range.end == null |
                        range.end! >= 0 & range.step > 0)

function []

(range:SteppedRange<Int?, Int>
):Iterator<T>

As [](Range<Int?>), but additionally handles a step.

Example:

for v in arr.iterator[1.. by 2] {
    Console.printLine(v)
}

Try it!

This will loop over every odd-numbered element in arr.

Parameters:: range - value of type SteppedRange<Int?, Int>

@default
@post(done)

method all

():Array<T>

Scans through the Iterator until the end, collecting all of the traversed elements into an Array.

@default
@post(done)

method apply

(m:(T)=&>())

Scans through the Iterator until the end, calling the specified method on each object returned.

For example, to call a method named process on each word in a string:

def words := "This will do something with the words in this string".find(/\w+/)
words.map(m => m.groups[0]).apply(process)

Try it!

Parameters:: m - value of type (T)=&>()

@default
@pre(!done)
@post(done)

method fold

(f:(T, T)=>(T)
):T

Successively applies a binary function to 'fold' the elements returned by the iterator down to a single value. For instance, if we have an Iterator<Int64> and fold it using the binary function Int64.+(Int64), as in:

iter.fold(Int.+)

Try it!

this would add the first and second elements returned by the iterator together, and then add the sum of the first two elements to the third, and so forth until all of the elements had been added together.

Similarly, we could fold using Int64.max(Int64) to find the biggest number returned by the iterator, Int64.*(Int64) to get the product of all of the numbers returned by the iterator, etc.

If the iterator returns only a single element, the result of fold is this single element and the function f is never called. This variant of fold may not be called on an iterator with no remaining elements because the result would be undefined. After calling fold, there will be no more elements remaining.

Parameters:: f - a binary function to combine elements of the iterator

Returns:: the result of combining all elements from the iterator

See also:: fold((T, T)=>(T), T)

@default
@post(done)

method fold

(f:(T, T)=>(T),
 start:T
):T

As fold((T, T)=>(T)), but additionally takes a starting value for the fold operation. The starting value is folded into the first element, the result is then folded into the second element, etc. This allows fold to be well-defined even on an empty iterator: folding an empty iterator simply returns the start value.

Parameters:: f - a binary function to combine elements of the iterator
start - the starting value for the fold

Returns:: the result of combining all elements from the iterator

See also:: fold((T, T)=>(T))

@default

method map<U>

(f:(T)=&>(U)
):Iterator<U>

Returns a new iterator which reads from this iterator and applies a method to transform the results. For instance,

File("/tmp/example").lines().map(line => line.length)

is an iterator which produces the length of each line in a file.

Parameters:: f - value of type (T)=&>(U)