kyanite 0.6.1 → 0.7.0

data/lib/kyanite/numeric.rb

@@ -1,4 +1,17 @@
 # ruby encoding: utf-8
 require 'kyanite/numeric/float'
 require 'kyanite/numeric/integer'
-require 'kyanite/numeric/numeric'
+
+
+
+class Numeric
+
+  # +false+, Numerics are not empty.
+  # @return [Boolean]
+  # @private
+  def empty? 
+      false 
+  end  
+  
+   
+end # class

data/lib/kyanite/numeric/float.rb

@@ -1,33 +1,43 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 Infinity = 1.0/0        unless defined? Infinity
 Googol   = 10**100      unless defined? Googol
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | Object | String | Symbol | *Numeric* |  
-# [ ] | Numeric | Integer | *Float* |  
-#
-# ---
-#
-# == *Float* 
-#
-#
+
+
+# @!macro numeric
 class Float
 
-  #  1.9 == 1.8 + 0.1               => false
-  #  1.9.approx(1.8 + 0.1)          => true
-  #  98.6.approx(98.66)             => false
-  #  98.6.approx(98.66, 0.001)      => true
-  # Copyright 2006 O'Reilly Media, Ruby Cookbook, by Lucas Carlson and Leonard Richardson
+  # Fuzzy comparison of Floats. Example:
+  #  (98.6).fuzzy_equal?(98.66)          => false
+  #  (98.6).fuzzy_equal?(98.66, 0.001)   => true
   #
-  def approx(other, relative_epsilon=Float::EPSILON, epsilon=Float::EPSILON)
-    difference = other - self
-    return true if difference.abs <= epsilon
-    relative_error = (difference / (self > other ? self : other)).abs
-    return relative_error <= relative_epsilon
+  # @param other [Float] Value to compare with
+  # @param error_max [Float] Maximum relative error
+  def fuzzy_equal?(other, error_max=0.000001)
+    diff = other - self
+    return true if diff.abs <= Float::EPSILON
+    relative_error = (diff / (self > other ? self : other)).abs
+    #puts relative_error
+    return relative_error <= error_max
   end
-  # http://oreilly.com/catalog/9780596523695/
-  # Ruby Cookbook, by Lucas Carlson and Leonard Richardson
-  # Copyright 2006 O'Reilly Media  
+
 
 
   
-end
+end
+
+# -----------------------------------------------------------------------------------------
+#  ausprobieren
+#
+if $0 == __FILE__ then
+
+  puts (98.6).fuzzy_equal?(98.66)
+  puts (98.6).fuzzy_equal?(98.66, 0.001)
+
+end # if

data/lib/kyanite/numeric/integer.rb

@@ -1,32 +1,24 @@
 # ruby encoding: utf-8
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | Object | String | Symbol | *Numeric* | 
-# [ ] | Numeric | *Integer* | Float |  
-#
-# ---
-#
-# == *Trivial* *Integer* *Methods* 
-#
-#
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
+
+# @!macro numeric
 class Integer
 
-  # Wandelt eine Sekundenzahl-seit-1970 in ein Time-Objekt
+  # Converts a number of seconds-since-1970 in a Time object
+  # @return [Time]  
   def to_time
     return nil if self > 2099999999     # geht leider nur bis ins Jahr 2036 
     ::Time.at(self)                     # ohne die Doppelpunkte sucht Ruby die Methode at in ::Time und wirft einen Error
   end     
   
-  # Rückgabe: self    
-  # Test: TestKyaniteNumeric#test_integer_triviales
-  def to_integer;                     self;            end     
-  
-  
-  # Rückgabe: self    
-  # Test: TestKyaniteNumeric#test_integer_triviales
-  def to_integer_optional;            self;            end  
-  
   
-  # Rückgabe: self    
-  # Test: TestKyaniteNumeric#test_integer_triviales
+    # +self+, you can not dup Integers
+    # @return [self]
   def dup;                            self;            end        
   
 end # class

data/lib/kyanite/optimizer.rb

@@ -1,24 +1,36 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
  
+
+
+
+# @!macro optimizer
+# ==== Example
+#   require 'kyanite/optimizer' 
+#   test = Optimizer.new
+#   test.push  1,  'hello'
+#   test.push  5,  'item'
+#   test.push  6,  'maximum23'
+#   test.push -1,  'minimum'
+#   test.push -1,  'another minimum'  
+#   test.content_max
+#   >= "maximum23"
+#   test.content_min
+#   >= "minimum"
+# More tests and examples {TestKyaniteOptimizer here}. 
 #
-# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]     | Kyanite | TrueClass | FalseClass | NilClass | *Div* | 
-# [ ] | Div | Tree::TreeNode | *Optimizer* | 
-# ---
-#
-# == *Optimizer* 
-# Auswahl von Objekten auf Basis von Scores. See TestKyaniteOptimizer for Tests and examples.
-#
-# Jedes Objekt wird per +push+ in den Optimizer geschrieben. Dabei wird auch sein Score übergeben.
-# +content_max+ bzw. +content_min+ liefern das Objekt mit dem höchsten / niedrigsten Score. 
-# +delete_max+ bzw. +delete_min+ löschen das Objekt mit den höchsten / niedrigsten Score. Dadurch ist auch der Zugriff auf die zweiten und dritten Objekte möglich. 
-#
+class Optimizer < Hash
+
 # Drei Stufen für Marshall sind denkbar:
 # * kein Marshal
 # * Marshal.load(Marshal.dump) beim Schreiben. Dadurch sind Schreibzugriffe teuer, Lesezugriffe aber billig
 # * Marshal.dump beim Schreiben, Marshal.load beim Lesen. Dadurch sind Lese- und Schreibzugriffe teuer, 
 #   die im Optimizer gespeicherten Objekte sind aber abgeschottet und geschützt.
-#
-class Optimizer < Hash
 
 #@@marshal = true
 
@@ -27,24 +39,25 @@ class Optimizer < Hash
   # end
   
   
-  # Liefert den Wert des höchsten Scores.
+
+  # @return [Numeric] Value of maximum score
   def score_max
     return nil  if size == 0  
     keys.max
   end
   
   
-  # Liefert den Wert des niedrigsten Scores.  
+  # @return [Numeric] Value of minimum score
   def score_min
     return nil  if size == 0  
     keys.min
   end  
   
   
-  # Liefert den Content mit dem höchsten Score. Mit
-  # [] content_max(0)      erhält man den ersten Content mit maximalem Score, mit
-  # [] content_max(-1)     den letzten Content mit maximalem Score und mit 
-  # [] content_max(0..-1)  alle Contents mit maximalem Score (dann als Array).
+  # Returns the content with maximum score. 
+  #  content_max(0)      # returns the first content with maximum score
+  #  content_max(-1)     # returns the last content with maximum score  
+  #  content_max(0..-1)  # returns all contents with maximum score (as Array)
   #
   def content_max(range=0..0)
     return nil  if size == 0
@@ -61,7 +74,11 @@ class Optimizer < Hash
   end
   
   
-  # siehe #content_max
+  # Returns the content with minimum score. 
+  #  content_min(0)      # returns the first content with minimum score
+  #  content_min(-1)     # returns the last content with minimum score  
+  #  content_min(0..-1)  # returns all contents with minimum score (as Array)
+  #
   def content_min(range=0..0)
     return nil  if size == 0
     range = (range..range) if range.kind_of?(Fixnum)    
@@ -77,7 +94,7 @@ class Optimizer < Hash
   end 
   
   
-  # Beladen des Optimizers mit Objekten.
+  # Load the optimizer with objects.
   def push( score, content, options={} )
     if self.has_key?(score) 
       self[score] << Marshal.dump(content) 
@@ -87,7 +104,7 @@ class Optimizer < Hash
   end
   
   
-  # Löscht alle Objekte in der Mitte.
+  # Deletes all objects in the middle.
   def cleanup
     return false if size <= 2
     keys.sort[1..-2].each do | key | 
@@ -97,14 +114,14 @@ class Optimizer < Hash
   end
   
   
-  # Löscht das Objekt mit dem niedrigsten Score.   
+  # Deletes the object with the lowest score. 
   def delete_min
     return false if size <= 1
     self.delete(keys.min)
     true
   end  
   
-  # Löscht das Objekt mit dem höchsten Score.     
+  # Deletes the object with the highest score.    
   def delete_max
     return false if size <= 1
     self.delete(keys.max)

data/lib/kyanite/range.rb

@@ -1,46 +1,63 @@
 # ruby encoding: utf-8
-# ü
+# 
 if $0 == __FILE__ 
-  require File.join(File.dirname(__FILE__), '..', '..', 'smart_load_path.rb' )
-  smart_load_path   
+  require 'drumherum'
+  smart_init
 end
+
 require 'facets/range/combine'
 require 'facets/range/within'
-require 'kyanite/enumerable'             # is_collection? ist für Ranges false
+require 'kyanite/enumerable'             # is_collection? ist false for Ranges
 
-# [ | Kyanite | Object | *Array* | Set | Enumerable | Hash | ]     | Array |  ArrayOfNumerics  | ArrayOfStrings |  ArrayOfEnumerables | *Range* |  
-# ---
-#
-#
-# == *Range*
-#
-#
-# Aus {Facets/Range}[http://facets.rubyforge.org/doc/api/core/classes/Range.html] eingefügt:  
-#  umbrella(range)
-#  within?
-#  combine(range)
+
+
+
+# @!macro range
 #
+# === Added from  {http://rubyworks.github.com/rubyfaux/?doc=http://rubyworks.github.com/facets/docs/facets-2.9.3/core.json#api-class-Range Facets Range}:  
+# [+umbrella(range)+] Returns a two element array of the relationship between two Ranges
+# [+within? (range)+] Is another Range anywhere within this Range?
+# [+combine(range)+]  Combine ranges
 #
 class Range
 
-  # Invertiert den Range, mit dem ein Ausschnitt eines Strings oder eines Arrays bestimmt wird.
-  # Liefert einen Range, mit dem der inverse Teil des Strings ausgewählt werden kann.
-  # Beispiele siehe TestKyaniteRange.
+
+  
+  # Given a range for selecting a section of a {String} or an {Array},
+  # +invert_index+ inverts this range, so that the result 
+  # selects the inverse part of the {String} or {Array}. 
+  #
+  # @example 
+  #  # return back 
+  #  (0..5).invert_index
+  #  => (6..-1)
+  #   
+  #  # return front 
+  #  (3..-1).invert_index
+  #  => (0..2)
+  # 
+  #  # return outer
+  #  (2..4).invert_index
+  #  => [0..1,   5..-1]
+  #
+  # Tests and more examples {TestKyaniteRange here}.
   #
+  #
+  # @return [Range] or [Array] of two Ranges
   def invert_index
   
-    # hinteren Teil ausgeben
+    # back
     if first == 0
       return (1..0)           if last == -1     # leer
       return (last+1..-1)                       # hinterer Teil
 
-    # vorderen Teil ausgeben
+    # front
     else 
       return (0..first-1)     if last == -1     # vorderer Teil
       
     end
     
-    # äußere Teile ausgeben
+    # outer
     return [(first..-1).invert_index, (0..last).invert_index]
   end # def
 
@@ -53,13 +70,16 @@ end # class
 
 if defined? TransparentNil
   class NilClass
-    def invert_index;                         nil;              end     
+    # @!group return nil    
+    def invert_index;                   nil;              end     
     def umbrella(*a);                   nil;              end     
     def combine(*a);                    nil;              end     
     def within?(*a);                    nil;              end     
   end
 end # if defined? TransparentNil
     
+    
+    
 # ==================================================================================
 # Ausprobieren
 #

data/lib/kyanite/set.rb

@@ -1,8 +1,8 @@
 # ruby encoding: utf-8
 # ü
 if $0 == __FILE__ 
-  require File.join(File.dirname(__FILE__), '..', '..', 'smart_load_path.rb' )
-  smart_load_path   
+  require 'drumherum'
+  smart_init
 end
 
 require 'set'
@@ -13,41 +13,34 @@ require 'kyanite/symbol'                 # damit man auch Symbols aufnehmen kann
 require 'kyanite/hash'                   # Korrektur der Methoden hash und eql?
 
 
-# [ | Kyanite | Object | Array | *Set* | Enumerable | Hash | ]     | *Set* | OrderedSet | SortedSet | 
-# ---
-#
-#
-# == *General* *Set*
-# Tests and examples see TestKyaniteSet
-#
-#
-# === Unterschiede der verschiedenen Set-Klassen
-# * Ein {Set}[http://www.ruby-doc.org/core/classes/Set.html] ist ungeordnet.                 
-#   Beispiele:  TestKyaniteSet#test_set
-# * Ein OrderedSet ist geordnet, es behält die ursprüngliche Reihenfolge, wird aber nicht kontinuierlich neu sortiert.
-#   Es sei denn, man sorgt dafür mit Dictionary#order_by      
-#   Beispiele:  TestKyaniteSet#test_ordered_set
-# * Ein {SortedSet}[http://www.ruby-doc.org/core/classes/SortedSet.html] ist geordnet und sortiert. Es behält immer die Sortierung.       
-#   Beispiele:  TestKyaniteSet#test_sorted_set
-#
+
+
+
+
+
+
+
+# @!macro set
 class Set
 
-  # Fügt das Element an das Set an.
+  # Adds the element to the set.
   def push(elt)
     self << elt
   end
   
   
-  # Vergleichsoperator, Standardsortierung: Size
+  # Comparison operator (by size)
+  # @return [Integer] 1, 0, -1
   def <=>(other)
     self.size <=> other.size
   end
   
   # def hash_raw
-    # @hash
+    # hash
   # end
   
-  # Liefert irgendein Element.  
+
+  # @return any element
   def first
     @hash.each do |key, value|
       return key
@@ -55,7 +48,7 @@ class Set
   end #def
   
   
-  # Liefert irgendein anderes Element.  
+  # @return any other element  
   def last
     first = nil
     @hash.each do |key, value|
@@ -71,16 +64,10 @@ class Set
 end
 
 
-# [ | Kyanite | Object | Array | *Set* | Enumerable | Hash | ]     | Set | *OrderedSet* | SortedSet | 
-# ---
-#
-#
-# == *Ordered* *Set*
-# Tests and examples see TestKyaniteSet
-#
-# Ein OrderedSet ist geordnet, es behält die ursprüngliche Reihenfolge, wird aber nicht kontinuierlich neu sortiert.
-# Es sei denn, man sorgt dafür mit Dictionary#order_by  
-#
+
+# =================================================================================================================
+# @!macro set
+# 
 class OrderedSet < Set
 
   def initialize(enum = nil, &block) # :yields: o
@@ -94,30 +81,32 @@ class OrderedSet < Set
   end
   
   
-  # Liefert das n-te Element.
+  # @return n-th Element
   def [](index)
     @hash.order[index]
   end
   
-  
-  def zugrundeliegendes_dictionary # :nodoc:
+  # @private  
+  def zugrundeliegendes_dictionary 
     @hash
   end
+
   
-  # Liefert ein entsprechendes Array.
-  # Diese Methode ist schnell. Es muss nichts umgeformt werden. Andere Methoden können also gerne auf to_a basieren. 
+  # This method is fast. Nothing needs to be converted. 
+  # @return [Array]
   def to_a 
     @hash.order
   end  
   
-
+  
+  # @return [Boolean]
   def ==(other)
     silence_warnings do   
       self.to_a.to_set == other.to_a.to_set
     end
   end  
 
-  # Wie Array#index
+  # like Array#index
   def index(object)
     self.to_a.index(object)
   end
@@ -131,10 +120,12 @@ class OrderedSet < Set
     @hash.order_by( &block )
   end
   
+  # @return first element  
   def first
     self[0]
   end
   
+  # @return last element  
   def last
     self[-1]
   end    
@@ -144,37 +135,35 @@ class OrderedSet < Set
 end # class
   
   
-# [ | Kyanite | Object | | Array | *Set* | Enumerable | Hash ]     | Set | OrderedSet | *SortedSet* | 
-# ---
-#
-#
-# == *Sorted* *Set*
-# Tests and examples see TestKyaniteSet
-#
-# Ein {SortedSet}[http://www.ruby-doc.org/core/classes/SortedSet.html] ist geordnet und sortiert. Es behält immer die Sortierung.       
-# Beispiele:  TestKyaniteSet#test_sorted_set
-#
+
+# =================================================================================================================
+# @!macro set
+# 
 class SortedSet 
 
-  # Liefert das n-te Element.
-  # ineffizient!!
+  # @return n-th Element
+  # n-th Element. inefficient!!
   def [](index)
     self.to_a[index]
   end
   
+  # @return first element    
   def first
     self[0]
   end
   
+  # @return last element    
   def last
     self[-1]
   end  
   
   # das war mal auskommentiert, wird aber von nat_lang gebraucht
-  def unshift(e) # :nodoc:
+  # @private
+  def unshift(e) 
     self << e
   end
   
+  # @return self   
   def to_sorted_set
     self
   end    
@@ -183,32 +172,36 @@ end # class
 
 
 
-
+# ===========================================================================================================================
+#
   
 class Array
 
-  # Liefert ein OrderedSet, das dem Array entspricht. 
-  # Übersicht über die verschiedenen Set-Klassen siehe Set.
-  # Tests siehe TestKyaniteSet#test_ordered_set    
+  # @!group Cast  
+  
+  # Returns {OrderedSet}, tests and examples {TestKyaniteSet#test_ordered_set here}.
+  # @return [OrderedSet]
   def to_ordered_set
     OrderedSet.new(self)
   end
   
-  # Liefert ein SortedSet, das dem Array entspricht. 
-  # Übersicht über die verschiedenen Set-Klassen siehe Set.  
-  # Tests siehe TestKyaniteSet#test_sorted_set
+  
+  # Returns {SortedSet}, tests and examples {TestKyaniteSet#test_sorted_set here}.
+  # @return [SortedSet]  
   def to_sorted_set
     SortedSet.new(self)
   end      
   
+  # @!endgroup  
   
 end # class
   
   
 class Object
 
-  # Liefert ein Set mit einem Element
-  #
+
+  # Returns {Set} with one element
+  # @return [Set] with one element
   def to_set; Set.new([self]); end
   
 end