sorting 0.0.1

data/.yardopts

@@ -0,0 +1 @@
+--no-private --list-undoc -m markdown - LICENSE.txt documentation/examples.rb

data/LICENSE.txt

@@ -0,0 +1,8 @@
+Copyright (c) 2012, Stefan Rusterholz <stefan.rusterholz@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.markdown

@@ -0,0 +1,63 @@
+README
+======
+
+
+Summary
+-------
+Helpful functionality for sorting and comparing.
+
+
+Installation
+------------
+`gem install sorting`
+
+
+Usage
+-----
+
+Sort a list of Person objects
+
+    # Convenient
+    require 'sorting/convenience'
+    people.sort_by { |person| [asc(person.first_name), asc(person.last_name), desc(person.age)] }
+
+    # Or without patching Kernel
+    require 'sorting'
+    people.sort_by { |person|
+      [Sorting.asc(person.first_name), Sorting.asc(person.last_name), Sorting.desc(person.age)]
+    }
+
+    # Care about nil values in your data
+    require 'sorting/convenience'
+    people.sort_by { |person|
+      [asc(person.first_name, :nils_first), asc(person.first_name, :nils_last)]
+    }
+
+    # Only care about nil values in your data
+    [5,3,nil,9].sort_by { |x| x || Sorting::Bigger } # Sorting::Smaller is available too
+
+    # Care about expensive comparison values which may not always be needed
+    # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
+    # it might only be needed in a small number of cases.
+    require 'sorting/convenience'
+    items.sort_by { |item|
+      [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
+    }
+
+Take a look at {file:documentation/examples.rb} for more examples.
+
+
+Links
+-----
+
+* [Online API Documentation](http://rdoc.info/github/apeiros/sorting/)
+* [Public Repository](https://github.com/apeiros/sorting)
+* [Bug Reporting](https://github.com/apeiros/sorting/issues)
+* [RubyGems Site](https://rubygems.org/gems/sorting)
+
+
+License
+-------
+
+You can use this code under the {file:LICENSE.txt BSD-2-Clause License}, free of charge.
+If you need a different license, please ask the author.

data/Rakefile

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.expand_path('../rake/lib', __FILE__))
+Dir.glob(File.expand_path('../rake/tasks/**/*.{rake,task,rb}', __FILE__)) do |task_file|
+  begin
+    import task_file
+  rescue LoadError => e
+    warn "Failed to load task file #{task_file}"
+    warn "  #{e.class} #{e.message}"
+    warn "  #{e.backtrace.first}"
+  end
+end

data/lib/sorting.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+
+
+require 'sorting/ascending'
+require 'sorting/bigger'
+require 'sorting/descending'
+require 'sorting/helpers'
+require 'sorting/smaller'
+require 'sorting/version'
+
+
+
+# Sorting
+# Helpful functionality for sorting and comparing.
+#
+# @example Convenient
+#     require 'sorting/convenience'
+#     people.sort_by { |person| [asc(person.first_name), asc(person.last_name), desc(person.age)] }
+#
+# @example Or without patching Kernel
+#     require 'sorting'
+#     people.sort_by { |person|
+#       [Sorting.asc(person.first_name), Sorting.asc(person.last_name), Sorting.desc(person.age)]
+#     }
+#
+# @example Care about nil values in your data
+#     require 'sorting/convenience'
+#     people.sort_by { |person|
+#       [asc(person.first_name, :nils_first), asc(person.first_name, :nils_last)]
+#     }
+#
+# @example Only care about nil values in your data
+#     [5,3,nil,9].sort_by { |x| x || Sorting::Bigger } # Sorting::Smaller is available too
+#
+# @example Care about expensive comparison values which may not always be needed
+#     # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
+#     # it might only be needed in a small number of cases.
+#     require 'sorting/convenience'
+#     items.sort_by { |item|
+#       [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
+#     }
+#
+module Sorting
+  class_eval(&Sorting::Helpers::MethodDefinitions)
+  module_function *Sorting::Helpers.private_instance_methods(false)
+end

data/lib/sorting/ascending.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+
+
+
+module Sorting
+
+  # This class is used to implement 'asc' (ascending) sorting.
+  # You should not need to use this class directly.
+  # You can `require 'sorting/convenience'` and then use Kernel#asc,
+  # or you can `require 'sorting'` and then use Sorting#asc (which
+  # is a module_function, and hence available as Sorting::asc)
+  #
+  # @see Sorting::Helpers
+  #   Sorting::Helpers is a module which provides you with a convenient .asc
+  #   forwarding method
+  #
+  # @see Sorting#asc
+  #   Sorting#asc is the common way to create a Sorting::Ascending instance
+  #
+  # @see Sorting::Descending
+  #   Sorting::Descending is the opposite of Sorting::Ascending
+  #
+  class Ascending
+
+    # Valid values for the treat_nils parameter of Sorting::Ascending#initialize
+    NilsValues = [:nils_first, :nils_last, nil]
+
+    include Comparable
+
+    # How nils values are treated
+    #
+    # @see NilsValues The list with all possible values
+    attr_reader :treat_nils
+
+    # @overload initialize(value, treat_nils=nil)
+    #
+    #   Create an ascending sorted value
+    #
+    #   @param [Comparable, #<=>] value
+    #     The value to compare.
+    #     Any object which implements <=> (or nil if you set treat_nils).
+    #
+    #   @param [nil, Symbol] treat_nils
+    #     One of nil, :nils_first, :nils_last. With nil, a normal exception
+    #     will be raised when compared with nil. With :nils_first, a nil will
+    #     always be considered smaller and hence be sorted to the beginning,
+    #     with :nils_last, a nil will always be considered bigger and hence be
+    #     sorted to the end.
+    #
+    #
+    # @overload initialize(treat_nils=nil, &value)
+    #
+    #   Create an ascending sorted value, where the value is lazily computed.
+    #   This is useful for values which are expensive to compute.
+    #
+    #   @param [nil, Symbol] treat_nils
+    #     One of nil, :nils_first, :nils_last. With nil, a normal exception
+    #     will be raised when compared with nil. With :nils_first, a nil will
+    #     always be considered smaller and hence be sorted to the beginning,
+    #     with :nils_last, a nil will always be considered bigger and hence be
+    #     sorted to the end.
+    #
+    #   @yieldreturn [Comparable, #<=>]
+    #     The value to compare.
+    #     Any object which implements <=> (or nil if you set treat_nils).
+    #
+    def initialize(*args, &lazy)
+      @memoized   = lazy ? false : true
+      @value      = lazy || args.first
+      @treat_nils = args[lazy ? 0 : 1]
+
+      unless NilsValues.include?(@treat_nils)
+        raise ArgumentError, "Invalid value for nils, expected :nils_first or :nils_last, got #{@treat_nils.inspect}"
+      end
+      if lazy
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 0..1" unless args.size.between?(0, 1)
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 1..2" unless args.size.between?(1, 2)
+      end
+    end
+
+    # Whether nils are always considered smaller.
+    def nils_first?
+      @treat_nils == :nils_first
+    end
+
+    # Whether nils are always considered bigger.
+    def nils_last?
+      @treat_nils == :nils_last
+    end
+
+    # @return [Comparable, #<=>, nil]
+    #   The comparable value. If the Ascending object was constructed with a
+    #   lazy block, the block will be executed the first time this method is
+    #   called.
+    #
+    def value
+      if @memoized
+        @value
+      else
+        @memoized = true
+        @value    = @value.call
+      end
+    end
+
+    # @return [-1, 0, 1, nil]
+    #   Comparison. Returns -1, 0, or +1 depending on whether `other` is less
+    #   than, equal to, or greater than `self`.
+    #   Comparison with nil is special cased when #treat_nils is set.
+    #   If #treat_nils is :nils_first, it will always return 1, if it is
+    #   :nils_last, it will always return -1.
+    #   Returns nil when the value could not be compared to with `other`.
+    #
+    def <=>(other)
+      my_value = value
+
+      if @treat_nils && my_value.nil?
+        @treat_nils == :nils_first ? -1 : 1
+      else
+        other_value = other.value
+
+        if @treat_nils && other_value.nil?
+          @treat_nils == :nils_first ? 1 : -1
+        else
+          my_value <=> other_value
+        end
+      end
+    end
+  end
+end

data/lib/sorting/bigger.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+
+
+
+module Sorting
+
+  # A value whose #<=> method will always compare as being the bigger value.
+  # Useful for defaultizing potentially nil values before comparing/sorting.
+  #
+  # @example
+  #     age = person.age || Sorting::Bigger
+  #
+  # @see Sorting::Smaller
+  #
+  module Bigger
+    extend Comparable
+
+    # @return [1]
+    #   Comparison. Pretends this object is bigger and hence always returns 1
+    #
+    def self.<=>(other)
+      1
+    end
+
+    # @private
+    # @see Numeric#coerce
+    #
+    def self.coerce(other)
+      [Smaller, self]
+    end
+
+    # @private
+    # @note
+    #   Rails' ActiveSupport patches DateTime incorrectly (doesn't use coerce).
+    #   This is a workaround
+    #
+    def self.to_datetime
+      self
+    end
+
+    # @private
+    # Enables comparisons with arrays
+    #
+    def self.to_ary
+      [self]
+    end
+
+    # @private
+    # @todo
+    #   (SR) Figure out why this ended up here. I (SR) think it was due to
+    #   some comparison failing without it, but I don't remember which.
+    #   The specific case should be documented.
+    #
+    def self.to_str
+      self
+    end
+
+    # @private
+    # @see Object#inspect
+    #
+    def self.inspect
+      "#<Sorting::Bigger>"
+    end
+  end
+end

data/lib/sorting/convenience.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+# The sorting/convenience.rb file adds Kernel#asc and Kernel#desc for
+# convenience. The methods are defined as module functions (see
+# Module#module_function), and hence also available as Kernel.asc and
+# Kernel.desc
+
+
+
+require 'sorting'
+
+
+
+# @private
+module Kernel
+  class_eval(&Sorting::Helpers::MethodDefinitions)
+  module_function *Sorting::Helpers.private_instance_methods(false)
+end

data/lib/sorting/descending.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+
+
+require 'sorting/ascending'
+
+
+
+module Sorting
+
+  # This class is used to implement 'desc' (descending) sorting.
+  # You should not need to use this class directly.
+  # You can `require 'sorting/convenience'` and then use Kernel#desc,
+  # or you can `require 'sorting'` and then use Sorting#desc (which
+  # is a module_function, and hence available as Sorting::desc)
+  #
+  # @see Sorting::Helpers
+  #   Sorting::Helpers is a module which provides you with a convenient .desc
+  #   forwarding method
+  #
+  # @see Sorting#desc
+  #   Sorting#desc is the common way to create a Sorting::Ascending instance
+  #
+  # @see Sorting::Descending
+  #   Sorting::Descending is the opposite of Sorting::Ascending
+  #
+  class Descending < Ascending
+
+    # @return [-1, 0, 1, nil]
+    #   Works reversed to how <=> works normally, i.e. it returns -1 when normal
+    #   <=> would return 1, and vice versa.
+    #   Comparison. Returns -1, 0, or +1 depending on whether `other` is greater
+    #   than, equal to, or less than `self`.
+    #   Comparison with nil is special cased when #treat_nils is set.
+    #   If #treat_nils is :nils_first, it will always return 1, if it is
+    #   :nils_last, it will always return -1.
+    #   Returns nil when the value could not be compared to with `other`.
+    #
+    def <=>(other)
+      my_value = value
+
+      if @treat_nils && my_value.nil?
+        @treat_nils == :nils_first ? -1 : 1
+      else
+        other_value = other.value
+
+        if @treat_nils && other_value.nil?
+          @treat_nils == :nils_first ? 1 : -1
+        else
+          other_value <=> my_value
+        end
+      end
+    end
+  end
+end

data/lib/sorting/helpers.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+
+
+require 'sorting/ascending'
+require 'sorting/descending'
+
+
+
+module Sorting
+
+  # This module provides convenience methods to create Sorting::Ascending and
+  # Sorting::Descending instances.
+  module Helpers
+
+    # The proc with the method definitions of asc and desc.
+    # They are in a proc so the proc can be class_eval'ed in Sorting and Kernel
+    # to avoid an issue with methods of modules which are included in another
+    # module not being properly shared
+    #
+    MethodDefinitions = proc {
+
+      # Convenience method to create a Sorting::Ascending instance.
+      # Works exactly the same as {Sorting::Ascending#initialize}
+      def asc(*args, &lazy)
+        Sorting::Ascending.new(*args, &lazy)
+      end
+      private :asc
+
+      # Convenience method to create a Sorting::Descending instance.
+      # Works exactly the same as {Sorting::Ascending#initialize Descending#initialize}
+      def desc(*args, &lazy)
+        Sorting::Descending.new(*args, &lazy)
+      end
+      private :desc
+    }
+
+    class_eval(&MethodDefinitions)
+  end
+end

data/lib/sorting/smaller.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+
+
+
+module Sorting
+
+  # A value whose #<=> method will always compare as being the smaller value.
+  # Useful for defaultizing potentially nil values before comparing/sorting.
+  #
+  # @example
+  #     age = person.age || Sorting::Smaller
+  #
+  # @see Sorting::Bigger
+  #
+  module Smaller
+    extend Comparable
+
+    # @return [-1]
+    #   Comparison. Pretends this object is smaller and hence always returns -1
+    #
+    def self.<=>(other)
+      -1
+    end
+
+    # @private
+    # @see Numeric#coerce
+    #
+    def self.coerce(other)
+      [Bigger, self]
+    end
+
+    # @private
+    # @note
+    #   Rails' ActiveSupport patches DateTime incorrectly (doesn't use coerce).
+    #   This is a workaround
+    #
+    def self.to_datetime
+      self
+    end
+
+    # @private
+    # @todo
+    #   (SR) Figure out why this ended up here. I (SR) think it was due to
+    #   some comparison failing without it, but I don't remember which.
+    #   The specific case should be documented.
+    #
+    def self.to_str
+      self
+    end
+
+    # @private
+    # Enables comparisons with arrays
+    #
+    def self.to_ary
+      [self]
+    end
+
+    # @private
+    # @see Object#inspect
+    #
+    def self.inspect
+      "#<Sorting::Smaller>"
+    end
+  end
+end

data/lib/sorting/version.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+begin
+  require 'rubygems/version' # newer rubygems use this
+rescue LoadError
+  require 'gem/version' # older rubygems use this
+end
+
+module Sorting
+
+  # The version of the sorting gem.
+  Version = Gem::Version.new("0.0.1")
+end

data/sorting.gemspec

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name                      = "sorting"
+  s.version                   = "0.0.1"
+  s.authors                   = "Stefan Rusterholz"
+  s.email                     = "stefan.rusterholz@gmail.com"
+  s.homepage                  = "https://github.com/apeiros/sorting"
+
+  s.description               = <<-DESCRIPTION.gsub(/^    /, '').chomp
+    Helpful functionality for sorting and comparing.
+  DESCRIPTION
+  s.summary                   = <<-SUMMARY.gsub(/^    /, '').chomp
+    Helpful functionality for sorting and comparing.
+  SUMMARY
+
+  s.files                     =
+    Dir['bin/**/*'] +
+    Dir['lib/**/*'] +
+    Dir['rake/**/*'] +
+    Dir['test/**/*'] +
+    Dir['*.gemspec'] +
+    %w[
+      .yardopts
+      LICENSE.txt
+      Rakefile
+      README.markdown
+    ]
+  s.require_paths             = %w[lib]
+  if File.directory?('bin') then
+    executables = Dir.chdir('bin') { Dir.glob('**/*').select { |f| File.executable?(f) } }
+    s.executables = executables unless executables.empty?
+  end
+
+  s.required_ruby_version     = ">= 1.9.2"
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1")
+  s.rubygems_version          = "1.3.1"
+  s.specification_version     = 3
+end

data/test/lib/sorting_test/assertions.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Test::Unit::Assertions
+  # Add your custom assertions here
+end

data/test/lib/sorting_test/helper.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+require 'stringio'
+require 'yaml'
+require 'test/unit/assertions'
+require 'sorting_test/assertions'
+
+
+PROJECT_DIR = File.expand_path('../../../../', __FILE__)
+TEST_DIR    = File.join(PROJECT_DIR, 'test')
+
+module TestSuite
+  attr_accessor :name
+end
+
+module Kernel
+  def suite(name, &block)
+    klass = Class.new(Test::Unit::TestCase)
+    klass.extend TestSuite
+    klass.name = "Suite #{name}"
+    klass.class_eval(&block)
+
+    klass
+  end
+  module_function :suite
+end
+
+class Test::Unit::TestCase
+  def self.suite(name, &block)
+    klass = Class.new(Test::Unit::TestCase)
+    klass.extend TestSuite
+    klass.name = "#{self.name} #{name}"
+    klass.class_eval(&block)
+
+    klass
+  end
+
+  def self.test(desc, &impl)
+    define_method("test #{desc}", &impl)
+  end
+
+  def capture_stdout
+    captured  = StringIO.new
+    $stdout   = captured
+    yield
+    captured.string
+  ensure
+    $stdout = STDOUT
+  end
+end

data/test/runner.rb

@@ -0,0 +1,19 @@
+# run with `ruby test/runner.rb`
+# if you only want to run a single test-file: `ruby test/runner.rb testfile.rb`
+
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
+$LOAD_PATH << File.expand_path('../../test/lib', __FILE__)
+
+require 'test/unit'
+require 'sorting_test/helper'
+
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start
+end
+
+units = ARGV.empty? ? Dir["#{TEST_DIR}/unit/**/*.rb"] : ARGV
+
+units.each do |unit|
+  load unit
+end

data/test/unit/sorting/test_ascending_descending.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+require 'sorting/convenience'
+
+suite "Sorting" do
+  suite "Ascending" do
+    test "#initialize" do
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(0)
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(0, nil)
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(0, :nils_first)
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(0, :nils_last)
+      assert_raises ArgumentError do Sorting::Ascending.new(0, :invalid) end
+
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new { 0 }
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(nil) { 0 }
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(:nils_first) { 0 }
+      assert_instance_of Sorting::Ascending, Sorting::Ascending.new(:nils_last) { 0 }
+      assert_raises ArgumentError do Sorting::Ascending.new(:invalid) { 0 } end
+    end
+
+    test "#treat_nils" do
+      assert_equal nil,         Sorting::Ascending.new(0).treat_nils
+      assert_equal nil,         Sorting::Ascending.new(0, nil).treat_nils
+      assert_equal :nils_first, Sorting::Ascending.new(0, :nils_first).treat_nils
+      assert_equal :nils_last,  Sorting::Ascending.new(0, :nils_last).treat_nils
+    end
+
+    test "#nils_first?" do
+      assert_equal false, Sorting::Ascending.new(0).nils_first?
+      assert_equal false, Sorting::Ascending.new(0, nil).nils_first?
+      assert_equal true,  Sorting::Ascending.new(0, :nils_first).nils_first?
+      assert_equal false, Sorting::Ascending.new(0, :nils_last).nils_first?
+    end
+
+    test "#nils_last?" do
+      assert_equal false, Sorting::Ascending.new(0).nils_last?
+      assert_equal false, Sorting::Ascending.new(0, nil).nils_last?
+      assert_equal false, Sorting::Ascending.new(0, :nils_first).nils_last?
+      assert_equal true,  Sorting::Ascending.new(0, :nils_last).nils_last?
+    end
+
+    test "#value" do
+      value = Object.new
+      assert_equal value, Sorting::Ascending.new(value).value
+    end
+
+    test "#<=>" do
+      assert_equal  -1, Sorting::Ascending.new(0) <=> Sorting::Ascending.new(1)
+      assert_equal   0, Sorting::Ascending.new(1) <=> Sorting::Ascending.new(1)
+      assert_equal   1, Sorting::Ascending.new(1) <=> Sorting::Ascending.new(0)
+      assert_equal nil, Sorting::Ascending.new(0) <=> Sorting::Ascending.new(nil)
+      assert_equal  -1, Sorting::Ascending.new(0, :nils_last) <=> Sorting::Ascending.new(nil)
+      assert_equal   1, Sorting::Ascending.new(0, :nils_first) <=> Sorting::Ascending.new(nil)
+
+      assert_equal  -1, Sorting::Ascending.new { 0 } <=> Sorting::Ascending.new { 1 }
+      assert_equal   0, Sorting::Ascending.new { 1 } <=> Sorting::Ascending.new { 1 }
+      assert_equal   1, Sorting::Ascending.new { 1 } <=> Sorting::Ascending.new { 0 }
+      assert_equal nil, Sorting::Ascending.new { 0 } <=> Sorting::Ascending.new { nil }
+      assert_equal  -1, Sorting::Ascending.new(:nils_last) { 0 } <=> Sorting::Ascending.new { nil }
+      assert_equal   1, Sorting::Ascending.new(:nils_first) { 0 } <=> Sorting::Ascending.new { nil }
+    end
+  end
+
+
+
+  suite "Descending" do
+    test "#initialize" do
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(0)
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(0, nil)
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(0, :nils_first)
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(0, :nils_last)
+      assert_raises ArgumentError do Sorting::Descending.new(0, :invalid) end
+
+      assert_instance_of Sorting::Descending, Sorting::Descending.new { 0 }
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(nil) { 0 }
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(:nils_first) { 0 }
+      assert_instance_of Sorting::Descending, Sorting::Descending.new(:nils_last) { 0 }
+      assert_raises ArgumentError do Sorting::Descending.new(:invalid) { 0 } end
+    end
+
+    test "#treat_nils" do
+      assert_equal nil,         Sorting::Descending.new(0).treat_nils
+      assert_equal nil,         Sorting::Descending.new(0, nil).treat_nils
+      assert_equal :nils_first, Sorting::Descending.new(0, :nils_first).treat_nils
+      assert_equal :nils_last,  Sorting::Descending.new(0, :nils_last).treat_nils
+    end
+
+    test "#nils_first?" do
+      assert_equal false, Sorting::Descending.new(0).nils_first?
+      assert_equal false, Sorting::Descending.new(0, nil).nils_first?
+      assert_equal true,  Sorting::Descending.new(0, :nils_first).nils_first?
+      assert_equal false, Sorting::Descending.new(0, :nils_last).nils_first?
+    end
+
+    test "#nils_last?" do
+      assert_equal false, Sorting::Descending.new(0).nils_last?
+      assert_equal false, Sorting::Descending.new(0, nil).nils_last?
+      assert_equal false, Sorting::Descending.new(0, :nils_first).nils_last?
+      assert_equal true,  Sorting::Descending.new(0, :nils_last).nils_last?
+    end
+
+    test "#<=>" do
+      assert_equal   1, Sorting::Descending.new(0) <=> Sorting::Descending.new(1)
+      assert_equal   0, Sorting::Descending.new(1) <=> Sorting::Descending.new(1)
+      assert_equal  -1, Sorting::Descending.new(1) <=> Sorting::Descending.new(0)
+      assert_equal nil, Sorting::Descending.new(0) <=> Sorting::Descending.new(nil)
+      assert_equal  -1, Sorting::Descending.new(0, :nils_last) <=> Sorting::Descending.new(nil)
+      assert_equal   1, Sorting::Descending.new(0, :nils_first) <=> Sorting::Descending.new(nil)
+
+      assert_equal   1, Sorting::Descending.new { 0 } <=> Sorting::Descending.new { 1 }
+      assert_equal   0, Sorting::Descending.new { 1 } <=> Sorting::Descending.new { 1 }
+      assert_equal  -1, Sorting::Descending.new { 1 } <=> Sorting::Descending.new { 0 }
+      assert_equal nil, Sorting::Descending.new { 0 } <=> Sorting::Descending.new { nil }
+      assert_equal  -1, Sorting::Descending.new(:nils_last) { 0 } <=> Sorting::Descending.new { nil }
+      assert_equal   1, Sorting::Descending.new(:nils_first) { 0 } <=> Sorting::Descending.new { nil }
+    end
+  end
+end

data/test/unit/sorting/test_convenience.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+require 'sorting/convenience'
+
+suite "File sorting/convenience" do
+  test "Kernel#asc" do
+    assert_instance_of Sorting::Ascending, asc(0), "Kernel#asc is present"
+    assert_raises NoMethodError, "Kernel#asc is private" do Object.new.asc(0) end
+  end
+
+  test "Kernel::asc" do
+    assert_instance_of Sorting::Ascending, Kernel.asc(0), "Kernel::asc is present"
+  end
+
+  test "Sorting#asc" do
+    obj = Object.new.tap { |o| o.extend Sorting }
+    assert_instance_of Sorting::Ascending, obj.send(:asc, 0), "Sorting#asc is present" # bad test, since Kernel#asc exists too :-/
+    assert_raises NoMethodError, "Sorting#asc is private" do obj.asc(0) end
+  end
+
+  test "Sorting::asc" do
+    assert_instance_of Sorting::Ascending, Sorting.asc(0), "Sorting::asc is present"
+  end
+
+  test "Sorting::Helpers#asc" do
+    obj = Object.new.tap { |o| o.extend Sorting::Helpers }
+    assert_instance_of Sorting::Ascending, obj.send(:asc, 0), "Sorting#asc is present" # bad test, since Kernel#asc exists too :-/
+    assert_raises NoMethodError, "Sorting::Helpers#asc is private" do obj.asc(0) end
+  end
+
+
+
+  test "Kernel#desc" do
+    assert_instance_of Sorting::Descending, desc(0), "Kernel#desc is present"
+    assert_raises NoMethodError, "Kernel#desc is private" do Object.new.desc(0) end
+  end
+
+  test "Kernel::desc" do
+    assert_instance_of Sorting::Descending, Kernel.desc(0), "Kernel::desc is present"
+  end
+
+  test "Sorting#desc" do
+    obj = Object.new.tap { |o| o.extend Sorting }
+    assert_instance_of Sorting::Descending, obj.send(:desc, 0), "Sorting#desc is present" # bad test, since Kernel#desc exists too :-/
+    assert_raises NoMethodError, "Sorting#desc is private" do obj.desc(0) end
+  end
+
+  test "Sorting::desc" do
+    assert_instance_of Sorting::Descending, Sorting.desc(0), "Sorting::desc is present"
+  end
+
+  test "Sorting::Helpers#desc" do
+    obj = Object.new.tap { |o| o.extend Sorting::Helpers }
+    assert_instance_of Sorting::Descending, obj.send(:desc, 0), "Sorting#desc is present" # bad test, since Kernel#desc exists too :-/
+    assert_raises NoMethodError, "Sorting::Helpers#desc is private" do obj.desc(0) end
+  end
+end

data/test/unit/sorting/test_smaller_bigger.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+require 'sorting/convenience'
+require 'date'
+
+suite "Sorting" do
+  suite "Smaller" do
+    test "#<=>" do
+      assert_equal  -1, Sorting::Smaller <=> 1
+      assert_equal  -1, Sorting::Smaller <=> Time.now
+      assert_equal  -1, Sorting::Smaller <=> Date.today
+      assert_equal  -1, Sorting::Smaller <=> Float::INFINITY
+      assert_equal  -1, Sorting::Smaller <=> "Some String"
+      assert_equal  -1, Sorting::Smaller <=> ["an", "array"]
+      assert_equal  -1, Sorting::Smaller <=> Object.new
+
+      assert_equal  1, 1 <=> Sorting::Smaller
+      assert_equal  1, Time.now <=> Sorting::Smaller
+      assert_equal  1, Date.today <=> Sorting::Smaller
+      assert_equal  1, Float::INFINITY <=> Sorting::Smaller
+      assert_equal  1, "Some String" <=> Sorting::Smaller
+      assert_equal  1, ["an", "array"] <=> Sorting::Smaller
+    end
+  end
+
+  suite "Bigger" do
+    test "#<=>" do
+      assert_equal  1, Sorting::Bigger <=> 1
+      assert_equal  1, Sorting::Bigger <=> Time.now
+      assert_equal  1, Sorting::Bigger <=> Date.today
+      assert_equal  1, Sorting::Bigger <=> Float::INFINITY
+      assert_equal  1, Sorting::Bigger <=> "Some String"
+      assert_equal  1, Sorting::Bigger <=> ["an", "array"]
+      assert_equal  1, Sorting::Bigger <=> Object.new
+
+      assert_equal  -1, 1 <=> Sorting::Bigger
+      assert_equal  -1, Time.now <=> Sorting::Bigger
+      assert_equal  -1, Date.today <=> Sorting::Bigger
+      assert_equal  -1, Float::INFINITY <=> Sorting::Bigger
+      assert_equal  -1, "Some String" <=> Sorting::Bigger
+      assert_equal  -1, ["an", "array"] <=> Sorting::Bigger
+    end
+  end
+end

data/test/unit/sorting/test_sorting.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'sorting/convenience'
+
+suite "Sorting" do
+  test "#asc" do
+    assert_equal [1,2,3], [3,1,2].sort_by { |x| asc(x) }
+  end
+
+  test "#asc with :nils_last" do
+    assert_equal [1,2,3,nil], [3,nil,1,2].sort_by { |x| asc(x, :nils_last) }
+  end
+
+  test "#asc with :nils_first" do
+    assert_equal [nil,1,2,3], [3,nil,1,2].sort_by { |x| asc(x, :nils_first) }
+  end
+
+  test "#asc with lazy evaluation" do
+    assert_equal [1,2,3], [3,1,2].sort_by { |x| asc { x } }
+  end
+
+  test "#asc with lazy evaluation and :nils_last" do
+    assert_equal [1,2,3,nil], [3,nil,1,2].sort_by { |x| asc(:nils_last) { x } }
+  end
+
+  test "#asc with lazy evaluation and :nils_first" do
+    assert_equal [nil,1,2,3], [3,nil,1,2].sort_by { |x| asc(:nils_first) { x } }
+  end
+
+  test "#desc" do
+    assert_equal [3,2,1], [3,1,2].sort_by { |x| desc(x) }
+  end
+
+  test "#desc with :nils_last" do
+    assert_equal [3,2,1,nil], [3,nil,1,2].sort_by { |x| desc(x, :nils_last) }
+  end
+
+  test "#desc with :nils_first" do
+    assert_equal [nil,3,2,1], [3,nil,1,2].sort_by { |x| desc(x, :nils_first) }
+  end
+
+  test "#desc with lazy evaluation" do
+    assert_equal [3,2,1], [3,1,2].sort_by { |x| desc { x } }
+  end
+
+  test "#desc with lazy evaluation and :nils_last" do
+    assert_equal [3,2,1,nil], [3,nil,1,2].sort_by { |x| desc(:nils_last) { x } }
+  end
+
+  test "#desc with lazy evaluation and :nils_first" do
+    assert_equal [nil,3,2,1], [3,nil,1,2].sort_by { |x| desc(:nils_first) { x } }
+  end
+
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: sorting
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Stefan Rusterholz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-22 00:00:00.000000000 Z
+dependencies: []
+description: Helpful functionality for sorting and comparing.
+email: stefan.rusterholz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sorting/ascending.rb
+- lib/sorting/bigger.rb
+- lib/sorting/convenience.rb
+- lib/sorting/descending.rb
+- lib/sorting/helpers.rb
+- lib/sorting/smaller.rb
+- lib/sorting/version.rb
+- lib/sorting.rb
+- test/lib/sorting_test/assertions.rb
+- test/lib/sorting_test/helper.rb
+- test/runner.rb
+- test/unit/sorting/test_ascending_descending.rb
+- test/unit/sorting/test_convenience.rb
+- test/unit/sorting/test_smaller_bigger.rb
+- test/unit/sorting/test_sorting.rb
+- sorting.gemspec
+- .yardopts
+- LICENSE.txt
+- Rakefile
+- README.markdown
+homepage: https://github.com/apeiros/sorting
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Helpful functionality for sorting and comparing.
+test_files: []
+has_rdoc: