Class: Sorting::Ascending

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/sorting/ascending.rb

Overview

Note:

require 'sorting' loads this class

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)

Direct Known Subclasses

Descending

Constant Summary collapse

NilsValues =

Valid values for the treat_nils parameter of Sorting::Ascending#initialize

[:nils_first, :nils_last, nil]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value, treat_nils = nil) ⇒ Ascending #initialize(treat_nils = nil, &value) ⇒ Ascending

Returns a new instance of Ascending

Overloads:

  • #initialize(value, treat_nils = nil) ⇒ Ascending

    Create an ascending sorted value

    Parameters:

    • value (Comparable, #<=>)

      The value to compare. Any object which implements <=> (or nil if you set treat_nils).

    • treat_nils (nil, Symbol) (defaults to: nil)

      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.

  • #initialize(treat_nils = nil, &value) ⇒ Ascending

    Create an ascending sorted value, where the value is lazily computed. This is useful for values which are expensive to compute.

    Parameters:

    • treat_nils (nil, Symbol) (defaults to: nil)

      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.

    Yield Returns:

    • (Comparable, #<=>)

      The value to compare. Any object which implements <=> (or nil if you set treat_nils).


71
72
73
74
75
76
77
78
79
80
81
82
83
84
# File 'lib/sorting/ascending.rb', line 71

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

Instance Attribute Details

#treat_nilsObject (readonly)

How nils values are treated


37
38
39
# File 'lib/sorting/ascending.rb', line 37

def treat_nils
  @treat_nils
end

Instance Method Details

#<=>(other) ⇒ -1, ...

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.

Returns:

  • (-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.


118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# File 'lib/sorting/ascending.rb', line 118

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

#nils_first?Boolean

Whether nils are always considered smaller.

Returns:

  • (Boolean)

87
88
89
# File 'lib/sorting/ascending.rb', line 87

def nils_first?
  @treat_nils == :nils_first
end

#nils_last?Boolean

Whether nils are always considered bigger.

Returns:

  • (Boolean)

92
93
94
# File 'lib/sorting/ascending.rb', line 92

def nils_last?
  @treat_nils == :nils_last
end

#valueComparable, ...

Returns 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.

Returns:

  • (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.


101
102
103
104
105
106
107
108
# File 'lib/sorting/ascending.rb', line 101

def value
  if @memoized
    @value
  else
    @memoized = true
    @value    = @value.call
  end
end