non_empty_array 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5649876842392722eeb4b0764cf1f7a75045836547b988cf8d56c929e11220f9
-  data.tar.gz: 178a65237cbac3a32620c4d9eb07021588a47d236dcb23bbe3eb51dba3b67ddf
+  metadata.gz: c54d118eef824c4fffa241971f7c95b927f24597eab6eddc019a434be045160b
+  data.tar.gz: '053186e3e45956d92ee38c4a218228daa881c89c73de2e6b2172762b05283a8c'
 SHA512:
-  metadata.gz: 3dee92ab346f77a421739796263bef093e90f6b00cd9a40bfcae2daac74a36ee31c6fb0e50eb321a7b2be0928f1c731050757a240cd8fc6efb9e96ba370cd92a
-  data.tar.gz: '0196289c3deb5a81607cb1b9e4f2fba68d3e00e404a3ba2fe9d8b6e02d18245142891eafb9e25caaf8aaf3f61f53f796510a1f5b9cada3c6b0d3d8c0ef60fb1a'
+  metadata.gz: b8ebda3c33e1bf55e37f2b62bf62a08b1dd7d542fd7017244085084b5c2dc70df2a6cbb79af5f4885ab7a09bdb21637cce6f42e8ee1702be3df07356337e7fef
+  data.tar.gz: 6331e7a5f3e9d9bd9c1210c38e538e457ecd7a228dc2676fd53dff4ab2290425ea9eec7e0723721f77838b9cd8ddacd47170a77b1234b3f7c5820471d7c922be

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    non_empty_array (1.0.0)
+    non_empty_array (1.1.0)
       sorbet-runtime (>= 0.5.5890)
 
 GEM

data/README.md

@@ -1,12 +1,54 @@
+[![Gem Version](https://badge.fury.io/rb/non_empty_array.svg)](https://badge.fury.io/rb/non_empty_array) [![Build Status](https://travis-ci.com/dogweather/non_empty_array.svg?branch=master)](https://travis-ci.com/dogweather/non_empty_array)
+
 # NonEmptyArray
 
-An enumerable which is guaranteed to not be empty.
+An [enumerable](https://ruby-doc.org/core-2.7.1/Enumerable.html) which is guaranteed to not be empty. E.g., `#first`
+will never fail.
 
-Additionally, two methods which give access:
+Additionally, three methods which give access:
 
-* `last()`
-* `all_but_last()`
+* `#tail`
+* `#last`
+* `#all_but_last`
 
 And one method for mutating the list:
 
-* `push()`
+* `#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:
+
+```ruby
+require 'non_empty_array'
+
+a = NonEmptyArray.new()  # => Ruby error - missing parameter
+```
+
+```ruby
+require 'non_empty_array'
+
+a = NonEmptyArray.new(100, [200, 300])
+
+# Methods from Enumerable
+a.count()         # => 3
+a.max()           # => 300
+a.to_a()          # => [100, 200, 300]
+
+# Methods specific to NonEmptyArray
+a.last()          # => 300          Always succeeds - never returns a "no element" error.
+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](https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-List-NonEmpty.html).

data/lib/non_empty_array.rb

@@ -18,7 +18,7 @@ class NonEmptyArray
 
   sig { override.params(block: T.untyped).void }
   def each(&block)
-    _all.each(&block)
+    all_elements.each(&block)
   end
 
   sig { returns(T.untyped) }
@@ -28,9 +28,12 @@ class NonEmptyArray
 
   sig { returns(T::Array[T.untyped]) }
   def all_but_last
-    T.must(_all.slice(0..-2))
+    T.must(all_elements.slice(0..-2))
   end
 
+  sig { returns(T::Array[T.untyped]) }
+  attr_reader :tail
+
   sig { params(element: T.untyped).returns(NonEmptyArray) }
   def push(element)
     @tail.push(element)
@@ -40,7 +43,7 @@ class NonEmptyArray
   private
 
   sig { returns(T::Array[T.untyped]) }
-  def _all
+  def all_elements
     [@head] + @tail
   end
 end

data/non_empty_array.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |spec|
   spec.name          = 'non_empty_array'
-  spec.version       = '1.0.0'
+  spec.version       = '1.1.0'
   spec.authors       = ['Robb Shecter']
   spec.email         = ['robb@public.law']
 
   spec.summary       = 'An ordered list guaranteed to have at least one element.'
-  spec.description   = "Inspired by Haskell's NonEmptyList"
+  spec.description   = "Inspired by Haskell's NonEmpty list"
   spec.homepage      = 'https://github.com/dogweather/non_empty_array'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: non_empty_array
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Robb Shecter
@@ -38,7 +38,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.5890
-description: Inspired by Haskell's NonEmptyList
+description: Inspired by Haskell's NonEmpty list
 email:
 - robb@public.law
 executables: []