Class: Arrow::SortKey

Inherits:
Object
  • Object
show all
Defined in:
lib/arrow/sort-key.rb,
lib/arrow/jruby/sort-key.rb

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target) ⇒ SortKey #initialize(target, order) ⇒ SortKey #initialize(target, order, null_placement) ⇒ SortKey

Creates a new Arrow::SortKey.

Overloads:

  • #initialize(target) ⇒ SortKey

    Examples:

    String without any prefix

    key = Arrow::SortKey.new("count")
key.target         # => "count"
key.order          # => Arrow::SortOrder::ASCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    String with order prefix only

    key = Arrow::SortKey.new("-count")
key.target         # => "count"
key.order          # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    String with order and null placement prefixes

    key = Arrow::SortKey.new("-^count")
key.target         # => "count"
key.order          # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_START

    String with null placement prefix only

    key = Arrow::SortKey.new("^count")
key.target         # => "count"
key.order          # => Arrow::SortOrder::ASCENDING
key.null_placement # => Arrow::NullPlacement::AT_START

    Symbol (no prefix processing)

    key = Arrow::SortKey.new(:"-count")
key.target         # => "-count"
key.order          # => Arrow::SortOrder::ASCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    Parameters:

    • target (Symbol, String) —

      The name or dot path of the sort column.

      If target is a String, it may have prefix markers that specify the sort order and null placement. The format is [+/-][^/$]column:

      • "+" prefix means ascending order
      • "-" prefix means descending order
      • "^" prefix means nulls at start
      • "$" prefix means nulls at end

      If target is a Symbol, it is converted to String and used as-is (no prefix processing).

  • #initialize(target, order) ⇒ SortKey

    Examples:

    No leading order mark processing

    key = Arrow::SortKey.new("-count", :ascending)
key.target # => "-count"
key.order  # => Arrow::SortOrder::ASCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    Order by abbreviated target with Symbol

    key = Arrow::SortKey.new("count", :desc)
key.target # => "count"
key.order  # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    Order by String

    key = Arrow::SortKey.new("count", "descending")
key.target # => "count"
key.order  # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_END

    Order by Arrow::SortOrder, give null_placement with target

    key = Arrow::SortKey.new("^count", Arrow::SortOrder::DESCENDING)
key.target # => "count"
key.order  # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_START

    Parameters:

    • target (Symbol, String) —

      The name or dot path of the sort column.

      No leading order mark processing. The given target is used as-is.

    • order (Symbol, String, Arrow::SortOrder) —

      How to order by this sort key.

      If this is a Symbol or String, this must be :ascending, "ascending", :asc, "asc", :descending, "descending", :desc or "desc".

  • #initialize(target, order, null_placement) ⇒ SortKey

    Examples:

    With all explicit parameters

    key = Arrow::SortKey.new("count", :desc, :at_start)
key.target         # => "count"
key.order          # => Arrow::SortOrder::DESCENDING
key.null_placement # => Arrow::NullPlacement::AT_START

    Parameters:

    • target (Symbol, String) —

      The name or dot path of the sort column.

    • order (Symbol, String, Arrow::SortOrder) —

      How to order by this sort key.

      If this is a Symbol or String, this must be :ascending, "ascending", :asc, "asc", :descending, "descending", :desc or "desc".

    • null_placement (Symbol, String, Arrow::NullPlacement) —

      Where to place nulls and NaNs. Must be :at_start, "at_start", :at_end, or "at_end".

Since:

  • 4.0.0



177
178
179
180
181
182
 
# File 'lib/arrow/sort-key.rb', line 177

def initialize(target, order=nil, null_placement=nil)
  target, order, null_placement = normalize_target(target, order, null_placement)
  order = normalize_order(order) || :ascending
  null_placement = normalize_null_placement(null_placement) || :at_end
  initialize_raw(target, order, null_placement)
end

Class Method Details

.resolve(sort_key) ⇒ Arrow::SortKey .resolve(target) ⇒ Arrow::SortKey .resolve(target, order) ⇒ Arrow::SortKey

Ensure returning suitable Arrow::SortKey.

Overloads:

  • .resolve(sort_key) ⇒ Arrow::SortKey

    Returns the given sort key itself. This is convenient to use this method as Arrow::SortKey converter.

    Parameters:

    Returns:

  • .resolve(target) ⇒ Arrow::SortKey

    Creates a new suitable sort key from column name or dot path with leading order mark. See #initialize for details about order mark.

    Returns:

  • .resolve(target, order) ⇒ Arrow::SortKey

    Creates a new suitable sort key from column name or dot path without leading order mark and order. See #initialize for details.

    Returns:

Since:

  • 4.0.0



49
50
51
52
 
# File 'lib/arrow/sort-key.rb', line 49

def resolve(target, order=nil, null_placement=nil)
  return target if target.is_a?(self)
  new(target, order, null_placement)
end

.try_convert(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



55
56
57
58
59
60
61
62
 
# File 'lib/arrow/sort-key.rb', line 55

def try_convert(value)
  case value
  when Symbol, String
    new(value.to_s, :ascending, :at_end)
  else
    nil
  end
end

Instance Method Details

#name ⇒ Object

For backward compatibility



211
 
# File 'lib/arrow/sort-key.rb', line 211

alias_method :name, :target

#target ⇒ Object

Raises:

  • (NotImplementedError) 


20
21
22
 
# File 'lib/arrow/jruby/sort-key.rb', line 20

def target
  raise NotImplementedError
end

#to_s ⇒ String

Returns The string representation of this sort key. You can use recreate Arrow::SortKey by Arrow::SortKey.new(key.to_s).

Examples:

Recreate Arrow::SortKey

key = Arrow::SortKey.new("-count")
key.to_s # => "-$count"
key == Arrow::SortKey.new(key.to_s) # => true

Returns:

  • (String) —

    The string representation of this sort key. You can use recreate Arrow::SortKey by Arrow::SortKey.new(key.to_s).

Since:

  • 4.0.0



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/arrow/sort-key.rb', line 194

def to_s
  result = ""
  if order == SortOrder::ASCENDING
    result += "+"
  else
    result += "-"
  end
  if null_placement == NullPlacement::AT_START
    result += "^"
  else
    result += "$"
  end
  result += target
  result
end