hash-utils 0.11.1 → 0.12.0

data/README.md

@@ -1,9 +1,18 @@
 Hash Utils
 ==========
 
-**Hash Utils** adds a lot of useful fundamental utility methods which 
-are missing in Ruby, both to [Array][1] and [Hash][2] classes and 
-introduces some useful methods and syntactic sugar to [Object][6] and [String][8] classes too.
+**hash-utils** adds more than 65 useful and frequently rather 
+fundamental methods which are missing in Ruby programming language, 
+to several core classes. It tries to be similar project to 
+[Ruby Facets][1] on principle, but less complex, more practical, 
+non-atomic and organized by better way.
+
+- `Array` – 3 methods,
+- `File` – 2 methods,
+- `Hash` – 30 methods,
+- `Object` – 3 methods,
+- `String` – 23 methods,
+- `Symbol` – 5 methods.
 
 For full reference and methods lists, see **[documentation][3]**.
 
@@ -31,10 +40,7 @@ Copyright
 Copyright © 2011 [Martin Kozák][10]. See `LICENSE.txt` for
 further details.
 
-[1]: http://www.ruby-doc.org/core/classes/Array.html
-[2]: http://www.ruby-doc.org/core/classes/Hash.html
+[1]: http://rubyworks.github.com/facets/
 [3]: http://rubydoc.info/gems/hash-utils
-[6]: http://www.ruby-doc.org/core/classes/Object.html
-[8]: http://www.ruby-doc.org/core/classes/String.html
 [9]: http://github.com/martinkozak/hash-utils/issues
 [10]: http://www.martinkozak.net/

data/Rakefile

@@ -16,7 +16,7 @@ Jeweler::Tasks.new do |gem|
   gem.name = "hash-utils"
   gem.homepage = "http://github.com/martinkozak/hash-utils"
   gem.license = "MIT"
-  gem.summary = 'Adds a lot of useful fundamental utility methods which are missing in Ruby, both to Array and Hash classes and introduces some useful methods and syntactic sugar to Object and String classes too.'
+  gem.summary = 'Adds more than 65 useful and frequently rather fundamental methods which are missing in Ruby programming language, to Array, File, Hash, Object, String and Symbol classes. It tries to be similar project to Ruby Facets on principle, but less complex, more practical, non-atomic and organized by better way.'
   gem.post_install_message = "\nHASH UTILS: Be warn, Hash#all? is deprecated since version 0.10.0 because of\nconflict with built-in one with in fact equivalent functionallity. It will be\nremoved around version 0.13.0. Please, check your code if you can and switch\nto Ruby's one.\n\n"
   gem.email = "martinkozak@martinkozak.net"
   gem.authors = ["Martin Kozák"]

data/VERSION

@@ -1 +1 @@
-0.11.1
+0.12.0

data/hash-utils.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{hash-utils}
-  s.version = "0.11.1"
+  s.version = "0.12.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Martin Kozák"]
-  s.date = %q{2011-03-09}
+  s.date = %q{2011-03-20}
   s.email = %q{martinkozak@martinkozak.net}
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -46,7 +46,7 @@ to Ruby's one.
 }
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.6.2}
-  s.summary = %q{Adds a lot of useful fundamental utility methods which are missing in Ruby, both to Array and Hash classes and introduces some useful methods and syntactic sugar to Object and String classes too.}
+  s.summary = %q{Adds more than 65 useful and frequently rather fundamental methods which are missing in Ruby programming language, to Array, File, Hash, Object, String and Symbol classes. It tries to be similar project to Ruby Facets on principle, but less complex, more practical, non-atomic and organized by better way.}
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

data/lib/hash-utils/hash.rb

@@ -505,4 +505,59 @@ class Hash
         return result
     end
     
+    ##
+    # Merges two hashes recursively in place. Receives unlimited
+    # count of hashes for merging them in left to right order.
+    #
+    # @param [*Hash] hashs for merge from
+    # @return [Hash] hash for merge to
+    # @since 0.12.0
+    #
+    
+    def deep_merge!(*args)
+        fm = args.map { |hash| [self, hash] }
+        
+        while not fm.empty?
+            _in, _out = fm.shift
+            _out.each_pair do |k, v|
+                if v.kind_of? Hash
+                    fm << [_in[k], _out[k]]
+                else
+                    _in[k] = v
+                end
+            end
+        end
+        
+        return self
+    end
+    
+    ##
+    # Merges two hashes recursively and returns new hash. Receives 
+    # unlimited count of hashes for merging them in left to right order.
+    # Included hashes will be copied too.
+    #
+    # @param [*Hash] hashes for merge from
+    # @return [Hash] hash for merge to
+    # @since 0.12.0
+    #
+    
+    def deep_merge(*args)
+        result = self.dup
+        fm = args.map { |hash| [result, hash] }
+
+        while not fm.empty?
+            _in, _out = fm.shift
+            _out.each_pair do |k, v|
+                if v.kind_of? Hash
+                    _in[k] = _in[k].dup
+                    fm << [_in[k], _out[k]]
+                else
+                    _in[k] = v
+                end
+            end
+        end
+
+        return result
+    end
+    
 end

data/lib/hash-utils/object.rb

@@ -6,6 +6,7 @@
 #
 
 class Object
+
     ##
     # Indicates object is in some object which supports +#include?+.
     #
@@ -28,4 +29,19 @@ class Object
     def to_b
         !!self
     end
+    
+    ##
+    # Multiplies object by +#dup+ n-times.
+    #
+    # @param [Integer] count required number of copies
+    # @return [Array] array with object copies
+    # @since 0.12.0
+    #
+    
+    def **(count)
+        result = [ ]
+        count.times { result << self.dup }
+        return result
+    end
+    
 end

data/lib/hash-utils/string.rb

@@ -10,6 +10,7 @@ require "hash-utils/object"
 #
 
 class String
+
     ##
     # Holds numeric matcher.
     #
@@ -218,6 +219,230 @@ class String
         self[-1].chr
     end
     
+    ##
+    # Returns required count of lines from beginning of string.
+    #
+    # @example
+    #   "a\nb\nc\nd\n".first_lines(2)
+    #   # will return ["a\n", "b\n"]   
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @param [Integer] count required count of lines
+    # @return [Array] array of lines
+    # @since 0.12.0
+    #
+    
+    def first_lines(count = 1)
+        result = [ ]
+        self.each_line do |line|
+            count -= 1
+            result << line
+            break if count == 0
+        end
+        
+        return result
+    end
+    
+    ##
+    # Returns first line of the string.
+    #
+    # @example
+    #   "a\nb\nc\nd\n".first_line
+    #   # will return "a\n"
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @return [String] line with +\n+
+    # @since 0.12.0
+    #
+        
+    def first_line
+        self.first_lines.first
+    end
+
+    ##
+    # Returns required count of lines from end of string.
+    #
+    # @example
+    #   "a\nb\nc\nd".last_lines(2)
+    #   # will return ["c\n", "d"]   
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @param [Integer] count required count of lines
+    # @return [Array] array of lines
+    # @since 0.12.0
+    #
+    
+    def last_lines(count = 1)
+        buffer = ""
+        result = [ ]
+        (self.length - 1).downto(0) do |i|
+            chr = self[i]
+            if chr.ord == 10
+                count -= 1
+                result << buffer.reverse!
+                buffer = ""
+                break if count == 0
+            end
+            buffer << chr.chr
+        end
+
+        if count != 0
+            result << buffer.reverse!
+        end
+        return result.reverse!
+    end
+    
+    ##
+    # Returns last line of the string.
+    #
+    # @example
+    #   "a\nb\nc\nd".last_line
+    #   # will return "d"
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @return [String] line
+    # @since 0.12.0
+    #
+        
+    def last_line
+        self.last_lines.last
+    end
+    
+    ##
+    # Removes given count of lines from beginning of file.
+    #
+    # @example 
+    #   str = "a\nb\nc\nd"
+    #
+    #   str.shift_lines(2)
+    #   # will return ["a\n", "b\n"]      
+    #   p str
+    #   # will print out "c\nd"
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @param [Integer] count required number of lines
+    # @return [Array] removed lines
+    # @since 0.12.0
+    #
+    
+    def shift_lines(count = 1)
+        lines = self.first_lines(count)
+        length = lines.inject(0) { |sum, i| sum + i.length }
+        self.replace(self[length..-1])
+        return lines
+    end
+    
+    ##
+    # Removes first line out from the string and returns it.
+    # @return [String] removed line
+    #
+    
+    def shift_line
+        self.shift_lines.first
+    end
+    
+    ##
+    # Puts lines to begin of string.
+    #
+    # @param [Array] lines line bodies without +\n+
+    # @return [String] itself
+    # @since 0.12.0
+    #
+    
+    def unshift_lines(*lines)
+        self.unshift(lines.join("\n") << "\n")
+    end
+    
+    alias :unshift_line :unshift_lines
+    
+    ##
+    # Removes lines out of end of the string.
+    #
+    # @note Works well for UNIX strings only. Convert your string 
+    #   if necessary.
+    # @param [Integer] count required number of lines
+    # @return [Array] removed lines
+    # @since 0.12.0
+    #
+    
+    def pop_lines(count = 1)
+        lines = self.last_lines(count)
+        length = lines.inject(0) { |sum, i| sum + i.length }
+        self.replace(self[0..(length - 1)])
+        return lines
+    end
+
+    ##
+    # Removes last line out from the string and returns it.
+    # @return [String] removed line
+    #
+    
+    def pop_line
+        self.pop_lines.first
+    end
+    
+    ##
+    # Joins lines to string.
+    #
+    # @param [Array] lines line bodies without +\n+
+    # @return [String] itself
+    # @since 0.12.0
+    #
+        
+    def push_lines(*lines)
+        self.push("\n" << lines.join("\n"))
+    end
+    
+    alias :push_line :push_lines
+    alias :push :<<
+    
+    ##
+    # Removes appropriate number of characters from end of string.
+    #
+    # @param [Integer] count required number of characters
+    # @return [String] removed characters
+    # @since 0.12.0
+    #
+    
+    def pop(count = 1)
+        res = self[(self.length - count)..-1]
+        self.replace(self[0..-(count + 1)])
+        return res
+    end
+
+    ##
+    # Removes appropriate number of characters from begin of string.
+    #
+    # @param [Integer] count required number of characters
+    # @return [String] removed characters
+    # @since 0.12.0
+    #
+    
+    def shift(count = 1)
+        res = self[0...count]
+        self.replace(self[count..-1])
+        return res
+    end
+
+    ##
+    # Puts content to begin of file.
+    #
+    # @param [String] string string for prepend
+    # @return [String] itself
+    # @since 0.12.0
+    #
+    
+    def unshift(string)
+        self.replace(string << self)
+    end    
+    
+    alias :prepend :unshift
+    alias :append :<<
     
     
     private
@@ -248,5 +473,6 @@ class String
         
         block.call(newcall)
     end
+    
 end
 

data/lib/hash-utils/symbol.rb

@@ -2,3 +2,76 @@
 # (c) 2011 Martin Kozák (martinkozak@martinkozak.net)
 
 require "hash-utils/object"
+
+##
+# Symbol extension.
+#
+
+class Symbol
+
+    ##
+    # Returns a new +Symbol+ containing integer copies of the receiver.
+    #
+    # @param [Integer] multi required number of copies
+    # @return [Symbol] new symbol
+    # @since 0.12.0
+    #
+    
+    def *(multi)
+        (self.to_s * multi).to_sym 
+    end
+
+    ##
+    # Returns a new +Symbol+ containing +other_str+ concatenated 
+    # to +str+.
+    #
+    # @param [Integer] other_str string for concatenating to
+    # @return [Symbol] new symbol
+    # @since 0.12.0
+    #
+    
+    def +(other_str)
+        (self.to_s + other_str.to_s).to_sym
+    end
+    
+    alias :concat :+
+    
+    ##
+    # Works by the same way as +String#slice on +Symbol+.
+    #
+    # @return [String]
+    # @see http://www.ruby-doc.org/core/classes/String.html#M001128
+    # @since 0.12.0
+    # 
+    
+    def [](*args)
+        self.to_s[*args]
+    end
+    
+    alias :slice :[]
+    
+    ##
+    # Returns true if +Symbol+ starts with a prefix given.
+    #
+    # @param [String+] prefix prefixes for check
+    # @return [Boolean] +true+ if yes, +false+ in otherwise
+    # @since 0.12.0
+    #
+    
+    def start_with?(*prefix)
+        self.to_s.start_with?(*prefix)
+    end
+    
+    ##
+    # Returns true if +Symbol+ ends with a prefix given.
+    #
+    # @param [String+] prefix prefixes for check
+    # @return [Boolean] +true+ if yes, +false+ in otherwise
+    # @since 0.12.0
+    #
+    
+    def end_with?(*suffix)
+        self.to_s.end_with?(*suffix)
+    end
+        
+end

data/lib/hash-utils.rb

@@ -5,4 +5,5 @@ require "hash-utils/array"
 require "hash-utils/hash"
 require "hash-utils/string"
 require "hash-utils/object"
+require "hash-utils/symbol"
 require "hash-utils/file"

data/test

@@ -9,38 +9,200 @@ require "riot"
 
 ## FILE
 
-context "File#touch" do
-    setup { File.touch("./~test") }
-    asserts("correctness") { File.exists? "./~test" }
-    teardown { File.unlink("./~test") }
-end
+# Filozofové mají Kanta rádi. Matematici mají Kanta také rádi, jen si 
+# myslí, že většina z toho, co vymyslel, je blbost.
+#
+# doc. Jiří Souček
 
-context "File#write" do
-    setup { File.write("./~test", "some string") }
-    asserts("correctness") { File.read("./~test") == "some string" }
-    teardown { File.unlink("./~test") }
+context "File" do
+    asserts("#touch") do 
+        File.touch("./~test1")
+        File.exists? "./~test1"
+    end
+    asserts("#write") do
+        File.write("./~test2", "some string")
+        File.read("./~test2") == "some string"
+    end
+    
+    teardown do 
+        File.unlink("./~test1")
+        File.unlink("./~test2")
+    end
 end
 
 ## HASH
 
-context "Hash#map_values" do
-    setup { {:a => 1, :b => 2 }.map_values { |i| i + 1 } }
-    asserts("correctness") { topic == { :a => 2, :b => 3 } }
+context "Hash" do
+    setup do 
+        { :a => 1, :b => 2 }
+    end
+ 
+    asserts("#compact") do
+        t = { :a => 1, :b => nil }
+        t = t.compact
+        t == { :a => 1 }
+    end
+    asserts("#compact!") do
+        t = { :a => 1, :b => nil }
+        t.compact!
+        t == { :a => 1 }
+    end
+    asserts("#map_values") do
+        topic.map_values { |i| i + 1 } == { :a => 2, :b => 3 }
+    end
+    asserts("#map_values!") do
+        t = topic.dup
+        t.map_values! { |i| i + 1 } 
+        t == { :a => 2, :b => 3 }
+    end
+    asserts("#deep_merge") do
+        h1 = {:a => {:b => :c, :d => :e}}
+        h2 = {:a => {:d => :f, :h => :i}}
+        h = h1.deep_merge(h2) 
+        (h == {:a => {:b => :c, :d => :f, :h => :i}}) and (h1 == {:a => {:b => :c, :d => :e}})
+    end
+    asserts("#deep_merge!") do
+        h = {:a => {:b => :c, :d => :e}}
+        h.deep_merge!({:a => {:d => :f, :h => :i}})
+        h == {:a => {:b => :c, :d => :f, :h => :i}}
+    end
 end
 
-context "Hash#map_values!" do
-    setup { {:a => 1, :b => 2 }.map_values! { |i| i + 1 } }
-    asserts("correctness") { topic == { :a => 2, :b => 3 } }
+## OBJECT
+
+context "Object" do
+    asserts("#**") do
+        "ab" ** 5 == ["ab", "ab", "ab", "ab", "ab"]
+    end
+    asserts("#in?") do
+        5.in? 1..7
+    end
+    asserts("#to_b") do
+        (nil.to_b === false) and ("ab".to_b === true)
+    end
 end
 
 ## STRING
 
-context "String#first" do
-    setup { "abc".first }
-    asserts("correctness") { topic == ?a }
+context "String" do
+    asserts("#first") do
+        "abc".first == ?a
+    end
+    asserts("#first_line") do
+        res = true
+        res &= "a\nb\nc\n".first_line == "a\n"
+        res &= "a".first_line == "a"
+    end
+    asserts("#first_lines") do
+        res = true
+        res &= "a\nb".first_lines(2) == ["a\n", "b"]
+        res &= "a\nb\nc\n".first_lines(4) == ["a\n", "b\n", "c\n"]
+    end
+    asserts("#last") do
+        "abc".last == ?c
+    end
+    asserts("#last_line") do
+        res = true
+        res &= "a\nb\nc\n".last_line == ""
+        res &= "a\nb\nc".last_line == "c"
+        res &= "a".last_line == "a"
+    end
+    asserts("#last_lines") do
+        res = true
+        res &= "a\nb".last_lines(2) == ["a\n", "b"]
+        res &= "a\nb\nc\n".last_lines(4) == ["a\n", "b\n", "c\n", ""]
+    end
+    asserts("#pop") do
+        res = true
+        str = "abcd"
+        res &= str.pop == "d"
+        res &= str == "abc"
+        str = "abcd"
+        res &= str.pop(2) == "cd"
+        res &= str == "ab"
+    end
+    asserts("#pop_line") do
+        res = true
+        str = "a\nb\nc\nd"
+        res &= str.pop_line == "d"
+        res &= str = "a\nb\nc\n"
+    end
+    asserts("#pop_lines") do
+        res = true
+        str = "a\nb\nc\nd\n"
+        res &= str.pop_lines(2) == ["d\n", ""]
+        res &= str = "a\nb\nc\n"
+    end
+    asserts("#push_line") do
+        res = true
+        str = "a\nb\nc\nd"
+        res &= str.push_line("1") == "a\nb\nc\nd\n1"
+        res &= str == "a\nb\nc\nd\n1"
+    end
+    asserts("#push_lines") do
+        res = true
+        str = "a\nb\nc\nd"
+        res &= str.push_lines("1", "2") == "a\nb\nc\nd\n1\n2"
+        res &= str == "a\nb\nc\nd\n1\n2"
+    end
+    asserts("#shift") do
+        res = true
+        str = "abcd"
+        res &= str.shift == "a"
+        res &= str == "bcd"
+        str = "abcd"
+        res &= str.shift(2) == "ab"
+        res &= str == "cd"
+    end
+    asserts("#shift_line") do
+        res = true
+        str = "a\nb\nc\nd\n"
+        res &= str.shift_line == "a\n"
+        res &= str = "b\nc\nd\n"
+    end
+    asserts("#shift_lines") do
+        res = true
+        str = "a\nb\nc\nd\n"
+        res &= str.shift_lines(2) == ["a\n", "b\n"]
+        res &= str = "c\nd\n"
+    end
+    asserts("#unshift") do
+        res = true
+        str = "abcd"
+        res &= str.unshift("123") == "123abcd"
+        res &= str == "123abcd"        
+    end
+    asserts("#unshift_line") do
+        res = true
+        str = "a\nb\nc\nd\n"
+        res &= str.unshift_line("1") == "1\na\nb\nc\nd\n"
+        res &= str == "1\na\nb\nc\nd\n"
+    end
+    asserts("#unshift_lines") do
+        res = true
+        str = "a\nb\nc\nd\n"
+        res &= str.unshift_lines("1", "2") == "1\n2\na\nb\nc\nd\n"
+        res &= str == "1\n2\na\nb\nc\nd\n"
+    end
+
 end
 
-context "String#last" do
-    setup { "abc".last }
-    asserts("correctness") { topic == ?c }
+## SYMBOL
+
+context "Symbol" do
+    asserts("#*") do
+        :a * 5 == :aaaaa
+    end
+    asserts("#+") do
+        :a + :b == :ab
+    end
+    asserts("#[]") do
+        :abcde[0...3] == "abc"
+    end
+    asserts("#end_with?") do
+        :abcde.end_with? "ghi", "cde"
+    end
+    asserts("#start_with?") do
+        :abcde.start_with? "ghi", "abc"
+    end
 end

metadata

@@ -2,7 +2,7 @@
 name: hash-utils
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors: 
 - "Martin Koz\xC3\xA1k"
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-09 00:00:00 +01:00
+date: 2011-03-20 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -92,7 +92,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -1180165342308683422
+      hash: -4395191142645509098
       segments: 
       - 0
       version: "0"
@@ -108,6 +108,6 @@ rubyforge_project:
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: Adds a lot of useful fundamental utility methods which are missing in Ruby, both to Array and Hash classes and introduces some useful methods and syntactic sugar to Object and String classes too.
+summary: Adds more than 65 useful and frequently rather fundamental methods which are missing in Ruby programming language, to Array, File, Hash, Object, String and Symbol classes. It tries to be similar project to Ruby Facets on principle, but less complex, more practical, non-atomic and organized by better way.
 test_files: []