kyanite 0.6.1 → 0.7.0

data/lib/kyanite/array.rb

@@ -1,6 +1,129 @@
 # ruby encoding: utf-8
+#
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
 
-require 'kyanite/array/matrix2' # das ist die oberste Ebene, array2 und array werden ebenfalls required
-require 'kyanite/enumerable/enumerable_enumerables'  
-require 'kyanite/enumerable/enumerable_numerics'  
-require 'kyanite/enumerable/enumerable_strings'  
+require 'facets/array/delete'           # Methoden delete_unless, delete_values, delete_values_at
+require 'facets/array/rotate'           # Methoden rotate, rotate!
+require 'facets/array/select'           # Methode select!
+require 'facets/to_hash'                # Methode to_h (in der Facets-Bibliothek falsch einsortiert?)
+
+require 'kyanite/enumerable/enumerable_enumerables'
+require 'kyanite/enumerable/enumerable_numerics'
+require 'kyanite/enumerable/enumerable_strings'
+require 'kyanite/enumerable'            #  ist eigentlich nicht nötig?
+require 'kyanite/general/object'        # Methode respond
+require 'kyanite/general/classutils'    # <=> für class
+require 'kyanite/symbol'                # size 
+
+
+
+# @!macro array
+#
+# === Required from {http://rubyworks.github.com/rubyfaux/?doc=http://rubyworks.github.com/facets/docs/facets-2.9.3/core.json#api-class-Array Facets Array}:  
+# [+delete_unless(&block)+]         Inverse of +delete_if+
+# [+delete_values(*values)+]        Delete multiple values from array (findet und löscht bestimmte Werte)
+# [+delete_values_at(*selectors)+]  Delete multiple values from array given indexes or index range (löscht Elemente an bestimmten Positionen)
+# [+rotate(n=1)+]                   Rotates an array's elements from back to front n times (alles rückt n Positionen auf)
+# [+select!{ |obj| block }+]        As with +select+ but modifies the Array in place.
+# [+to_h(arrayed=nil)+]             Converts a two-element associative array into a hash. 
+# 
+class Array    
+ 
+  
+  # Cuts the front portion, and returns the rest.
+  # If the remainder is only one element, it' not returned as an array but as single element.
+  # Useful for recursions. Example:  
+  #   [1,2,3].shift_complement  =>  [2,3]
+  #   [1,2,3].shift_complement.shift_complement  =>  3
+  #   [1,2,3].shift_complement.shift_complement.shift_complement  =>  nil
+  #
+  # See tests and examples {TestKyaniteArray#test_array_shift_complement here}.
+  #
+  def shift_complement
+    if self.size > 2
+      self[1..-1]
+    else
+      self[-1]
+    end
+  end
+  
+  
+
+  
+  
+  # Rephrases the index of an Array pos / neg / inv.
+  # [:pos]     The index is rephrased as a positive integer
+  # [:neg]     The index is rephrased as a negative integer 
+  # [:inv]     if it was positive, then it will get negative, and vice versa
+  # 
+  # @return [Integer]
+  #
+  # See tests and examples {TestKyaniteArray#test_rephrase_index here}
+  #
+  def rephrase_index(i, style=:inv)
+    return i    if i >  (size-1)
+    return i    if i <  -size
+    case style
+    when :inv
+          if i >=0    # pos >> neg
+            (i - size)
+          else        # neg >> pos
+            (i + size)
+          end
+    when :pos
+          if i >= 0   # pos bleibt
+            i
+          else        # neg >> pos
+            (i + size)
+          end    
+    when :neg
+          if i >= 0   # pos >> neg
+            (i - size)
+          else        # neg bleibt
+            i
+          end    
+    end #case
+  end #def
+  
+ 
+
+
+end #  class Array         
+
+
+
+
+if defined? TransparentNil
+  class NilClass
+    def shift_complement;               nil;            end  
+  end
+end
+    
+    
+class Numeric
+  # +nil+, Complements {Array#shift_complement}.
+  # @return [NilClass]  
+  def shift_complement 
+    nil
+  end  
+end    
+
+
+
+
+
+    
+    
+    
+    
+
+
+    
+    
+    
+    
+    
+    

data/lib/kyanite/basics.rb

@@ -6,9 +6,7 @@
 # innerhalb von Verzeichnissen
 #
 
-# require 'kyanite/array'   
-  require 'kyanite/array/array'           # aber nicht array2 und matrix2 
-  
+  require 'kyanite/array'    
 # require 'kyanite/general'    
 # require 'kyanite/general/callerutils'
   require 'kyanite/general/classutils'  
@@ -19,16 +17,14 @@
 # require 'kyanite/general/undoable'       
    
   require 'kyanite/numeric'    
-# require 'kyanite/operation'              # nur manuell
   
 # require 'kyanite/string'     
 # require 'kyanite/string/cast'
 # require 'kyanite/string/chars'
 # require 'kyanite/string/diff'
-# require 'kyanite/string/div'
   require 'kyanite/string/include'
 # require 'kyanite/string/list'
-  require 'kyanite/string/mgsub'
+  require 'kyanite/string/misc'
 # require 'kyanite/string/nested'
 # require 'kyanite/string/random'
 # require 'kyanite/string/split'
@@ -48,7 +44,7 @@
 # require 'kyanite/set'  
   require 'kyanite/symbol'  
 # require 'kyanite/tree'  
-# require 'kyanite/unit_test'         # nur für Tests
+
          
 # ----------------------------------------------------------------
 # Außerhalb

data/lib/kyanite/dictionary.rb

@@ -1,4 +1,10 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 require 'hashery' # old: 'facets/dictionary'
 unless defined? ENUMERABLE_REQUIRED
   require 'kyanite/enumerable'             # is_collection? 
@@ -7,16 +13,8 @@ end
 
 
 
-# [ | Kyanite | Object | Array | Set | Enumerable | *Hash* | ]     | Hash |  *Dictionary* |
-# ---
-#  
-#
-# == *Tools* *For* *Facets* *Dictionary*
-# A Dictionary is a ordered Hash. 
-# Expands {Facets/Dictionary}[http://facets.rubyforge.org/doc/api/more/classes/Dictionary.html].
-# See TestKyaniteDictionary for tests and examples.
-#
-#
+
+# @!macro dictionary
 class Dictionary < Hashery::Dictionary
 
   def fetch_by_index(index)
@@ -55,9 +53,11 @@ class Dictionary < Hashery::Dictionary
 end
 
 
+
+
 class Hash
 
-  # TODO: effizienter
+  # @return [Dictionary]
   def to_dictionary
     result = Dictionary.new
       self.each do | key, value |
@@ -71,25 +71,23 @@ end
 
 class Array
 
-  # :section: Cast
-  
-  
-  
-  # Liefert ein Dictionary (das ist ein geordneter Hash)
-  #
-  # TODO: effizienter
+  # @!group Cast
+  # Returns {Dictionary} 
+  # @return [Dictionary]  
   def to_dictionary
+    # TODO: effizienter
     result = Dictionary.new
       self.each do | zeile |
         result << zeile
       end
     result
   end
+  # @!endgroup   
   
   #funktioniert nicht
-  def to_dictionary2 # :nodoc:
-    Dictionary.new(self.flatten)
-  end  
+  # def to_dictionary2 # :nodoc:
+    # Dictionary.new(self.flatten)
+  # end  
   
 end
 

data/lib/kyanite/enumerable/enumerable_enumerables.rb

@@ -1,8 +1,14 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 
 module Enumerable
 
- # In-place-Variante von transpose. 
+ # In-place-variant of +transpose+. 
   def transpose!
       self.replace(self.transpose)
   end    
@@ -10,25 +16,19 @@ module Enumerable
 
 end
 
-# [ | Kyanite | Object | Array | Set | *Enumerable* | Hash | ]     | Enumerable | EnumerableNumerics | EnumerableStrings | *EnumerableEnumerables* | 
-# ---
-#
-#
-# == *Enumeration* *Of* *Enumerations*
-# Für zweidimensionale Enumerables bzw. Aufzählungen von Objekten, die wiederum aufzählbar sind.
-# See TestKyaniteEnumerableEnumerables for tests and examples.
-# See ArrayOfEnumerables for an Array with modul EnumerableEnumerables included. 
-#
-#
+
+
+
+
+# @!macro enum_of_enums
 module EnumerableEnumerables
 
-  # Macht das Enumerable rechteckig.
-  # Maßgeblich ist die erste Zeile.
+  # Makes the Enumerable rectangular (= strict two-dimensional). The first row is essential. 
   #
-  # Tests and examples see TestKyaniteEnumerableEnumerables.
+  # See tests and examples {TestKyaniteEnumerableEnumerables#test_rectangle1 here}.
   def rectangle
     qsize = self[0].size   
-    result = []
+    result = ArrayOfEnumerables.new
     self.each do |zeile|
       size_diff = qsize - zeile.size  
       # so lassen oder zuschneiden      
@@ -46,14 +46,8 @@ end
 
 
 
-# [ | Kyanite | Object | *Array* | Set | Enumerable | Hash | ]     | Array |  ArrayOfNumerics  | ArrayOfStrings |  *ArrayOfEnumerables* | Range |  
-# ---
-#
-#
-# == *Array* *Of* *Enumerations*
-# An ArrayOfEnumerables is an Array with modul EnumerableEnumerables included. 
-# See TestKyaniteEnumerableEnumerables for tests and examples.
-#
+
+# @!macro enum_of_enums
 class ArrayOfEnumerables < Array   
   include EnumerableEnumerables
 end
@@ -61,10 +55,14 @@ end
 
 class Array
 
-  # Liefert ein ArrayOfEnumerables (das ist ein Array mit inkludiertem Modul EnumerableEnumerables)
+  # @!group Cast
+  # Returns {ArrayOfEnumerables} (this is an {Array} with modul {EnumerableEnumerables} included)
+  # @return [ArrayOfEnumerables]    
   def to_array_of_enumerables
     ArrayOfEnumerables.new(self)
   end
+  #@!endgroup
+  
 end
 
 

data/lib/kyanite/enumerable/enumerable_numerics.rb

@@ -1,24 +1,26 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
 
-# [ | Kyanite | Object | Array | Set | *Enumerable* | Hash | ]     | Enumerable | *EnumerableNumerics* | EnumerableStrings | EnumerableEnumerables | 
-# ---
-#
-#
-# == *Enumeration* *Of* *Numerics*
-# See TestKyaniteEnumerableNumerics for tests and examples.
-# See ArrayOfNumerics for an Array with modul EnumerableNumerics included. 
-#
-#
+
+
+
+
+# @!macro enum_of_numerics
 module EnumerableNumerics
 
   
 # ======================================================================================
-# :section: Mittelwerte
+# @!group Mean Values
 #  
 
-  # Arithmetrischer Mittelwert
-  # Tests and examples see TestKyaniteEnumerableNumerics.
-  #    
+  # Arithmetic mean
+  #
+  # Tests and examples {TestKyaniteEnumerableNumerics here}.
+  # @return [Float]   
   def mean
     self.inject(0.0) { |sum, i | sum += i } / self.length.to_f 
   end
@@ -26,15 +28,14 @@ module EnumerableNumerics
   alias average          mean
   alias mean_arithmetric mean
  
-  # Harmonischer Mittelwert
-  #
-  # Normalerweise ist der harmonische Mittelwert nur für positive Zahlen sinnvoll definiert.
-  # Mit der Option <tt>:allow_negative => true </tt>kann man aber auch negative Zahlen mit einbeziehen.
-  # Dann wird der harmonische Mittelwert aller positiven Elemente mit dem 
-  # harmonische Mittelwert aller negativen Elemente verrechnet (als gewichtetes arithmetisches Mittel).
+
+  # Harmonic mean
   #
-  # Tests and examples see TestKyaniteEnumerableNumerics.
-  #    
+  # Usually, the harmonic mean is defined only for positive numbers.
+  # The option <tt>:allow_negative => true </tt> can also include negative numbers in the calculation.
+  # Then the result will be a weighted arithmetic mean of the harmonic mean of all positive elements
+  # and the harmonic mean of all negative elements.
+  # @return [Float]  
   def mean_harmonic( options={} )
     return 0              if self.empty?  
     return self.first     if self.size == 1
@@ -45,8 +46,8 @@ module EnumerableNumerics
       return self.size / summe
       
     else
-      positives = []
-      negatives = []
+      positives = ArrayOfNumerics.new
+      negatives = ArrayOfNumerics.new
       self.each do |e|
         if e >= 0
           positives << e
@@ -70,7 +71,9 @@ module EnumerableNumerics
   end #def 
   
  
-  # Geometrischer Mittelwert 
+
+  # Geometric mean
+  # @return [Float]    
   def mean_geometric
     self.prd ** ( 1.0/self.size ) 
   end  
@@ -78,32 +81,34 @@ module EnumerableNumerics
 
   
 # ======================================================================================
-# :section: Summe, Produkt, Parallelschaltung
+# @!group Sum, Product, Parallel
 #    
   
   
-  # Summe
+  # Sum
   #
-  # Methode darf nicht sum heißen, kollidiert sonst schnell mit ActiveRecord.
-  # Tests and examples see TestKyaniteEnumerableNumerics.
-  #  
+  # Tests and examples {TestKyaniteEnumerableNumerics here}.
+  # @return [Numeric]    
   def summation
+    # Methode darf nicht sum heißen, kollidiert sonst schnell mit ActiveRecord.  
     self.inject(0.0) { |sum, i | sum += i }  
   end  
   
   
-  # Produkt
-  # Methode darf nicht product heißen, die gibt es nämlich schon.
-  # Tests and examples see TestKyaniteEnumerableNumerics.
-  #    
+  # Product
+  #
+  # Tests and examples {TestKyaniteEnumerableNumerics here}.
+  # @return [Numeric]    
   def prd
+    # Methode darf nicht product heißen, die gibt es nämlich schon.  
     self.inject(1.0) { |p, i | p *= i }  
   end    
   
-  
-  # Ergebnis entspricht der Parallelschaltung von Widerständen.
-  # Tests and examples see TestKyaniteEnumerableNumerics.
-  #    
+  # Parallel
+  #
+  # Result is equal to the total resistance of resistors in parallel circuits.
+  # Tests and examples {TestKyaniteEnumerableNumerics here}.
+  # @return [Float]    
   def parallel
     mean_harmonic / size  
   end
@@ -114,14 +119,10 @@ end #class
 
 
 
-# [ | Kyanite | Object | *Array* | Set | Enumerable | Hash | ]     | Array |  *ArrayOfNumerics*  | ArrayOfStrings |  ArrayOfEnumerables | Range | 
-# ---
-#
-#
-# == *Array* *Of* *Numerics*
-# An ArrayOfNumerics is an Array with modul EnumerableNumerics included. 
-# See TestKyaniteEnumerableNumerics for tests and examples.
-#
+
+
+
+# @!macro enum_of_numerics
 class ArrayOfNumerics < Array 
   include EnumerableNumerics
 end
@@ -130,10 +131,13 @@ end
 
 class Array
 
-  # Liefert ein ArrayOfNumerics (das ist ein Array mit inkludiertem Modul EnumerableNumerics)
+  # @!group Cast
+  # Returns {ArrayOfNumerics} (this is an {Array} with modul {EnumerableNumerics} included)
+  # @return [ArrayOfNumerics]  
   def to_array_of_numerics
     ArrayOfNumerics.new(self)
   end
+  #@!endgroup
   
 end
 
@@ -157,9 +161,7 @@ end
 # Ausprobieren
 #
 if $0 == __FILE__ 
-  class Array
-    include EnumerableNumerics
-  end  
+