org.osgl.util

Interface C.Traversable<T>

Type Parameters:

T - The element type

All Superinterfaces:

C.Featured, Iterable<T>

All Known Subinterfaces:

C.List<T>, C.ListOrSet<T>, C.Range<ELEMENT>, C.ReversibleSequence<T>, C.Sequence<T>, C.Set<T>

All Known Implementing Classes:

C.Array, CompositeList, FastStr, IntRange, LazyRange, ListBase, Osgl.Val, Osgl.Var, SequenceBase, SetBase, Str, StrBase, TraversableBase

Enclosing class:

C

public static interface C.Traversable<T>
extends Iterable<T>, C.Featured

Define a traversable structure with functional programming support, including map, reduce etc.

Nested Class Summary

Nested classes/interfaces inherited from interface org.osgl.util.C.Featured

C.Featured.Factory

Method Summary

Modifier and Type	Method and Description
C.Traversable<T>	accept(Osgl.Function<? super T,?> visitor) Iterate this Traversable with a visitor function.
boolean	allMatch(Osgl.Function<? super T,Boolean> predicate) Check if all elements match the predicate specified
boolean	anyMatch(Osgl.Function<? super T,Boolean> predicate) Check if any elements matches the predicate specified
C.Traversable<T>	each(Osgl.Function<? super T,?> visitor) Alias of accept(Osgl.Function)
C.Traversable<T>	eager() Returns this traversable and turn off C.Feature.LAZY
C.Traversable<T>	filter(Osgl.Function<? super T,Boolean> predicate) Returns an new traversable that contains all elements in the current traversable except that does not pass the test of the filter function specified.
Osgl.Option<T>	findOne(Osgl.Function<? super T,Boolean> predicate) Returns an element that matches the predicate specified.
<R> C.Traversable<R>	flatMap(Osgl.Function<? super T,? extends Iterable<? extends R>> mapper) Returns a traversable consisting of the results of replacing each element of this stream with the contents of the iterable produced by applying the provided mapping function to each element.
C.Traversable<T>	forEach(Osgl.Function<? super T,?> visitor) Alias of accept(Osgl.Function)
boolean	isEmpty() Is this traversal empty?
C.Traversable<T>	lazy() Returns this traversable and try to turn on C.Feature.LAZY.
<R> C.Traversable<R>	map(Osgl.Function<? super T,? extends R> mapper) Returns an new traversable with a mapper function specified.
boolean	noneMatch(Osgl.Function<? super T,Boolean> predicate) Check if no elements matches the predicate specified.
C.Traversable<T>	parallel() Returns this traversable and try to turn on C.Feature.PARALLEL.
Osgl.Option<T>	reduce(Osgl.Func2<T,T,T> accumulator) Performs a reduction on the elements in this traversable, using provided accumulating function.
<R> R	reduce(R identity, Osgl.Func2<R,T,R> accumulator) Performs a reduction on the elements in this traversable, using the provided identity and accumulating function.
C.Traversable<T>	sequential() Returns this traversable and turn off C.Feature.PARALLEL
int	size() Return the size of this traversal

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Methods inherited from interface org.osgl.util.C.Featured

features, is

Method Detail

parallel

C.Traversable<T> parallel()

Returns this traversable and try to turn on C.Feature.PARALLEL. If this traversable does not support C.Feature.PARALLEL then return this traversable directly without any state change

Returns:

this reference with parallel turned on if parallel is supported

sequential

C.Traversable<T> sequential()

Returns this traversable and turn off C.Feature.PARALLEL

Returns:

this reference with parallel turned off

lazy

C.Traversable<T> lazy()

Returns this traversable and try to turn on C.Feature.LAZY. If lazy is not supported then return this traversable directly without any state change

Returns:

this reference with lazy turned on if it is supported

eager

C.Traversable<T> eager()

Returns this traversable and turn off C.Feature.LAZY

Returns:

this reference with lazy turned off

isEmpty

boolean isEmpty()

Is this traversal empty?

Returns:

true if the traversal is empty or false otherwise

Since:

0.2

size

int size()
  throws UnsupportedOperationException

Return the size of this traversal

Returns:

the size of the structure

Throws:

UnsupportedOperationException - if this structure does not support this method

Since:

0.2

map

<R> C.Traversable<R> map(Osgl.Function<? super T,? extends R> mapper)

Returns an new traversable with a mapper function specified. The element in the new traversal is the result of the mapper function applied to this traversal element.

     Traversable traversable = C.list(23, _.NONE, null);
     assertEquals(C.list(true, false, false), traversal.map(_.F.NOT_NULL));
     assertEquals(C.list("23", "", ""), traversal.map(_.F.AS_STRING));
 

For Lazy Traversable, it must use lazy evaluation for this method. Otherwise it is up to implementation to decide whether use lazy evaluation or not

Type Parameters:

R - the element type of the new traversal

Parameters:

mapper - the function that applied to element in this traversal and returns element in the result traversal

Returns:

the new traversal contains results of the mapper function applied to this traversal

Since:

0.2

flatMap

<R> C.Traversable<R> flatMap(Osgl.Function<? super T,? extends Iterable<? extends R>> mapper)

Returns a traversable consisting of the results of replacing each element of this stream with the contents of the iterable produced by applying the provided mapping function to each element. If the result of the mapping function is null, this is treated as if the result is an empty traversable.

Type Parameters:

R - the element type of the the new traversable

Parameters:

mapper - the function produce an iterable when applied to an element

Returns:

the new traversable

Since:

0.2

filter

C.Traversable<T> filter(Osgl.Function<? super T,Boolean> predicate)

Returns an new traversable that contains all elements in the current traversable except that does not pass the test of the filter function specified.

     Traversable traversable = C.list(-1, 0, 1, -3, 7);
     Traversable filtered = traversable.filter(_.F.gt(0));
     assertTrue(filtered.contains(1));
     assertFalse(filtered.contains(-3));
 

Parameters:

predicate - the function that test if the element in the traversable should be kept in the resulting traversable. When applying the filter function to the element, if the result is true then the element will be kept in the resulting traversable.

Returns:

the new traversable consists of elements passed the filter function test

Since:

0.2

reduce

<R> R reduce(R identity,
             Osgl.Func2<R,T,R> accumulator)

Performs a reduction on the elements in this traversable, using the provided identity and accumulating function. This might be equivalent to:

      R result = identity;
      for (T element: this traversable) {
          result = accumulator.apply(result, element);
      }
      return result;
 

The above shows a typical left side reduce. However depending on the implementation, it might choose another way to do the reduction, including reduction in a parallel way

Type Parameters:

R - the type of identity and the return value

Parameters:

identity - the identity value for the accumulating function

accumulator - the function the combine two values

Returns:

the result of reduction

Since:

0.2

reduce

Osgl.Option<T> reduce(Osgl.Func2<T,T,T> accumulator)

Performs a reduction on the elements in this traversable, using provided accumulating function. This might be equivalent to:

      boolean found = false;
      T result = null;
      for (T element: this traversable) {
          if (found) {
              result = accumulator.apply(result, element);
          } else {
              found = true;
              result = element;
          }
      }
      return found ? _.some(result) : _.none();
 

The above shows a typical left side reduction. However depending on the implementation, it might choose another way to do the reduction, including reduction in a parallel way

Parameters:

accumulator - the function takes previous accumulating result and the current element being iterated

Returns:

an option describing the accumulating result or Osgl.none() if the structure is empty

Since:

0.2

allMatch

boolean allMatch(Osgl.Function<? super T,Boolean> predicate)

Check if all elements match the predicate specified

Parameters:

predicate - the function to test the element

Returns:

true if all elements match the predicate

Since:

0.2

anyMatch

boolean anyMatch(Osgl.Function<? super T,Boolean> predicate)

Check if any elements matches the predicate specified

Parameters:

predicate - the function to test the element

Returns:

true if any element matches the predicate

Since:

0.2

noneMatch

boolean noneMatch(Osgl.Function<? super T,Boolean> predicate)

Check if no elements matches the predicate specified. This should be equivalent to:

      this.allMatch(_.F.negate(predicate));
 

Parameters:

predicate - the function to test the element

Returns:

true if none element matches the predicate

Since:

0.2

findOne

Osgl.Option<T> findOne(Osgl.Function<? super T,Boolean> predicate)

Returns an element that matches the predicate specified. The interface does not indicate if it should be the first element matches the predicate be returned or in case of parallel computing, whatever element matches found first is returned. It's all up to the implementation to refine the semantic of this method

Parameters:

predicate - the function map element to Boolean

Returns:

an element in this traversal that matches the predicate or Osgl.NONE if no element matches

Since:

0.2

accept

C.Traversable<T> accept(Osgl.Function<? super T,?> visitor)

Iterate this Traversable with a visitor function. This method does not specify the approach to iterate through this structure. The implementation might choose iterate from left to right, or vice versa. It might even choose to split the structure into multiple parts, and iterate through them in parallel

Parameters:

visitor - a function that apply to element in this Traversable. The return value of the function is ignored

Returns:

this Traversable instance for chained call

Since:

0.2

each

C.Traversable<T> each(Osgl.Function<? super T,?> visitor)

Alias of accept(Osgl.Function)

Parameters:

visitor - the visitor to tranverse the elements

Returns:

this Traversable instance

forEach

C.Traversable<T> forEach(Osgl.Function<? super T,?> visitor)

Alias of accept(Osgl.Function)

Parameters:

visitor - the visitor function

Returns:

this Traversable instance