fancy 0.3.3 → 0.4.0

data/lib/enumerable.fy

@@ -10,6 +10,7 @@ class FancyEnumerable {
 
     Indicates, if a collection includes a given element.
     """
+
     any?: |x| { item == x }
   }
 
@@ -26,6 +27,25 @@ class FancyEnumerable {
     }
   }
 
+  def join: str {
+    """
+    @str Value (usually a @String@) to be used for the joined @String@.
+    @return @String@ containing all elements in @self interspersed with @str.
+
+    Joins a collection with a @String@ between each element, returning a new @String@.
+
+        \"hello, world\” join: \"-\" # => \"h-e-l-l-o-,- -w-o-r-l-d\"
+    """
+
+    s = ""
+    each: |c| {
+      s << c
+    } in_between: {
+      s << str
+    }
+    s
+  }
+
   def any?: condition {
     """
     @condition @Block@ (or @Callable) that is used to check if any element in @self yields true for it.
@@ -57,7 +77,13 @@ class FancyEnumerable {
   }
 
   def find: item {
-    "Returns @nil, if the given object isn't found, or the object, if it is found."
+    """
+    @item Item to be found in @self.
+    @return The first element that is equal to @item or @nil, if none found.
+
+    Returns @nil, if @item (or anything that returns @true when comparing to @item) isn't found.
+    Otherwise returns that element that is equal to @item.
+    """
 
     if: (item is_a?: Block) then: {
       find_by: item
@@ -85,7 +111,12 @@ class FancyEnumerable {
   }
 
   def map: block {
-    "Returns a new @Array@ with the results of calling a given block for every element"
+    """
+    @block A @Block@ that gets called with each element in @self.
+    @return An @Array@ containing all values of calling @block with each element in @self.
+
+    Returns a new @Array@ with the results of calling a given block for every element.
+    """
 
     coll = []
     each: |x| {
@@ -95,7 +126,12 @@ class FancyEnumerable {
   }
 
   def select: condition {
-    "Returns a new @Array@ with all elements that meet the given condition block."
+    """
+    @condition A @Block@ that is used as a filter on all elements in @self.
+    @return An @Array@ containing all elements in @self that yield @true when called with @condition.
+
+    Returns a new @Array@ with all elements that meet the given condition block.
+    """
 
     coll = []
     each: |x| {
@@ -105,7 +141,10 @@ class FancyEnumerable {
   }
 
   def reject: condition {
-    "Returns a new @Array@ with all elements that don't meet the given condition block."
+    """
+    Similar to @select:@ but inverse.
+    Returns a new @Array@ with all elements that don't meet the given condition block.
+    """
 
     coll = []
     each: |x| {
@@ -115,7 +154,17 @@ class FancyEnumerable {
   }
 
   def take_while: condition {
-    "Returns a new @Array@ by taking elements from the beginning as long as they meet the given condition block."
+    """
+    @condition A @Block@ that is used as a condition for filtering.
+    @return An @Array@ of all elements from the beginning until @condition yields @false.
+
+    Returns a new @Array@ by taking elements from the beginning
+    as long as they meet the given condition block.
+
+    Example:
+        [1,2,3,4,5] take_while: |x| { x < 4 } # => [1,2,3]
+    """
+
     coll = []
     each: |x| {
       if: (condition call: [x]) then: {
@@ -128,7 +177,14 @@ class FancyEnumerable {
   }
 
   def drop_while: condition {
-    "Returns a new @Array@ by skipping elements from the beginning as long as they meet the given condition block."
+    """
+    Similar to @take_while:@ but inverse.
+    Returns a new @Array@ by skipping elements from the beginning
+    as long as they meet the given condition block.
+
+    Example:
+        [1,2,3,4,5] drop_while: |x| { x < 4 } # => [4,5]
+    """
 
     coll = []
     drop = nil
@@ -137,7 +193,7 @@ class FancyEnumerable {
       if: (drop or: first_check) then: {
         drop = condition call: [x]
         first_check = nil
-        # check, if we actually have to insert his one:
+        # check, if we actually have to insert this one:
         unless: drop do: {
           coll << x
         }
@@ -149,6 +205,14 @@ class FancyEnumerable {
   }
 
   def take: amount {
+    """
+    @amount Amount of elements to take from @self.
+    @return First @amount elements of @self in an @Array@.
+
+    Example:
+        [1,2,3,4] take: 2 # => [1,2]
+    """
+
     i = 0
     take_while: {
       i = i + 1
@@ -157,6 +221,14 @@ class FancyEnumerable {
   }
 
   def drop: amount {
+    """
+    @amount Amount of elements to skip in @self.
+    @return An @Array@ of all but the first @amount elements in @self.
+
+    Example:
+        [1,2,3,4,5] drop: 2 # => [3,4,5]
+    """
+
     i = 0
     drop_while: {
       i = i + 1
@@ -165,7 +237,13 @@ class FancyEnumerable {
   }
 
   def reduce: block init_val: init_val {
-    "Calculates a value based on a given block to be called on an accumulator value and an initial value."
+    """
+    Calculates a value based on a given block to be called on an accumulator
+    value and an initial value.
+
+    Example:
+        [1,2,3] reduce: |sum val| { sum + val } init_val: 0 # => 6
+    """
 
     acc = init_val
     each: |x| {
@@ -176,13 +254,25 @@ class FancyEnumerable {
 
   def inject: val into: block {
     """
-    Same as reduce:init_val: but taking the initial value as first and the reducing block as second parameter.
+    Same as reduce:init_val: but taking the initial value as first
+    and the reducing block as second parameter.
+
+    Example:
+        [1,2,3] inject: 0 into: |sum val| { sum + val } # => 6
     """
+
     reduce: block init_val: val
   }
 
   def uniq {
-    "Returns a new Array with all unique values (double entries are skipped)."
+    """
+    @return @Array@ of all unique elements in @self.
+
+    Returns a new Array with all unique values (double entries are skipped).
+
+    Example:
+        [1,2,1,2,3] uniq # => [1,2,3]
+    """
 
     uniq_vals = []
     each: |x| {
@@ -194,7 +284,11 @@ class FancyEnumerable {
   }
 
   def size {
-    "Returns the size of an Enumerable."
+    """
+    @return Amount of elements in @self.
+
+    Returns the size of an Enumerable.
+    """
 
     i = 0
     each: |x| {
@@ -204,18 +298,32 @@ class FancyEnumerable {
   }
 
   def empty? {
-    "Indicates, if the Enumerable is empty (has no elements)."
+    """
+    @return @true, if size of @self is 0, @false otherwise.
+
+    Indicates, if the Enumerable is empty (has no elements).
+    """
+
     size == 0
   }
 
   def first {
+    """
+    @return First element in @self or @nil, if empty.
+    """
+
     each: |x| {
       return x
     }
+    nil
   }
 
   def last {
-    "Returns the last element in an Enumerable."
+    """
+    @return Last element in @self or @nil, if empty.
+
+    Returns the last element in an Enumerable.
+    """
 
     item = nil
     each: |x| {
@@ -225,34 +333,105 @@ class FancyEnumerable {
   }
 
   def compact {
-    "Returns a new @Array@ with all values removed that are @nil ( return @true on @nil? )."
+    """
+    @return @Array@ with all non-nil elements in @self.
+
+    Returns a new @Array@ with all values removed that are @nil ( return @true on @nil? ).
+
+    Example:
+        [1,2,nil,3,nil] compact # => [1,2,3]
+    """
 
     reject: |x| { x nil? }
   }
 
-  def superior_by: comparison_block {
-    "Returns the superiour element in the @Enumerable that has met the given comparison block with all other elements."
+  def superior_by: comparison_block taking: selection_block ('identity) {
+    """
+    @comparison_block @Block@ to be used for comparison.
+    @selection_block @Block@ to be used for selecting the values to be used for comparison by @comparison_bock.
+    @return Superior element in @self in terms of @comparison_block.
+
+    Returns the superior element in the @Enumerable that has met
+    the given comparison block with all other elements,
+    applied to whatever @selection_block returns for each element.
+    @selection_block defaults to @identity.
+
+    Examples:
+        [1,2,5,3,4] superior_by: '> # => 5
+        [1,2,5,3,4] superior_by: '< # => 1
+        [[1,2], [2,3,4], [], [1]] superior_by: '> taking: 'size # => [2,3,4]
+        [[1,2], [2,3,4], [-1]] superior_by: '< taking: 'first # => [-1]
+    """
+
 
-    retval = first
-    each: |x| {
-      if: (comparison_block call: [x, retval]) then: {
-        retval = x
+    pairs = self map: |val| {
+      (val, selection_block call: [val])
+    }
+
+    retval = pairs first
+    pairs each: |p| {
+      if: (comparison_block call: [p second, retval second]) then: {
+        retval = p
       }
     }
-    retval
+    retval first
   }
 
   def max {
-    "Returns the maximum value in the Enumerable (via the '>' comparison message)."
+    """
+    @return Maximum value in @self.
+
+    Returns the maximum value in the Enumerable (via the '>' comparison message).
+    """
+
     superior_by: '>
   }
 
   def min {
-    "Returns the minimum value in the Enumerable (via the '<' comparison message)."
+    """
+    @return Minimum value in @self.
+
+    Returns the minimum value in the Enumerable (via the '<' comparison message).
+    """
+
     superior_by: '<
   }
 
+  def sum {
+    """
+    Calculates the sum of all the elements in the @Enumerable
+    (assuming them to be @Number@s (implementing '+' & '*')).
+    """
+
+    reduce: '+ init_val: 0
+  }
+
+  def product {
+    """
+    Calculates the product of all the elements in the @Enumerable
+    (assuming them to be @Number@s (implementing @+ & @*)).
+    """
+
+    reduce: '* init_val: 1
+  }
+
+  def average {
+    """
+    @return Average value in @self (expecting @Number@s or Objects implementing @+ and @*).
+    """
+
+    { return 0 } if: (size == 0)
+    sum to_f / size
+  }
+
   def partition_by: block {
+    """
+    @block @Block@ that gets used to decide when to partition elements in @self.
+    @return @Array@ of @Array@s, partitioned by equal return values of calling @block with each element
+
+    Example:
+        0 upto: 10 . partition_by: @{< 3}  # => [[0, 1, 2], [3, 4, 5, 6, 7, 8, 9, 10]]
+    """
     last = block call: [first]
     coll = []
     tmp_coll = []
@@ -269,4 +448,59 @@ class FancyEnumerable {
     coll << tmp_coll
     coll
   }
+
+  def random {
+    """
+    @return Random element in @self.
+    """
+
+    at: (rand(size))
+  }
+
+  def sort_by: block {
+    """
+    @block @Block@ taking 2 arguments used to compare elements in a collection.
+    @return Sorted @Array@ of elements in @self.
+
+    Sorts a collection by a given comparison block.
+    """
+
+    if: (block is_a?: Symbol) then: {
+      sort() |a b| {
+        a receive_message: block . <=> (b receive_message: block)
+      }
+    } else: {
+      sort(&block)
+    }
+  }
+
+  def in_groups_of: size {
+    """
+    @size Maximum size of each group.
+    @return @Array@ of @Array@s with a max size of @size (grouped).
+
+    Example usage:
+        [1,2,3,4,5] in_groups_of: 3 # => [[1,2,3],[4,5]]
+    """
+
+    groups = []
+    tmp = []
+    enum = to_enum
+
+    loop: {
+      size times: {
+        tmp << (enum next)
+      }
+
+      if: (enum ended?) then: {
+        { groups << tmp } unless: $ tmp empty?
+        break
+      }
+
+      groups << tmp
+      tmp = []
+    }
+
+    groups
+  }
 }

data/lib/enumerator.fy

@@ -1,14 +1,44 @@
 class FancyEnumerator {
-  def initialize: @object {
+  def initialize: @collection {
+    """
+    @collection Collection to iterate over.
+
+    Initializes a new FancyEnumerator with a given @collection,
+    using #each: for iteration.
+    """
+
     @iterator = 'each:
     rewind
   }
 
-  def initialize: @object with: @iterator {
+  def initialize: @collection with: @iterator {
+    """
+    @collection Collection to iterate over.
+    @iterator Selector to use to iterate over @collection.
+
+    Initializes a new FancyEnumerator with a given @collection
+    and @iterator selector to be used for iteration.
+    """
+
     rewind
   }
 
   def next {
+    """
+    @return Next element in the collection this enumerator is attached to.
+
+    Returns the next element in the collection this enumerator is attached to.
+    It will move the internal position forward (compared to e.g. #peek, which doesn't).
+
+    Example:
+        a = [1,2,3]
+        e = a to_enum
+        e next # => 1
+        e next # => 2
+        e next # => 3
+        e next # => raises Fancy StopIteration
+    """
+
     if: @peeked then: {
       @peeked = false
       @peek
@@ -22,6 +52,16 @@ class FancyEnumerator {
     }
   }
 
+  def ended? {
+    """
+    @return @true if the enumerator has ended (no more values left), @false otherwise.
+
+    Indicates if an enumerator has ended (no more values left).
+    """
+
+    @fiber alive? not
+  }
+
   def peek {
     """
     Returns the next object in the FancyEnumerator, but doesn't move the
@@ -29,15 +69,16 @@ class FancyEnumerator {
     When the position reaches the end, a Fancy StopIteration exception is
     raised.
 
-    a = [1,2,3]
-    e = a to_enum
-    e next p #=> 1
-    e peek p #=> 2
-    e peek p #=> 2
-    e peek p #=> 2
-    e next p #=> 2
-    e next p #=> 3
-    e next p #=> raises Fancy StopIteration
+    Example:
+        a = [1,2,3]
+        e = a to_enum
+        e next p #=> 1
+        e peek p #=> 2
+        e peek p #=> 2
+        e peek p #=> 2
+        e next p #=> 2
+        e next p #=> 3
+        e next p #=> raises Fancy StopIteration
     """
 
     unless: @peeked do: {
@@ -54,24 +95,90 @@ class FancyEnumerator {
   }
 
   def rewind {
+    """
+    Resets the enumerator to start from the collection's beginning.
+    """
+
     @peeked = false
     @peek = nil
 
     @fiber = Fiber new: {
       param = |element| { yield: element }
-      @object send_message: @iterator with_params: [param]
+      @collection receive_message: @iterator with_params: [param]
     }
   }
 
   def with: object each: block {
+    """
+    @object Object to pass along to @block with each element in the collection.
+    @block A @Block@ to be called with each element in the collection and @object.
+
+    Similar to #each: but also passing in a given @object to each invocation of @block.
+    """
+
+    each: |element| {
+      block call: [element, object]
+    }
+
+    return object
+  }
+
+  def each: block {
+    """
+    @block @Block@ to be called with each element in the collection (iteration).
+
+    Calls a given @Block@ with each element in the collection this enumerator is attached to.
+    Used for iterating over the collection using this enumerator.
+    """
+
     loop: {
       try {
-        block call: [next, object]
+        block call: [next]
       } catch (Fancy StopIteration) => ex {
-        return object
+        return self
       }
     }
+  }
 
-    return object
+  def chunk: block {
+    Generator new: |inner_block| {
+      enums = []
+      last = nil
+      previous = nil
+      stack = []
+
+      each: |element| {
+        result = (block call: [element]) not not
+        if: (previous == result) then: {
+          stack << element
+        } else: {
+          previous if_nil: {
+            # wait one gap to call
+          } else: {
+            inner_block call: [[previous, stack]]
+          }
+          previous = result
+          stack = [element]
+          last = [result, stack]
+          enums << last
+        }
+      }
+
+      self
+    } . to_enum
+  }
+
+  class Generator {
+    def initialize: @block {}
+
+    def each: block {
+      @block call: [block]
+    }
+  }
+
+  def to_a {
+    output = []
+    each: |element| { output << element }
+    output
   }
 }