kyanite 0.6.1 → 0.7.0

data/lib/kyanite/string.rb

@@ -4,10 +4,9 @@ require 'kyanite/enumerable'
 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'

data/lib/kyanite/string/cast.rb

@@ -1,35 +1,33 @@
 # ruby encoding: utf-8
+
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 require 'kyanite/numeric/integer'
  
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | Object | *String* | Symbol | Numeric |
-#
-# ---
-#
-# == *String*  
-#
-#
-class String
 
-  # ---------------------------------------------------------------------------------------------------------------------------------
-  # :section: Cast
-  # See TestKyaniteStringCast for tests and examples.
-  #  
+class String
 
-    
-    
-    # Wandelt einen String in den plausibelsten Identifier um:
-    #   self.strip.to_integer_optional
+  
+  # @!group Cast
+  
+    # Converts a string into the most plausible Identifier
     #
-    # Tests & Beispiele siehe TestKyaniteStringCast#test_to_identifier
+    # See examples and tests {TestKyaniteStringCast#test_to_identifier here}.     
+    # @return [Integer]        
     def to_identifier
       self.strip.to_integer_optional
     end        
         
         
-    # Wandelt einen String in einen Integer, auch dann, wenn die Zahl hinten angehängt wurde.
-    # Im Gegensatz zu to_i wird nil zurückgegeben, wenn keine Zahl drin war. 
+    
+    # Converts a string to an integer, even if the number was appended to anything.
+    # Unlike +to_i+ it returns +nil+ if no integer was found inside the string.    
     # 
-    # Beispiele & Tests siehe TestKyaniteStringCast#test_to_integer      
+    # See examples and tests {TestKyaniteStringCast#test_to_integer here}.      
+    # @return [Integer]     
     def to_integer
         return nil                 unless self =~ /\d/
         firsttry = self.to_i
@@ -38,18 +36,23 @@ class String
     end
 
 
-    # Wandelt einen String in einen Integer.
-    # Im Gegensatz zu to_i wird self zurückgegeben, wenn der String nicht mit einer Zahl beginnt.
-    # Leere Strings werden in NIL umgewandelt. 
-    # 
-    # Beispiele & Tests siehe TestKyaniteStringCast#test_to_integer_optional    
+    
+    # Tries to convert a string to an integer. 
+    # Returns +self+ if the string does not start with a number.
+    # Empty strings are converted to +nil+.
+    #
+    # See examples and tests {TestKyaniteStringCast#test_to_integer_optional here}.   
+    # @return [Integer, String]
     def to_integer_optional
         return nil                  if self.empty?
         return self                 unless (self =~ /^\d/  || self =~ /^-\d/ )
         return self.to_i
     end
     
-
+    
+    # Non-empty strings are returned.
+    # Empty strings are converted to +nil+.
+    # @return [String, Nil]    
     def to_nil
       return self unless self.empty?
       nil
@@ -59,12 +62,14 @@ class String
 
  
     unless defined? HEX_CHARS
+      # @private
       HEX_CHARS = '0123456789abcdef'.freeze
     end
 
     
     # Get a hex representation for a char.
-    # See also String#from_x.     
+    # See also {#from_x from_x}.     
+    # @return [String]       
     def to_x
       hex = ''
       each_byte { |byte|
@@ -76,8 +81,11 @@ class String
       hex
     end
     
+    
+    
     # Get a char for a hex representation.   
-    # See also String#to_x. 
+    # See also {#to_x to_x}.     
+    # @return [String]       
     def from_x
       str, q, first = '', 0, false
       each_byte { |byte|
@@ -100,16 +108,32 @@ class String
 
 end
 
-if defined? TransparentNil
-  class NilClass
-    def to_identifier;                  nil;            end
-    def to_integer;                     nil;            end
-    def to_integer_optional;            nil;            end
-    def to_nil(*a);                     nil;            end  
-    def to_x;                           nil;            end  
-    def from_x;                         nil;            end  
-  end
+
+# @!endgroup
+
+class NilClass
+  def to_identifier;                  nil;            end
+  def to_integer;                     nil;            end
+  def to_integer_optional;            nil;            end
+  def to_nil(*a);                     nil;            end  
+  def to_x;                           nil;            end  
+  def from_x;                         nil;            end  
 end
 
 
+class Integer
+  
+  
+  # +self+, complements {String#to_integer}. 
+  # @return [self]
+  def to_integer;                     self;            end     
+  
+  
+  # +self+, complements {String#to_integer_optional}. 
+  # @return [self] 
+  def to_integer_optional;            self;            end  
+      
+  
+end # class
+
 

data/lib/kyanite/string/chars.rb

@@ -1,50 +1,50 @@
 # 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 'kyanite/string/chars_const'
 
-  
-unless defined? MYSQL_REPLACES
-  MYSQL_REPLACES =  [                 
-                                      [/ä/,    'a'], 
-                                      [/ö/,    'o'],  
-                                      [/ü/,    'u'],        
-                                      [/Ä/,    'a'], 
-                                      [/Ö/,    'o'],  
-                                      [/Ü/,    'u'],      
-                                      [/ss/,   'ß'],      
-                                      [/SS/,   'ß']     
-                    ]  
-end    
-    
-    
-   
-   
+ 
 
 
 class String
 
+  unless defined? MYSQL_REPLACES
+    MYSQL_REPLACES =  [                 
+                                        [/ä/,    'a'], 
+                                        [/ö/,    'o'],  
+                                        [/ü/,    'u'],        
+                                        [/Ä/,    'a'], 
+                                        [/Ö/,    'o'],  
+                                        [/Ü/,    'u'],      
+                                        [/ss/,   'ß'],      
+                                        [/SS/,   'ß']     
+                      ]  
+  end   
+
     # ---------------------------------------------------------------------------------------------------------------------------------
-    # :section: Clear / Format Text
+    # @!group Clear / Format Text
     # See TestKyaniteStringChars for tests and examples.    
 
-    # Reduziert den String auf ein Base94-Encoding.
-    # * Wandelt àáâăäãāåạąæảấầắằÀÁÂĂÄÃĀÅẠĄÆẢẤẦẮẰ usw. in aaaaaaaaaaaaaaaaAAAAAAAAAAAAAAAA usw. um 
-    # * entfernt anschließend alle Nicht-Asciizeichen
-    # * entfernt außerdem alle nichtdruckbaren Asciizeichen
-    # * Vorsicht: Newlines werden auch entfernt
+    # Reduces the string to a base94 encoding.
+    # 1. Converts àáâăäãāåạąæảấầắằÀÁÂĂÄÃĀÅẠĄÆẢẤẦẮẰ etc. to aaaaaaaaaaaaaaaaAAAAAAAAAAAAAAAA.
+    # 2. Then removes all non-Ascii-chars.
+    # 3. Then removes all non-printable Ascii-chars.
+    # 4. Caution: Also Newlines are removed. 
     #   
-    # See TestKyaniteStringChars for tests and examples.
-    #
+    # See tests and examples {TestKyaniteStringChars#test_reduce94_a here}.
+    # @return [String]
     def reduce94( options={} )
       dup.reduce94!(options)
     end        
     
-    # See TestKyaniteStringChars for tests and examples.
-    #    
+
+    # In-place-variant of {#reduce94 reduce94}.   
+    # @return [String]
     def reduce94!( options={} )       
       self.gsub!( 'ß', options[:german_sz] )        if options[:german_sz]      
       self.tr!(TR_FULL, TR_REDUCED)
@@ -59,12 +59,23 @@ class String
     #       
     # See TestKyaniteStringChars for tests and examples.
     #    
+    
+    # Reduces the string to a base53 encoding.
+    # The result consists only uppercase letters, minus, and lowercase characters as replacement for some known special characters.
+    # 1. Removes all non-letter-chars.
+    # 2. Converts all regular letters to upcase letters. 
+    # 3. Converts special letters to reduced downcase letters, eg. àáâăäãāåạąæảấầắằÀÁÂĂÄÃĀÅẠĄÆẢẤẦẮẰ etc. to aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.
+    # 4. Caution: Also Newlines are removed. 
+    #   
+    # See tests and examples {TestKyaniteStringChars#test_reduce53_a here}.
+    # @return [String]
     def reduce53( options={} )
       dup.reduce53!(options)
     end        
     
-    # See TestKyaniteStringChars for tests and examples.
-    #    
+    
+    # In-place-variant of {#reduce53 reduce53}.
+    # @return [String]    
     def reduce53!( options={} )
     
       if options[:camelcase]  
@@ -114,43 +125,59 @@ class String
     
     
     # ---------------------------------------------------------------------------------------------------------------------------------
-    # :section: Groß- und Kleinschreibung
+    # @!group Upcase and Downcase with support for special letters like german umlauts
     # See TestKyaniteStringChars for tests and examples.
     #
     
-    # Ein Überschreiben von downcase führt in Kombination mit ActiveSupport zu seltsamen Ergebnissen!
+    # Better +downcase+: also works with special letters like german umlauts.
+    # (If you overwrite downcase you will get strange results if you use Active Support.)
+    #
+    # See tests and examples {TestKyaniteStringChars#test_downcase_upcase here}.  
+    # @return [String]    
     def downcase2 
       self.tr(TR_UPCASE, TR_DOWNCASE).downcase
     end    
     
+    # In-place-variant of {#downcase2 downcase2}.    
+    # @return [String]    
     def downcase2! 
       self.tr!(TR_UPCASE, TR_DOWNCASE).downcase!
     end        
     
     
-    # Ein Überschreiben von upcase führt in Kombination mit ActiveSupport zu seltsamen Ergebnissen!       
+    # Better +upcase+: also works with special letters like german umlauts.
+    # (If you overwrite upcase you will get strange results if you use Active Support.)    
+    #
+    # See tests and examples {TestKyaniteStringChars#test_downcase_upcase here}.      
+    # @return [String]      
     def upcase2
       self.tr(TR_DOWNCASE, TR_UPCASE).upcase
     end      
     
+    # In-place-variant of {#upcase2 upcase2}.    
+    # @return [String]    
     def upcase2!
       self.tr!(TR_DOWNCASE, TR_UPCASE).upcase!
     end  
 
+    # Converts the first letter to upcase, also works with special letters like german umlauts.
+    # @return [String]      
     def capitalize
       (slice(0) || '').upcase2 + (slice(1..-1) || '').downcase2
     end
     
     
-    # Erster Buchstabe groß?
+    # Is the first letter upcase? Also works with special letters like german umlauts. 
     def capitalized?
       self =~ TR_UPCASE_ALL_REGEXP
     end   
 
+    # Is the string upcase? Also works with special letters like german umlauts.    
     def upcase?
       (self == self.upcase)
     end
     
+    # Is the string downcase? Also works with special letters like german umlauts.     
     def downcase?
       (self == self.upcase)
     end    
@@ -186,8 +213,11 @@ if $0 == __FILE__ then
   #require 'perception'
   
   #puts "Hallo"
-  puts 'Scheiße'.reduce94(:german_sz => 'z')
+  # puts 'Scheiße'.reduce94(:german_sz => 'z')
+  test_down =       'àáâăäãāåạąæảấầắằабćĉčçċцчďðđдèéêěĕëēėęếеэфĝğġģгĥħхìíîĭïĩīıįijийĵюяķкĺľłļŀлмńňñņŋнòóôŏöõōøőơœопŕřŗрśŝšşсшщţťŧþтùúûŭüũūůűųưувŵýŷÿźżžжз'
+  test_up =         'ÀÁÂĂÄÃĀÅẠĄÆẢẤẦẮẰАБĆĈČÇĊЦЧĎÐĐДÈÉÊĚĔËĒĖĘẾЕЭФĜĞĠĢГĤĦХÌÍÎĬÏĨĪİĮIJИЙĴЮЯĶКĹĽŁĻĿЛМŃŇÑŅŊНÒÓÔŎÖÕŌØŐƠŒОПŔŘŖРŚŜŠŞСШЩŢŤŦÞТÙÚÛŬÜŨŪŮŰŲƯУВŴÝŶŸŹŻŽЖЗ'
 
+  puts "hallo".upcase!
 
 
 end

data/lib/kyanite/string/chars_const.rb

@@ -1,10 +1,11 @@
 # 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 'hashery' 
 require 'kyanite/string/div'
 

data/lib/kyanite/string/diff.rb

@@ -1,16 +1,23 @@
-# ruby encoding: utf-8 
+# ruby encoding: utf-8
 
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
 
-class String
 
+
+class String       
+
+# @!group Overlap / Diff
+     
         
-# ---------------------------------------------------------------------------------------------------------------------------------
-# :section: Overlap / Diff
-# See TestKyaniteStringDiff for tests and examples.         
-        
-  # Gibt den gemeinsamen Teil zweier Strings aus (von vorne gezählt).  
+  # Returns the mutual part of two strings. Example:
+  #  "Hello world".overlap("Hello darling") 
+  #  => "Hello"
   #    
-  # Beispiele & Tests siehe TestKyaniteStringDiff#test_overlap    
+  # See more examples and tests {TestKyaniteStringDiff#test_overlap here}.    
+  # @return [String] mutual part
   def overlap(b)
       return ''         if b.nil?
       b = b.to_str
@@ -22,18 +29,22 @@ class String
   end    
 
   
-  # Liefert den Unterschied zwischen zwei Strings zurück.
-  # Im Zweifelsfall immer den längsten String.
-  # Wenn dann immer noch Zweifel, dann self. 
-  #    
-  # Beispiele & Tests siehe TestKyaniteStringDiff#test_diff    
+  # Returns the differencing part of two strings. Example:
+  #  "Hello darling".diff("Hello") 
+  #  => " darling"
+  #      
+  # When in doubt, the longest differencing string.
+  # If there is still doubt, then +self+.
+  #     
+  # See more examples and tests {TestKyaniteStringDiff#test_diff here}.  
+  # @return [String] differencing part  
   def diff(b)
       return self     if b.nil?
       b = b.to_str
       return ''        if self == b        # kein Unterschied
   
     a = self 
-    a,b = b,a     if a.size >= b.size        # a ist jetzt k�rzer oder gleichlang wie b
+    a,b = b,a     if a.size >= b.size        # a ist jetzt k?rzer oder gleichlang wie b
     overlap = a.overlap(b)
     return self if overlap == ''
     return b.split(overlap)[1]
@@ -41,19 +52,24 @@ class String
 
   
   
-  # Liefert zugleich overlap und diff zurück.
-  # Symmetrie: Rechnet man overlap + diff, so erhält man immer den längsten der beiden ursprünglichen Strings.
-  # Waren beide gleichlang, so erhält man self.
+
   # overlapdiff braucht genauso viel Zeit wie diff alleine. 
+  
+  # Returns {#diff diff} and {#overlap overlap} in one array.
+  # Takes as much time as +diff+ alone.
+  #
+  # Symmetry: If we add +overlap+ + +diff+, we always get the longest of the two original strings.
+  # If both had the same length, we get +self+.
   #
-  # Beispiele & Tests siehe TestKyaniteStringDiff#test_overlapdiff    
+  # See examples and tests {TestKyaniteStringDiff#test_overlapdiff here}.  
+  # @return [Array] mutual part, differencing part
   def overlapdiff(b)
       return '', self     if b.nil?
       b = b.to_str
       return self,''        if self == b        # kein Unterschied
   
     a = self 
-    a,b = b,a     if a.size >= b.size        # a ist jetzt k�rzer oder gleichlang wie b
+    a,b = b,a     if a.size >= b.size        # a ist jetzt k?rzer oder gleichlang wie b
     overlap = a.overlap(b)
     return overlap, self if overlap == ''
     return overlap, b.split(overlap)[1]
@@ -64,24 +80,38 @@ class String
 end
 
 
-if defined? TransparentNil
-  class NilClass
-
-    # Rückgabe: Leerer String,
-    # siehe String#overlap
-    def overlap(*a);              '';             end  
-    
-    # Rückgabe: b,
-    # siehe String#diff  
-    def diff(b);                  b;              end  
-    
-    # Rückgabe: ['', b],
-    # siehe String#overlapdiff
-    def overlapdiff(b);           ['', b];        end  
-  end
+
+class NilClass
+
+  # see {String#overlap}
+  # @return [String] Empty String  
+  def overlap(*a);              '';             end  
+  
+
+  # see {String#diff}  
+  # @return [String] Parameter b
+  def diff(b);                  b;              end  
+  
+
+  # see {String#overlapdiff}  
+  # @return [Array] ['', b] 
+  def overlapdiff(b);           ['', b];        end  
 end
 
 
+# -----------------------------------------------------------------------------------------
+# Ausprobieren
+#
+if $0 == __FILE__ then
+
+puts "Hello darling".diff("Hello") 
+
+
+
+
+
+
+end