~

Single element consructor

Double element consructor

Multi element consructor

Get void instance

Alias for join

Creates a new Stream with given element appended to current Stream

  ((1 <> 5).~ + 99 + 100).tp

  // Output
  ~(1, 2, 3, 4, 5, 99, 100)

Alias for joinAll

Creates a new Stream with given elements appended to current Stream

  (('1' <> '9').~ ++ ('a' <> 'd') ++ ('A' <> 'D')).tp

  // Output
  ~(1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, A, B, C, D)

Alias for joinAllAt

Creates a new Stream with given elements inserted into current Stream at given index

If index is out of range, the elements are prepended or appended

   (('a' <> 'f').~ ++@ (3, 'X' <> 'Z')).tp

   // Output
   ~(a, b, c, X, Y, Z, d, e, f)

Alias for joinAt

Creates a new Stream with given element inserted into current Stream at given index

If index is out of range, the element is prepended or appended

 (('a' <> 'd').~ +@ (2, 'X')).tp

  // Output
  ~(a, b, X, c, d)

Pack

Returns stream elements as Pack

Average

Computes average

For empty Stream returns zero value

   (10 <> 15).~.map(_.Float).average  // Returns 12.5

Note: average is available for types providing given ~~.Custom.Math.Average implementations, which are by default Double, Float and opaque numerics based on Double and Float

Average option

Computes average or returns void option for empty stream

   (10 <> 15).~.map(_.Float).average_?  // Returns Opt(12.5)

Note: average_? is available for types providing given ~~.Custom.Math.Average implementations, which are by default Double, Float and opaque numerics based on Double and Float

Multi average

Simultaneously computes up to 5 average values for properties specified by functions

Returns tuple of appropriate size with values corresponding to the given mappings

For empty Stream returned tuple will hold zeros

   (1 <> 1000).~.averageFew(_ * 10F, _ * 100F).tp  // Prints (5005, 50050)

    val (first, second, third) = (1 <> 1000).~.averageFew(v => v.Double, _ * 10.0, _ * 100.0)

    first.tp     // Prints 5005
    second.tp    // Prints 5005
    third.tp     // Prints 5005

Note: Averages areavailable for types providing given Stream.Custom.Average implementations, which are by default Double, Float and opaque numerics based on Double and Float

Partial map

Creates a new Stream by applying a partial function to all elements of current Stream on which the function is defined.

(0 <>> 26).~.collect{
 case i if(i%2==0) => ('a' + i).Char
}.tp

// Output
~(a, c, e, g, i, k, m, o, q, s, u, w, y)

Note:

• collect is functionally similar to map_?, which is prefferable in most cases.
• 'partialMap' would be a better name for this operation, but 'collect' is an established Scala convention.

Value check

Returns true if stream contains given value.

Conditional count

Counts all stream elements, which satisfy given predicate

All count

Counts all stream elements

Count and time

Returns all elements count and Time.Length it took to pump the stream

  val (cnt,time) = (1 <> 1000).~.peek(_ => J.sleep(1.Millis)).countAndTime

  ("" + cnt + " elements processed in " + time.tag).tp

  // Output
  1000 elements processed in 1.488880500 sec

Multi count

Simultaneously counts values for up to 5 different predicates

Returns tuple of appropriate size with values corresponding to the given mappings

For empty Stream returned tuple will hold zeros

val (large, odd, even) = (1 <>> 1000).~.countFew(_ > 100, _ % 2 == 0, _ % 2 == 1)

large.tp    // Prints 899
odd.tp      // Prints 499
even.tp     // Prints 500

Default element

If current Stream is empty, the given element will be appended

Otherwise current Stream will not change

 (1 <>> 1).~.default(99).tp // Prints ~(99)

 (1 <>> 5).~.default(99).tp // Prints ~(1, 2, 3, 4)

Default info

Creates default Info object describing current stream

 ('a' <> 'z').~.defaultDoc.tp

 // Output
scalqa.def.char.g.stream.Z$Stream_fromRange@8bm3{raw=Char,size=26}

Note. Streams may provide custom Able.Info implementations, extending defaultDoc

Text description

Returns a tree formatted text describing all stream trasformations

('a' <> 'z').~
 .map(_.Int)
 .take(_ % 2 == 0)
 .describe.tp

// Output
scalqa.def.int.g.Stream$TakeStream$2@4ds1{raw=Int}
 scalqa.def.char.z.stream.map$Ints@j38c{raw=Int,fromRaw=Char,size=26}
   scalqa.def.char.Z$Stream_fromRange@gw1k{raw=Char,size=26,from=a,step=1}

Pump stream out

Fetches and discards all stream elements

This operation can be usefull for side effects built into streaming pipeline

 ('A' <> 'C').~.peek(_.tp).drain

 // Output
 A
 B
 C

Heavy reversed filter

Disallows Stream elements satisfying the given function

DROP is functionally equivalent to drop, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Reverse filter

Disallows Stream elements satisfying the given function

  (0 <>> 10).~.drop(_ > 5).tp

  // Output
  ~(0, 1, 2, 3, 4, 5)

Note: Scala equivalent is called "filterNot"

Range reversed filter

Only allows elements outside specified sequencial range

  ('a' <> 'f').~.drop_<>(2 <> 3).tp

  // Output
  ~(a, b, e, f)

Note: Sequence indexing starts from 0

Multi element reversed filter

Only lets elements not found in given stream

  ('a' <> 'z').~.dropAll('c' <> 'x') .tp       // Prints ~(a, b, y, z)

Multi element mapped reversed filter

Only lets elements, which mapped value is not found in given stream

  ('a' <> 'z').~.dropAllBy(_.Int % 10, ~~(1,3,7,4,6)).tp

  // Output
  ~(b, c, d, f, i, l, m, n, p, s, v, w, x, z)

Every Nth element reversed filter

Drops every nTh element

  (1 <> 10).~.dropEvery(3).tp   // Prints: ~(1, 2, 4, 5, 7, 8, 10)

Head reversed filter

Drops given number of first elements

  (1 <> 10).~.dropFirst(3).tp  // Prints  ~(4, 5, 6, 7, 8, 9, 10)

Tail reversed filter

Drops given number of elements coming last

  (1 <> 10).~.dropLast(3).tp  // Prints  ~(1, 2, 3, 4, 5, 6, 7)

Note: This method will block on unlimited streams

Single value reversed filter

Drops only specified value.

  (1 <> 4).~.dropOnly(3).tp

  // Output
  ~(1, 2, 4)

Note: dropOnly is more efficient than general filter, because there is no function involved.

Duplicates reversed filter

Drops elements equal to passed in prior position

Note: To generally get rid of all duplicates, the stream must be sorted to arrange duplicates in sequence

Mapped duplicates reversed filter

Drops elements, which evaluate to the same value as elements passed in prior position

Note: To generally get rid of all duplicates, the stream must be sorted by the mapping function

  (1 <> 100).~.dropSameBy(_.toString.length).tp

  // Output
  ~(1, 10, 100)

Void value reversed filter

Drops elements which test to be void

Coditional reversed head filter

Discards first consecutive elements satisfying the condition

  def stream = (1 <> 5).~ ++ (1 <> 5)

  stream.tp                     // Prints ~(1, 2, 3, 4, 5, 1, 2, 3, 4, 5)

  stream.dropWhile(_ <= 3).tp   // Prints ~(4, 5, 1, 2, 3, 4, 5)

Note: Everything starting from the first non compliant element will be allowed (including later compliant elements)

Enables preview capabilities

Returns Stream.Preview, which allows to pre-load and inspect elements, even before they are read

  def strm : ~[String] = ???

  if(strm.enablePreview.previewSize > 1000) "Stream is over 1K".TP

Adds sizing information

If Stream already has sizing, this method is a simple cas t, otherwise, the elements might be buffered and counted.

Equal check

Iterates both streams and compares all corresponding elements

Returns true if all are equal, `false`` otherwise

Equal check

Iterates both streams and compares all corresponding elements

When first not equal pair is found, the problem result is returned

If all elements are equal, Result[true] is returned

(0 <> 10).~.equalsAll_??(0 <> 10).tp
// Prints: Result(true)

(0 <> 10).~.equalsAll_??(0 <>> 10).tp
// Prints: Result(Problem(Second stream has less elements))

((0 <> 5).~ + 7 + 8).equalsAll_??(0 <> 10).tp
// Prints: Result(Problem(Fail at index 6: 7 != 6))

Note: The returned problem contains message with basic description

Equal start check

Checks if starting elements of two streams (to a point where one stream ends) are equal

Equal start check

Checks if starting elements of two streams (to a point where one stream ends) are equal

(0 <> 10).~.equalsStart_??(0 <> 1000).tp
// Prints: Result(true)

(0 <> 1000).~.equalsStart_??(0 <> 10).tp
// Prints: Result(true)

((0 <> 5).~ + 7 + 8).equalsStart_??(0 <> 10).tp
// Prints: Result(Problem(Fail at index 6: 7 != 6))

Note: The returned problem result contains message with basic description

Exists check

Returns true if there is an elemnet satisfying given predicate

Legacy filter

Filters Stream elements according to given function

  (0 <>> 10).~.filter(_ > 5).tp

  // Output
  ~(6, 7, 8, 9)

Note: take is usually used instead.

Find value

Finds the first value accepted by given predicate

 (1 <> 1000).~.find(_ > 100).tp  // Prints 101

Note: If value is not found find fails, use find_? in most cases

Optional find value

Finds the first value accepted by given predicate or returns void option if not found

(1 <> 1000).~.find_?(_ > 100).tp   // Prints Opt(101)

(1 <> 10).~.find_?(_ > 100).tp     // Prints Opt(\/)

Find index

Optionally returns index for the first element satisfying the predicate or Int.Opt(/) if none found

  (50 <> 500).~.findPosition_?(_ == 400)  // Retuns Int.Opt(350)

Heavy flat map

FLAT_MAP is functionally equivalent to flatMap, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Flat map

Creates a new Stream by applying given function to all elements of current Stream and concatenating the results

(1 <> 3).~.flatMap(i => ~~(i, i*10, i*100)).tp

// Output
~(1, 10, 100, 2, 20, 200, 3, 30, 300)

Converts a stream of streams into a flat stream

val vs: ~[~[Char]] = ~~(
  'a' <> 'd',
  Pack('x', 'y', 'z'),
  Vector('v', 'e', 'c', 't', 'o', 'r'))

vs.flatten.tp // Prints ~(a, b, c, d, x, y, z, v, e, c, t, o, r)

Fold

Folds elements with a binary function

    // Calculate sum of first 1000 Ints

    (1 <> 1000).~.fold(0)(_ + _) // Returns 500500

Heavy Fold

Folds elements with a binary function

FOLD is functionally equivalent to fold, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Heavy Fold and convert

Folds and converts elements with a binary function

FOLD_AS is functionally equivalent to foldAs, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Fold and convert

Folds and converts elements with a binary function

    // Calculate sum of first 1000 Ints

    (1 <> 1000).~.foldAs(0L)(_ + _) // Returns 500500

Heavy process stream

Applies given function to each stream element

FOREACH is functionally equivalent to foreach, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Process stream

Applies given function to each stream element

 ('A' <> 'C').~.foreach(_.tp)

 // Output
 A
 B
 C

For each indexed

Calls given function with counter

 ('A' <> 'C').~.foreachIndexed((i,v) => "Element " + i + " = " + v tp(), 1)

 // Output
 Element 1 = A
 Element 2 = B
 Element 3 = C

Run for nonexistent value

Runs given function only if stream is empty.

This operation is rarely useful and is provided for consistency.

Use peekEmpty instead, it can be combined with other processing

Constructor from Enumeration

Explicit constructor from Iterable

Note: There is also global implicit conversion from Iterable to Stream

Explicit constructor from IterableOnce

Note: There is also global implicit conversion from IterableOnce to Stream

Explicit constructor from Iterator

Note: There is also global implicit conversion from Iterator to Stream

Constructor from Product

Constructor from Spliterator

Group by test

Puts elements in the same group based on a function test for every two consecutive elements

   // Putting Ints into groups of 3

   (0 <> 20).~.group(_ / 3 == _ / 3).print

   // Output
   ---------------
   ?
   ---------------
   ~(0, 1, 2)
   ~(3, 4, 5)
   ~(6, 7, 8)
   ~(9, 10, 11)
   ~(12, 13, 14)
   ~(15, 16, 17)
   ~(18, 19, 20)
   ---------------

Simple grouping

Puts consecutive elements in the same group if they are equal

   def stream =  ~~(1, 2, 3).repeat(3)

   stream.tp           // Prints ~(1, 1, 1, 2, 2, 2, 3, 3, 3)

   stream.group.print  // Prints  ------------
                                ?
                                ------------
                                ~(1, 1, 1)
                                ~(2, 2, 2)
                                ~(3, 3, 3)
                                ------------

Note: Non consecutive equal elements will end up in different groups. Prior ordering might be needed

Grouping on properties

Puts consecutive elements in the same group if all the specified properties are equal

When properties change, a new group is started

    ('#' <> '|').~.groupBy(_.isLetter, _.isDigit).print

   // Output
   ---------------------------------------------------------------------------------
   ?
   ---------------------------------------------------------------------------------
   ~(#, $, %, &, ', (, ), *, +, ,, -, ., /)
   ~(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
   ~(:, ;, <, =, >, ?, @)
   ~(A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)
   ~([, \, ], /\, _, `)
   ~(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, p, t, u, v, w, x, y, z)
   ~({, ~)
   ---------------------------------------------------------------------------------

Fixed size groups

Puts consecutive elements into fixed size groups

('a' <> 'z').~.groupEvery(8).print

// Output
-------------------------
?
-------------------------
~(a, b, c, d, e, f, g, h)
~(i, j, k, l, m, n, o, p)
~(q, r, p, t, u, v, w, x)
~(y, z)
-------------------------

Grouping on a property

Puts consecutive elements in the same group if their properties are equal

  (0 <> 20).~.groupWith(_ / 3).print

  // Output
  -- -------------
  _1 _2
  -- -------------
  0  ~(0, 1, 2)
  1  ~(3, 4, 5)
  2  ~(6, 7, 8)
  3  ~(9, 10, 11)
  4  ~(12, 13, 14)
  5  ~(15, 16, 17)
  6  ~(18, 19, 20)
  -- -------------

Note: groupWith also returns the groupped property value (unlike groupBy)

Loose size information

Many streams return ''sizeLong_?'', knowing their current size

hideSizeData drops sizing information, so some optimizations will not be available

This is primarily for testing and debugging

Forall check

Returns true if every single element satisfies the given predicate

Iterator view

Wraps current stream as scala.collection.Iterator

Join element

Creates a new Stream with given element appended to current Stream

  (1 <> 5).~.join(99).join(100).tp

  // Output
  ~(1, 2, 3, 4, 5, 99, 100)

Join all

Creates a new Stream with given elements appended to current Stream

  ('1' <> '9').~.joinAll('a' <> 'd').joinAll('A' <> 'D').tp

  // Output
  ~(1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, A, B, C, D)

Join all at position

Creates a new Stream with given elements inserted into current Stream at given index

If index is out of range, the elements are prepended or appended

   ('a' <> 'f').~.joinAllAt(3, 'X' <> 'Z').tp

   // Output
   ~(a, b, c, X, Y, Z, d, e, f)

Join element at position

Creates a new Stream with given element inserted into current Stream at given index

If index is out of range, the element is prepended or appended

 ('a' <> 'd').~.joinAt(2, 'X').tp

  // Output
  ~(a, b, X, c, d)

Last element

Returns the last stream element

Fails if empty

Last element

Optionally returns the last element or Opt(/)

Preload all

Immediately loads all stream elements into memory, so they are no longer dependent on underlying sources.

  def strm : ~[String] = ???

  strm.load

  // is functionally same as

  strm.toBuffer.~

Convert ot String

The result is a concatenation of all elements with given separator

   ('a' <> 'j').~.makeString()              // Returns abcdefghij

   ('a' <> 'j').~.makeString("|")           // Returns a|b|c|d|e|f|g|h|i|j

Simple map

Creates a new Stream where each element is a result of applying given function to current Stream elements

(0 <>> 26).~.map(i => ('a' + i).Char).tp

// Output
~(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z)

Heavy map

MAP is functionally equivalent to map, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Heavy optional map

MAP_? is functionally equivalent to map_?, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Optional map

Creates a new Stream where each element is a result of applying given function to Stream elements. If the function returns void option, the element is dropped.

(1 <> 10).~.map_?(i => if(i>5) "Str_"+i else \/).tp

// Output
~(Str_6, Str_7, Str_8, Str_9, Str_10)

Pattern matching can be used, but the last void case must always be present:

(0 <>> 26).~.map_?{
 case i if(i%2==0) => ('a' + i).Char
 case _            => \/
}.tp

// Output
~(a, c, e, g, i, k, m, o, q, s, u, w, y)

Note:

• map_? is functionally similar to collect, but is faster (PartialFunction has to be evaluated twice)
• map_? can return specialized stream result, but boxing might happen during mapping
• mapRaw_? is trully unboxed for raw types

Maximum

Computes maximum value

Fails for empty streams

Optional maximum

Computes maximum value or returns void option for empty streams

Maximum by property

Computes maximum value based on given function

Fails for empty streams

Optional maximum by property

Computes maximum value based on given function or returns void option for empty streams

Minimum

Computes minimum value

Fails for empty streams

Optional minimum

Computes minimum value or returns void option for empty streams

Minimum by property

Computes minimum value based on given function

Fails for empty streams

Optional minimum by property

Computes minimum value based on given function or returns void option for empty streams

Non empty option Optionally returns stream, if it is not empty.

Note: If stream does not have sizing information, this method will immediately preload at lease the first element.

Parallel

Returns Stream.Flow with parallel execution

Each consecutive element will be sent to a new thread for processing

  (1 <> 5).~
     .parallel
     .map("Value: " + _ + "\t" + Thread.currentThread.getName)
     .foreach(println)

  // Possible Output
  Value: 1    ForkJoinPool.commonPool-worker-9
  Value: 3    ForkJoinPool.commonPool-worker-11
  Value: 2    main
  Value: 4    ForkJoinPool.commonPool-worker-2
  Value: 5    ForkJoinPool.commonPool-worker-4

Conditionally parallel

Returns Stream.Flow with parallel or sequential implementation, depending on given parameter

   (1 <> 50).~.parallelIf(true).isParallel   // Returns true

   (1 <> 50).~.parallelIf(false).isParallel  // Returns false

Conditionally parallel

Returns Stream.Flow with parallel or sequential implementation, depending on stream having element count equal or greater than given ''threshold''

  (1 <> 50).~.parallelIfOver(100).isParallel   // Returns false

  (1 <> 200).~.parallelIfOver(100).isParallel  // Returns true

Parallel with Priority

This is very expensive operation, because it creates a custom thread pool. It only sutable for long running streams

   (1 <> 100).~.parallelWithPriority(MIN, 4).foreach(v => ())

   (1 <> 100).~.parallelWithPriority(MAX).foreach(v => ())

   (1 <> 100).~.parallelWithPriority(J.Priority(5), 4).foreach(v => ())

Note: parallelism determines how many parallel threads are allowed. Default value is CPU core count minus 1

Predicate grouping

All stream elements are grouped by given predicates, which are applied in sequence. Thus if an element is accepted into a group, it will not be evaluated by the rest of the filters.

The resulting stream size will be equal to the number of predicates plus one. The last group will hold spill over elements, not accepted by any predicate. Groups can be empty.

val ~~(odd,even) = (1 <> 10).~.partition(_ % 2 == 1)

odd.tp
even.tp

// Age groups
(1 <> 80).~.partition(_ <= 12, _ in 13 <> 19, _ < 30, _ in 30 <> 40, _ < 50, _ < 65).print

// Output
~(1, 3, 5, 7, 9)
~(2, 4, 6, 8, 10)

-------------------------------------------------------------------
?
-------------------------------------------------------------------
~(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
~(13, 14, 15, 16, 17, 18, 19)
~(20, 21, 22, 23, 24, 25, 26, 27, 28, 29)
~(30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40)
~(41, 42, 43, 44, 45, 46, 47, 48, 49)
~(50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64)
~(65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80)
-------------------------------------------------------------------

Inspect

The given function will be run with every passing stream element.

  (1 <> 5).~.peek(_.tp).drain

  // Output
  1
  2
  3
  4
  5

Peek empty

The given function is executed once, only if stream is empty

  (1 <> 10).~.drop(_ > 0).peekEmpty("Stream is empty".tp).drain

  // Output
  Stream is empty

Peek end

The given function is executed once, when stream is exhausted

The function receives total element count and Time.Length, it took for all elements to pass

  (1 <> 10).~
    .peek(_ => J.sleep(100.Millis))
    .peekEnd((cnt,time) => "Elements: "+cnt+"  total time: "+time.tag tp())
    .drain

  // Output
  Elements: 10  total time: 0.904106700 sec

Note: This will not run for empty streams

Custom events

Allows to setup Stream.Custom.Events multiple monitoring events

 (1 <> 1000).~
   .peek(_ => J.sleep(5.Millis))
   .peekEvents(e => {
     e.onBeforeFirst(t   => "Started at: "+ t.dayTime.tag tp())
     e.onEvery(1.Second, (c,t) => "  Processed "+c+" in "+t.tag tp())
     e.onAfterLast((c,t) => "Finished in: "+ t.tag + ",  Element count: " + c tp())
   })
   .drain

 // Output

 Started at: 14:05:39.333
   Processed 187 in 1.018583400 sec
   Processed 371 in 2.020508100 secs
   Processed 557 in 3.021843300 secs
   Processed 743 in 4.023837400 secs
   Processed 928 in 5.026982 secs
 Finished in: 5.411673300 secs, Element count: 1000

Indexed peek

The given function will be executed with every passing element and its index.

  ('a' <> 'f').~.peekIndexed((i,c) => (""+i+" : "+c).tp, 1).drain

  // Output
  1 : a
  2 : b
  3 : c
  4 : d
  5 : e
  6 : f

Note. By default indexing starts with 0, but it can be specified

Custom monitor

Adds pre-build Stream.Custom.Event.Monitor

If passed monitor tests to be void (.isEmpty), the operation is ignored

Peek start

The given function is executed once, just before the first elements is about to pass.

  ('a' <> 'f').~.peekStart(time => "Started at: "+time).drain

Note: This will not run for empty streams

Print to console

Prints stream elements in a table like structure

Tuples, case classes, products, and Able.Info object properties are formatted as table columns

('A' <> 'F').~.map(v => (v.Int, v)).print

// Output
-- --
_1 _2
-- --
65 A
66 B
67 C
68 D
69 E
70 F
-- --

// -----------------------------------------------------
case class Case(int: Int, name: String, odd: Boolean):
    def this(i: Int) = this(i, "Name"+i, i%2==0)

(1 <> 10).~.map(new Case(_)).print

// Output
--- ------ -----
int name   odd
--- ------ -----
1   Name1  false
2   Name2  true
3   Name3  false
4   Name4  true
5   Name5  false
6   Name6  true
7   Name7  false
8   Name8  true
9   Name9  false
10  Name10 true
--- ------ -----

Print to console with rows numbered

Same as regular print, but with added row number as first column

('A' <> 'F').~.map(v => (v.Int, v)).print_#

// Output
-- -- --
#  _1 _2
-- -- --
0  65 A
1  66 B
2  67 C
3  68 D
4  69 E
5  70 F
-- -- --

Note: Number is mostly usefull for longer or even infinite streams

Print to console with rows indexed

Same as regular print, but with added index as first column identifying the object

('A' <> 'F').~.map(v => (v.Int, v)).print

// Output
----------------- -- --
Id                _1 _2
----------------- -- --
scala.Tuple2@dzkr 65 A
scala.Tuple2@zn1  66 B
scala.Tuple2@71j3 67 C
scala.Tuple2@562u 68 D
scala.Tuple2@c8tt 69 E
scala.Tuple2@p0m8 70 F
----------------- -- --

Process elements or empty case

Applies given function to each stream element or runs second function when stream is empty

 ('A' <>> 'A').~.process(_.tp, "Empty".tp)

 // Output
 Empty

Range

Computes value range

Fails for empty streams

Optional range

Computes value value or returns void option for empty streams

Specialized stream

Converts current stream into specialized on underlying primitive data. If stream is already specialized, the conversion is a simple cas t.

   val s  : ~[Int] = 1 <> 10

   val ss : Int.~  = s.raw

Note: If underlying type is not primitive, the method will not compile

Next element

Delivers next stream element

 val s : ~[Char] = 'A' <> 'Z'

 s.read.tp  // Prints A
 s.read.tp  // Prints B
 s.read.tp  // Prints C

Note: If stream is empty, read will fail. So, use a safer read_? in most cases

Read many elements

Immediatelly removes given number of elements from current stream and returns them as a new stream

 val s : ~[Int] = 1 <> 12

 s.read_~(3).tp  // Prints ~(1, 2, 3)
 s.read_~(4).tp  // Prints ~(4, 5, 6, 7)
 s.read_~(7).tp  // Prints ~(8, 9, 10, 11, 12)
 s.read_~(8).tp  // Prints ~()

Note: If requested number of elements is not available, the number returned is less (0 if empty)

Next optional element

Delivers next stream element or void option if stream is empty

 val s : ~[Char] = 'A' <> 'C'

 s.read_?.tp  // Prints Opt(A)
 s.read_?.tp  // Prints Opt(B)
 s.read_?.tp  // Prints Opt(C)
 s.read_?.tp  // Prints Opt(\/)

Reduce

Folds elements with a binary function

   // Calculate sum of first 1000 Ints

   (1 <> 1000).~.reduce(_ + _) // Returns 500500

Note. Threre is no default value, and if stream is empty, operation fails. Use reduce_? as safer option

Heavy reduce

Folds elements with a binary function

REDUCE is functionally equivalent to reduce, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Optional reduce

Folds elements with a binary function or returns empty option when stream is empty

    // Calculate sum of first 1000 Ints

    (1 <> 1000).~.reduce_?(_ + _) // Returns Opt(500500)

Heavy optional reduce

Folds elements with a binary function

REDUCE_? is functionally equivalent to reduce_?, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Generalize

If stream is specialized it will be up-ca st to general Val.Stream type, so further operations will be general (unless they are specialized, like map)

  val special : Int.><  = (1 <> 10).~.><

  val general : ><[Int] = (1 <> 10).~.ref.><

  special.getClass.tp // Prints class scalqa.def.int.g.Pack

  general.getClass.tp // Prints class scalqa.val.pack.z.ArrayPack

Note: This is a true zero cost operation. It does not change byte code (only compiler context)

Repeat elements

Creates a new Stream where each elements from current Stream is repeated given number of times

 (0 <> 2).~.repeat(3).tp

 // Output
 ~(0, 0, 0, 1, 1, 1, 2, 2, 2)

Reverse order

Re-arranges all elements is reverse order

('A' <> 'F').~.reverse.tp  // Prints ~(F, E, D, C, B, A)

Reverse order in segments

Reverses order of elements within segments of fixed size

(1 <> 15).~.reverseEvery(5).tp

(1 <> 15).~.reverseEvery(5).reverseEvery(3).reverseEvery(7).tp

// Output
~(5, 4, 3, 2, 1, 10, 9, 8, 7, 6, 15, 14, 13, 12, 11)

~(7, 2, 1, 10, 5, 4, 3, 12, 11, 6, 15, 14, 9, 8, 13)

Use Case: Predefined Shuffle

For testing purposes it is often required to get elements in random order. However the order cannot be completely random, if we want to replicate bugs

reverseEvery can shuffle elements in a predefined order which looks random

Randomize order

Re-arranges elements is random order

Optional size

Many streams can return their current element count. If the information is not available, void option is returned

Note: If size is known, but exceeds integer range, void option is returned. For theses cases use sizeLong_?

 var s = ('a' <> 'z').~

 s.size_?.tp         // Prints Int.Opt(26)

 s = s.take(_ > 10)  // static sizing is lost

 s.size_?.tp         // Prints Int.Opt(\/)

Optional long size

Many streams can return their current element count. If the information is not available, void option is returned

var s = (Int.min.Long <> Int.max.Long).~

s.sizeLong_?.tp    // Prints Long.Opt(4294967296)

s = s.take(_ > 10) // static sizing is lost

s.sizeLong_?.tp    // Prints Long.Opt(\/)

Sliding group view

Example: group size 3 with step 1

 ('a' <> 'g').~.sliding(3).print

 // Output
 ----------
 ?
 ----------
 ~(a, b, c)
 ~(b, c, d)
 ~(c, d, e)
 ~(d, e, f)
 ~(e, f, g)
 ----------

Example: group size 4 with step 2

 ('a' <> 'g').~.sliding(4,2).print

 // Output
 -------------
 ?
 -------------
 ~(a, b, c, d)
 ~(c, d, e, f)
 ~(e, f, g)
 -------------

Sort

Sorts stream elements with given Ordering

  ~~(5, 1, 4, 2, 3).sort.tp  // Prints ~(1, 2, 3, 4, 5)

Sort by three properties

Sorts stream on first property, then if indeterminate on second, etc...

Sort by two properties

Sorts stream on first property, and then, if indeterminate on second

Sort by property

Sorts stream of elements based on a single property

  ~~("aaaa", "bb", "ccc", "d").sortBy(_.length).tp

  // Output
  ~(d, bb, ccc, aaaa)

Sort reversed

Reverse sorts stream elements with given Ordering

  ~~(5, 1, 4, 2, 3).sortReversed.tp  // Prints ~(5, 4, 3, 2, 1)

Positional split

Splits Stream at specified positions

val ~~(s1, s2, s3) = (0 <> 20).~.splitAt(5, 15)

s1.tp   // Prints ~(0, 1, 2, 3, 4)
s2.tp   // Prints ~(5, 6, 7, 8, 9, 10, 11, 12, 13, 14)
s3.tp   // Prints ~(15, 16, 17, 18, 19, 20)

Note. The same could be accomplished with read_~

```

val s3 = (0 <> 20).~ val s1 = s3.read_~(5) val s2 = s3.read_~(10) ```

Sum

Calculates sum of all values

For empty stream returns zero

    (1 <> 1000).~.sum.tp // Prints 500500

Optional sum

Calculates sum of all values or returns void option for empty streams

    (1 <> 1000).~.sum_?.tp // Prints Opt(500500)

Multi sum

Simultaneously computes up to 5 sum values for properties specified by given functions

Returns tuple of appropriate size with values corresponding to the given mappings

For empty Stream returned tuple will hold zeros

 (1 <> 1000).~.sumFew(_ * 10, _ * 100).tp  // Prints (5005000, 50050000)

 val (first, second, third) = (1 <> 1000).~.sumFew(v => v, _ * 10, _ * 100)

 first.tp     // Prints 500500
 second.tp    // Prints 5005000
 third.tp     // Prints 50050000

Heavy filter

Filters Stream elements according to given function

TAKE is functionally equivalent to take, but is fully inlined. It makes compiled code larger, but guarantees the best possible performance on large streams.

Main filter

Only takes Stream elements satisfying the given function

  (0 <>> 10).~.take(_ > 5).tp

  // Output
  ~(6, 7, 8, 9)

Note: Traditional method filter is also available and can be used, but take is prefferable in most cases.

Range filter

Only allows elements withing specified sequencial range

  ('a' <> 'z').~.take_<>(1 <> 7).tp

  // Output
  ~(b, c, d, e, f, g, h)

Note: Sequence indexing starts from 0

Multi element filter

Only lets elements equal to the found in given stream

  ('a' <> 'z').~.takeAll(~~('z','x','b')).tp   // Prints ~('b','x','y')

  ('a' <> 'z').~.takeAll('b' <> 'f') .tp       // Prints ~('b','c','d','e','f')

Multi element mapped filter

Only lets elements, which mapped value is found in given stream

  ('a' <> 'z').~.takeAllBy(_.Int % 10, ~~(1,3,7)).tp

  // Output
  ~(a, e, g, k, o, q, u, y)

Every Nth element filter

Only lets every nTh element

  (1 <> 20).~.takeEvery(4).tp   // Prints: ~(4, 8, 12, 16, 20)

Head filter

Only takes given number of first elements

  (1 <> 10).~.takeFirst(3).tp  // Prints  ~(1, 2, 3)

Indexed filter

Only lets elements satisfying the given function, which also accepts element sequential index

  ('a' <> 'z').~.takeIndexed((i, _) => i >= 2 && i <= 7, 1).tp

  // Output
  ~(b, c, d, e, f, g)

Note: By default indexing starts from 0, but starting value can also be explicitly specified.

Tail filter

Only takes given number of elements coming last

  (1 <> 10).~.takeLast(3).tp  // Prints  ~(8, 9, 10)

Note: This method will block on unlimited streams

Single value filter

Filters only specified value.

  (0 <>> 10).~.takeOnly(5).tp

  // Output
  ~(5)

Note: takeOnly is more efficient than general filter, because there is no function involved.

Type filter

Only lets elements of specified type

  ~~(1, '2', "3", new Object(), 0.0).takeType[String].tp  // Prints: ~(3)

Conditional head filter

Only takes first consecutive elements satisfying the condition

  def stream = (1 <> 5).~ ++ (1 <> 5)

  stream.tp                     // Prints ~(1, 2, 3, 4, 5, 1, 2, 3, 4, 5)

  stream.takeWhile(_ <= 3).tp    // Prints ~(1, 2, 3)

Note: Everything starting from the first non compliant element will be discarded (including later compliant elements)

Convert to Array

Returns stream elements as Array

 val a : Array[Int] =  (1 <> 10).~.toArray

Convert to Buffer

Returns stream elements as Buffer

Convert to Idx

Returns stream elements as Idx

Convert to Java Iterator

Wraps current stream as java.util.Iterator

Convert to Java List

Returns stream elements as java.util.List

Convert to Java Spliterator

Wraps current stream as java.util.Spliterator

Convert to Java Stream

Wraps current stream as java.util.stream.Stream

Convert to List

Returns stream elements as scala.collection.immutable.List

Convert to Lookup

Returns a stream of tuples with (Key,Value) pairs as Lookup

val intLookup : Lookup[Int,Char] = ('A' <> 'F').~.zipKey(_.Int).toLookup

intLookup.pair_~.tp   // Prints ~((69,E), (70,F), (65,A), (66,B), (67,C), (68,D))

val charLookup : Lookup[Char,Int] = ('A' <> 'F').~.zipValue(_.Int).toLookup

charLookup.pair_~.tp   // Prints ~((E,69), (F,70), (A,65), (B,66), (C,67), (D,68))

Convert to Product

Returns stream elements as scala.Product

Convert to Seq

Returns stream elements as scala.collection.immutable.IndexedSeq

Convert to unique collection

Returns stream elements as StableSet

Elements as multi-line String

Returns all elements as String formatted table

If elements implement Able.Info, each 'info' property value is placed in a different column

If elements implement scala.Product (like all Tuples), each Product element is placed in a different column

  ('a' <> 'e').~.map(v => (v + "1", v + "2", v + "3", v + "4", v + "5")).tp

  // Output
  -- -- -- -- --
  ?  ?  ?  ?  ?
  -- -- -- -- --
  a1 a2 a3 a4 a5
  b1 b2 b3 b4 b5
  c1 c2 c3 c4 c5
  d1 d2 d3 d4 d5
  e1 e2 e3 e4 e5
  -- -- -- -- --

Convert to Vector

Returns stream elements as scala.collection.immutable.Vector

Transpose

Transposes matrix where rows become columns

 def stream : ~[~[Int]] = ~~(11 <> 15,
                             List(21, 22, 23, 24, 25),
                             Vector(31, 32, 33, 34, 35))

 stream.print

 stream.transpose.print

 // Output
 ---------------------
 ?
 ---------------------
 ~(11, 12, 13, 14, 15)
 ~(21, 22, 23, 24, 25)
 ~(31, 32, 33, 34, 35)
 ---------------------

 -------------
 ?
 -------------
 ~(11, 21, 31)
 ~(12, 22, 32)
 ~(13, 23, 33)
 ~(14, 24, 34)
 ~(15, 25, 35)
 -------------

Lazy generator

Lazily unfolds next stream value with a function taking all prior values

If the given function returns void option, the stream ends

 // Unfolding Fibonacci Sequence

 (0 <> 1).~.unfold(_.takeLast(2).sum).takeFirst(20).tp

 // Output
 ~(0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181)

Note: Method .takeFirst(20) is needed, because otherwise the stream will never end and would be hard to print out

Unzips stream in two

Unzips a stream of tupled values in two

 val pairs = ('a' <> 'g').~.zipValue(_.toUpper).><

 pairs.~.tp  // Prints ~((a,A), (b,B), (c,C), (d,D), (e,E), (f,F), (g,G))

 val (left, right) = pairs.~.unzip

 left.tp   // Prints ~(a, b, c, d, e, f, g)

 right.tp  // Prints ~(G, F, E, D, C, B, A)

Merge

Merges two streams in one, creating tuples of corresponding elements

  (1 <> 100).~.zip('A' <> 'D').tp  // Prints ~((1,A), (2,B), (3,C), (4,D))

If one of the streams is shorter, the excess elements are lost

Merge stream

Merges two streams in one, creating tuples of corresponding elements

If one of the streams is shorter, the provided defaults are used. If the default is not available, operation fails

  ('a' <> 'f').~.zip('A' <> 'H', '?', '?').tp

  // Output
  ~((a,A), (b,B), (c,C), (d,D), (e,E), (f,F), (?,G), (?,H))

Merges current folding value

(1 <> 7).~.zipFoldAs(0L)(_ + _).print

// "Running Total" Output
-- --
?  ?
-- --
1  1
2  3
3  6
4  10
5  15
6  21
7  28

Merge number Creates a new Stream with elements paired with their sequential position Note: Index is the first element in the resulting tuples.

   ('A' <> 'F').~.zipIndex('A'.toInt) tp  // Prints Stream((65,A), (66,B), (67,C), (68,D), (69,E), (70,F))

Merge index

Creates a new Stream with elements paired with their sequential position, starting at 0

  ('A' <> 'F').~.zipIndex.tp

  // Output

  ~((0,A), (1,B), (2,C), (3,D), (4,E), (5,F))

Note: Index is the first element in the resulting tuples

Merge property first

Creates a new Stream with elements paired with their property, defined by given function

The paired value is in the first tuple position

  ('A' <> 'F').~.zipKey(_.Int).tp  // Prints ~((65,A), (66,B), (67,C), (68,D), (69,E), (70,F))

Merge with next

Creates new Stream with elements paired with the optional next element

  (1 <> 5).~.zipNext.tp  // Prints ~((1,Opt(2)), (2,Opt(3)), (3,Opt(4)), (4,Opt(5)), (5,Opt(\/)))

Merge with prior

Creates new Stream with elements paired with the optional prior element

  (1 <> 5).~.zipPrior.tp  // Prints ~((Opt(\/),1), (Opt(1),2), (Opt(2),3), (Opt(3),4), (Opt(4),5))

Merge property

Creates a new Stream with elements paired with their property, defined by given function

The paired value is in the second tuple position

  ('A' <> 'F').~.zipValue(_.Int).tp  // Prints ~((A,65), (B,66), (C,67), (D,68), (E,69), (F,70))