gossamer - v8.4.0

gossamer/iterator

Types

Iterator

</>

A pull-based iterator that yields values one at a time. a is the yielded value type, return is the final return value, next is the type of values passed in via next_with.

See Iterator on MDN.

pub type Iterator(a, return, next)

Values

drop

</> 
pub fn drop(
  from iterator: Iterator(a, return, next),
  up_to count: Int,
) -> Iterator(a, Nil, Nil)

Returns a new iterator that skips the first count values from the source iterator, then yields the rest.

every

</> 
pub fn every(
  in iterator: Iterator(a, return, next),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

Consumes the iterator and returns True if the predicate returns True for every value. Short-circuits on the first non-match.

filter

</> 
pub fn filter(
  in iterator: Iterator(a, return, next),
  keeping predicate: fn(a) -> Bool,
) -> Iterator(a, Nil, Nil)

Returns a new iterator that yields only the values from the source iterator for which the predicate returns True.

find

</> 
pub fn find(
  in iterator: Iterator(a, return, next),
  one_that predicate: fn(a) -> Bool,
) -> Result(a, Nil)

Consumes the iterator and returns the first value for which the predicate returns True. Returns an error if no value matches.

flat_map

</> 
pub fn flat_map(
  over iterator: Iterator(a, return, next),
  with callback: fn(a) -> Iterator(b, Nil, Nil),
) -> Iterator(b, Nil, Nil)

Returns a new iterator that applies the callback to each value from the source iterator and yields all values from the resulting iterators.

for

</> 
pub fn for(
  in iterator: Iterator(a, return, next),
  run fun: fn(a) -> any,
) -> Nil

from_list

</> 
pub fn from_list(list: List(a)) -> Iterator(a, Nil, Nil)

Creates an iterator from a Gleam list.

map

</> 
pub fn map(
  over iterator: Iterator(a, return, next),
  with callback: fn(a) -> b,
) -> Iterator(b, Nil, Nil)

Returns a new iterator that yields the results of applying the callback to each value from the source iterator.

new

</> 
pub fn new(
  next: fn(option.Option(next)) -> iterator_result.IteratorResult(
    a,
    return,
  ),
) -> Iterator(a, return, next)

Creates an iterator from a next callback — called each time a value is pulled, producing the next value or signaling done.

next

</> 
pub fn next(
  iterator: Iterator(a, return, next),
) -> iterator_result.IteratorResult(a, return)

Advances the iterator and returns the next result.

next_with

</> 
pub fn next_with(
  iterator: Iterator(a, return, next),
  value: next,
) -> iterator_result.IteratorResult(a, return)

Advances the iterator, passing value to the iterator’s internal logic.

reduce

</> 
pub fn reduce(
  over iterator: Iterator(a, return, next),
  from initial: b,
  with callback: fn(b, a) -> b,
) -> b

Consumes the iterator, calling the reducer with each value and an accumulator. Returns the final accumulator value.

return

</> 
pub fn return(
  iterator: Iterator(a, return, next),
) -> Result(
  iterator_handler_outcome.IteratorHandlerOutcome(a, return),
  js_error.JsError,
)

Ends iteration early by invoking the iterator’s optional return handler. Ok(NoHandler) if the iterator doesn’t define one; Ok(Handled) carries the result the handler produced. Returns an error if the handler throws.

return_with

</> 
pub fn return_with(
  iterator: Iterator(a, return, next),
  value: return,
) -> Result(
  iterator_handler_outcome.IteratorHandlerOutcome(a, return),
  js_error.JsError,
)

Like return, but passes value to the iterator’s return handler. value is discarded if the iterator doesn’t define one.

some

</> 
pub fn some(
  in iterator: Iterator(a, return, next),
  satisfying predicate: fn(a) -> Bool,
) -> Bool

Consumes the iterator and returns True if the predicate returns True for any value. Short-circuits on the first match.

take

</> 
pub fn take(
  from iterator: Iterator(a, return, next),
  up_to limit: Int,
) -> Iterator(a, Nil, Nil)

Returns a new iterator that yields at most limit values from the source iterator.

throw

</> 
pub fn throw(
  iterator: Iterator(a, return, next),
  reason reason: e,
) -> Result(
  iterator_handler_outcome.IteratorHandlerOutcome(a, return),
  js_error.JsError,
)

Signals an error to the iterator by invoking its optional throw handler. Ok(NoHandler) if the iterator doesn’t define one — reason is discarded; the caller must decide whether to propagate. Ok(Handled) carries the result the handler produced. Returns an error if the handler itself throws.

to_list

</> 
pub fn to_list(iterator: Iterator(a, return, next)) -> List(a)

Collects all values from an iterator into a list. Consumes the iterator.

with_return

</> 
pub fn with_return(
  iterator: Iterator(a, return, next),
  return: fn(option.Option(return)) -> iterator_result.IteratorResult(
    a,
    return,
  ),
) -> Iterator(a, return, next)

Adds a return handler to the iterator, called when the consumer ends iteration early. Used to release resources.

with_throw

</> 
pub fn with_throw(
  iterator: Iterator(a, return, next),
  throw: fn(e) -> iterator_result.IteratorResult(a, return),
) -> Iterator(a, return, next)

Adds a throw handler to the iterator, called when the consumer signals an error.

✨ Search Document