Tools

A library of utility services and concerns.

Class: SleepingKingStudios::Tools::ArrayTools

Parent Namespace
SleepingKingStudios::Tools
Inherited Classes
SleepingKingStudios::Tools::Base > Object
Defined In
lib/sleeping_king_studios/tools/array_tools.rb

Table Of Contents

Overview

Tools for working with array-like enumerable objects.

Back To Top

Constants

ARRAY_METHODS

= %i[[] count each].freeze

Expected methods that an Array-like object should implement.

OTHER_METHODS

= %i[each_key each_pair].freeze

Methods that an Array-like object should not implement.

Back To Top

Class Methods

.instance => SleepingKingStudios::Tools::Base

Inherited From
SleepingKingStudios::Tools::Base

Returns

Back To Top

Instance Methods

#array?(obj) => Boolean

Returns true if the object is or appears to be an Array.

This method checks for the method signatures of the object. An Array-like method will define all of the the #[], #count, and #each methods, and neither of the #each_key or #each_pair methods.

Examples

ArrayTools.array?(nil)
#=> false

ArrayTools.array?([])
#=> true

ArrayTools.array?({})
#=> false

Parameters

Returns

#bisect(ary) => Array<Array<Object>>

Partitions the array into matching and non-matching items.

Separates the array into two arrays, the first containing all items in the original array that matches the provided block, and the second containing all items in the original array that do not match the provided block.

Examples

selected, rejected = ArrayTools.bisect([*0...10]) { |item| item.even? }
selected
#=> [0, 2, 4, 6, 8]
rejected
#=> [1, 3, 5, 7, 9]

Parameters

Yield Parameters

Yield Returns

Returns

Raises

#count_values(ary) => Hash{Object => Integer}
#count_values(ary, &block) => Hash{Object => Integer}

Also known as: tally

Counts the number of times each item or result appears in the object.

Overloads

#count_values(ary) => Hash{Object => Integer}

Counts the number of times each value appears in the enumerable object.

Examples
ArrayTools.count_values([1, 1, 1, 2, 2, 3])
#=> { 1 => 3, 2 => 2, 3 => 1 }
Parameters
  • ary (Array<Object>) — the values to count.
Returns
  • (Hash{Object => Integer}) — The number of times each value appears in the enumerable object.
Raises
  • (ArgumentError) — if the first argument is not an Array-like object.
#count_values(ary, &block) => Hash{Object => Integer}

Calls the block and counts the number of times each result appears.

Examples
ArrayTools.count_values([1, 1, 1, 2, 2, 3]) { |i| i ** 2 }
#=> { 1 => 3, 4 => 2, 9 => 1 }
Parameters
  • ary (Array<Object>) — the values to count.
Yield Parameters
  • item (Object) — an item in the array to matched.
Returns
  • (Hash{Object => Integer}) — the number of times each result appears.
Raises
  • (ArgumentError) — if the first argument is not an Array-like object.

#deep_dup(ary) => Array

Creates a deep copy of the object.

Iterates over the array and returns a new Array with deep copies of each array item.

Examples

ary = ['one', 'two', 'three']
cpy = ArrayTools.deep_dup ary

cpy << 'four'
#=> ['one', 'two', 'three', 'four']
ary
#=> ['one', 'two', 'three']

cpy.first.sub!(/on/, 'vu')
cpy
#=> ['vun', 'two', 'three', 'four']
ary
#=> ['one', 'two', 'three']

Parameters

Returns

Raises

See Also

#deep_freeze(ary) => Array

Freezes the array and performs a deep freeze on each array item.

Examples

ary = ['one', 'two', 'three']
ArrayTools.deep_freeze ary

ary.frozen?
#=> true
ary.first.frozen?
#=> true

Parameters

Returns

Raises

See Also

#humanize_list(ary, **options, &) => String

Generates a human-readable string representation of the list items.

Accepts a list of values and returns a human-readable string of the values, with the format based on the number of items.

Examples

With Zero Items

ArrayTools.humanize_list([])
#=> ''

With One Item

ArrayTools.humanize_list(['spam'])
#=> 'spam'

With Two Items

ArrayTools.humanize_list(['spam', 'eggs'])
#=> 'spam and eggs'

With Three Or More Items

ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'])
#=> 'spam, eggs, bacon, and spam'

With Three Or More Items And Options

ArrayTools.humanize_list(
  ['spam', 'eggs', 'bacon', 'spam'],
  :last_separator => ' or '
)
#=> 'spam, eggs, bacon, or spam'

Parameters

Options Hash (options)

Returns

Raises

#immutable?(ary) => Boolean

Checks if the array and its contents are immutable.

An array is considered immutable if the array itself is frozen and each item in the array is immutable.

Examples

ArrayTools.immutable?([1, 2, 3])
#=> false

ArrayTools.immutable?([1, 2, 3].freeze)
#=> true

ArrayTools.immutable?([+'ichi', +'ni', +'san'])
#=> false

ArrayTools.immutable?([+'ichi', +'ni', +'san'].freeze)
#=> false

ArrayTools.immutable?(['ichi', 'ni', 'san'].freeze)
#=> true

Parameters

Returns

Raises

See Also

#mutable?(ary) => Boolean

Checks if the array or any of its contents are mutable.

Parameters

Returns

Raises

See Also

#splice(ary, start, delete_count, *insert) => Array<Object>

Replaces a range of items in the array with the given items.

Examples

Deleting items from an Array

values = %w(katana wakizashi tachi daito shoto)
ArrayTools.splice values, 1, 2
#=> ['wakizashi', 'tachi']
values
#=> ['katana', 'daito', 'shoto']

Inserting items into an Array

values = %w(longsword broadsword claymore)
ArrayTools.splice values, 1, 0, 'zweihander'
#=> []
values
#=> ['longsword', 'zweihander', 'broadsword', 'claymore']

Inserting and deleting items

values = %w(shortbow longbow crossbow)
ArrayTools.splice values, 2, 1, 'arbalest', 'chu-ko-nu'
#=> ['crossbow']
values
#=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']

Parameters

Returns

Raises

Back To Top

Back to Documentation | Versions | 1.2 | Reference | SleepingKingStudios | SleepingKingStudios::Tools