Gem Version Build Status

NonEmptyArray

An enumerable which is guaranteed to have at least one element. E.g., #first will never fail.

These four methods give non-empty-aware access:

Always succeed

  • #first
  • #last

May return an empty Array

  • #tail
  • #all_but_last

And one method for mutating the list:

  • #push

Why is this useful?

Sometimes I know that an Array isn't empty. In fact, it should never be empty, because otherwise, it means the object was set up incorrectly. The usual way to handle this is to check the array's length, or check for nil, and throw an exception if, for some reason, the Array is empty.

This NonEmptyArray approach saves this unnecessary work by moving the non-emptyness into the type system, letting Ruby check and prevent misuse. I.e., this class is designed so that it's impossible for it to be empty. And it has accessors like #last which always returns an element - it can never fail:

require 'non_empty_array'

a = NonEmptyArray.new()  # => Ruby error - missing parameter

require 'non_empty_array'

a = NonEmptyArray.new('1000')  # Simplest way to create one
a.count()       # => 1
a.push('2000')
a.count()       # => 2

require 'non_empty_array'

a = NonEmptyArray.new(100, [200, 300]).  # Creating from both the head and tail

# Methods from Enumerable
a.count()         # => 3
a.max()           # => 300
a.to_a()          # => [100, 200, 300]

# Methods specific to NonEmptyArray
a.first()         # => 100          Always succeeds - never returns a "no element" error.
a.last()          # => 300          Always succeeds
a.all_but_last()  # => [100, 200]   A normal array, which may indeed be empty.
a.push('400')
a.all_but_last()  # => [100, 200, 300]
a.tail()          # => [200, 300, 400]

Influenced by Haskell's NonEmpty List.