transforms.rb in xi-lang-0.1.4

- old
+ new

@@ -289,10 +289,11 @@
 
       # Scale from one range of values to another range of values
       #
       # @example
       #   peek [0,2,4,1,3,6].p.scale(0, 6, 0, 0x7f)
+      #     #=> [(0/1), (127/3), (254/3), (127/6), (127/2), (127/1)]
       #
       # @param min_from [Numeric]
       # @param max_from [Numeric]
       # @param min_to [Numeric]
       # @param max_to [Numeric]
@@ -300,31 +301,69 @@
       #
       def scale(min_from, max_from, min_to, max_to)
         normalize(min_from, max_from).denormalize(min_to, max_to)
       end
 
-      # TODO Document
+      # Slows down a pattern by stretching start and duration of events
+      # +num+ times.
+      #
+      # It is the inverse operation of #accelerate
+      #
+      # @example
+      #   peek_events %w(a b c d).p([1/4, 1/8, 1/6]).decelerate(2)
+      #     #=> [E["a",0,1/2], E["b",1/2,1/4], E["c",3/4,1/3], E["d",13/12,1/2]]
+      #
+      # @param num [Numeric]
+      # @return [Pattern]
+      # @see #accelerate
+      #
       def decelerate(num)
         Pattern.new(self) { |y|
           each_event { |e| y << E[e.value, e.start * num, e.duration * num] }
         }
       end
 
-      # TODO Document
+      # Advance a pattern by shrinking start and duration of events
+      # +num+ times.
+      #
+      # It is the inverse operation of #decelerate
+      #
+      # @example
+      #   peek_events %w(a b c d).p([1/2, 1/4]).accelerate(2)
+      #     #=> [E["a",0,1/4], E["b",1/4,1/8], E["c",3/8,1/4], E["d",5/8,1/8]]
+      #
+      # @param num [Numeric]
+      # @return [Pattern]
+      # @see #decelerate
+      #
       def accelerate(num)
         Pattern.new(self) { |y|
           each_event { |e| y << E[e.value, e.start / num, e.duration / num] }
         }
       end
 
       # Based on +probability+, it yields original value or nil
-      # TODO Document
       #
+      # +probability+ can also be an enumerable or a *finite* Pattern. In this
+      # case, for each value in +probability+ it will enumerate original
+      # pattern based on that probability value.
+      #
+      # @example
+      #   peek (1..6).p.sometimes        #=> [1, nil, 3, nil, 5, 6]
+      #   peek (1..6).p.sometimes(1/4)   #=> [nil, nil, nil, 4, nil, 6]
+      #
+      # @example
+      #   peek (1..6).p.sometimes([0.5, 1]), 12
+      #     #=> [1, 2, nil, nil, 5, 6, 1, 2, 3, 4, 5, 6]
+      #
+      # @param probability [Numeric, #each] (default=0.5)
+      # @return [Pattern]
+      #
       def sometimes(probability=0.5)
         prob_pat = probability.p
 
-        if times_pat.infinite?
+        if prob_pat.infinite?
           fail ArgumentError, 'times must be a finite pattern'
         end
 
         Pattern.new(self, size: size * prob_pat.reduce(:+)) do |y|
           prob_pat.each do |prob|
@@ -332,12 +371,26 @@
           end
         end
       end
 
       # Repeats each value +times+
-      # TODO Document
       #
+      # +times+ can also be an enumerable or a *finite* Pattern.  In this case,
+      # for each value in +times+, it will yield each value of original pattern
+      # repeated a number of times based on that +times+ value.
+      #
+      # @example
+      #   peek [1, 2, 3].p.repeat_each(2)   #=> [1, 1, 2, 2, 3, 3]
+      #   peek [1, 2, 3].p.repeat_each(3)   #=> [1, 1, 1, 2, 2, 2, 3, 3, 3]
+      #
+      # @example
+      #   peek [1, 2, 3].p.repeat_each([3,2]), 15
+      #     #=> [1, 1, 1, 2, 2, 2, 3, 3, 3, 1, 1, 2, 2, 3, 3]
+      #
+      # @param times [Numeric, #each]
+      # @return [Pattern]
+      #
       def repeat_each(times)
         times_pat = times.p
 
         if times_pat.infinite?
           fail ArgumentError, 'times must be a finite pattern'
@@ -346,9 +399,56 @@
         Pattern.new(self, size: size * times_pat.reduce(:+)) do |y|
           times_pat.each do |t|
             each { |v| t.times { y << v } }
           end
         end
+      end
+
+      # Choose items from the list randomly, +repeats+ number of times
+      #
+      # @see Pattern::Generators::ClassMethods#rand
+      #
+      # @example
+      #   peek [1, 2, 3].p.rand             #=> [2]
+      #   peek [1, 2, 3, 4].p.rand(6)       #=> [1, 3, 2, 2, 4, 3]
+      #
+      # @param repeats [Fixnum, Symbol] number or inf (default: 1)
+      # @return [Pattern]
+      #
+      def rand(repeats=1)
+        P.rand(self, repeats)
+      end
+
+      # Choose randomly, but only allow repeating the same item after yielding
+      # all items from the list.
+      #
+      # @see Pattern::Generators::ClassMethods#xrand
+      #
+      # @example
+      #   peek [1, 2, 3, 4, 5].p.xrand    #=> [4]
+      #   peek [1, 2, 3].p.xrand(8)       #=> [1, 3, 2, 3, 1, 2, 3, 2]
+      #
+      # @param repeats [Fixnum, Symbol] number or inf (default: 1)
+      # @return [Pattern]
+      #
+      def xrand(repeats=1)
+        P.xrand(self, repeats)
+      end
+
+      # Shuffle the list in random order, and use the same random order
+      # +repeats+ times
+      #
+      # @see Pattern::Generators::ClassMethods#shuf
+      #
+      # @example
+      #   peek [1, 2, 3, 4, 5].p.xrand    #=> [4]
+      #   peek [1, 2, 3].p.xrand(8)       #=> [1, 3, 2, 3, 1, 2, 3, 2]
+      #
+      # @param repeats [Fixnum, Symbol] number or inf (default: 1)
+      # @return [Pattern]
+      #
+      def shuf(repeats=1)
+        P.shuf(self, repeats)
       end
     end
   end
 end