Document Array#shift? (#4886)

crystal-lang · Sep 1, 2017 · dca2887 · dca2887
1 parent d1960a5
commit dca2887
Showing 1 changed file with 13 additions and 1 deletion.
diff --git a/src/array.cr b/src/array.cr
@@ -1454,7 +1454,7 @@ class Array(T)
   end
 
   # Removes the first value of `self`, at index 0. This method returns the removed value.
-  # Raises `IndexError` if array is of 0 size.
+  # If the array is empty, it raises `IndexError`.
   #
   # ```
   # a = ["a", "b", "c"]
@@ -1507,6 +1507,18 @@ class Array(T)
     ary
   end
 
+  # Removes the first value of `self`, at index 0. This method returns the removed value.
+  # If the array is empty, it returns `nil` without raising any error.
+  #
+  # ```
+  # a = ["a", "b"]
+  # a.shift? # => "a"
+  # a        # => ["b"]
+  # a.shift? # => "b"
+  # a        # => []
+  # a.shift? # => nil
+  # a        # => []
+  # ```
   def shift?
     shift { nil }
   end