[DOC] Tweaks for Array#shift (#11886)

This commit is contained in:
Burdette Lamar 2024-10-12 09:36:29 -05:00 committed by GitHub
parent afacb8ada5
commit 81910a93ff
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
Notes: git 2024-10-12 14:36:47 +00:00
Merged-By: peterzhu2118 <peter@peterzhu.ca>

45
array.c
View File

@ -1512,35 +1512,40 @@ rb_ary_shift(VALUE ary)
/* /*
* call-seq: * call-seq:
* array.shift -> object or nil * shift -> object or nil
* array.shift(n) -> new_array * shift(count) -> new_array or nil
* *
* Removes and returns leading elements. * Removes and returns leading elements from +self+.
* *
* When no argument is given, removes and returns the first element: * With no argument, removes and returns one element, if available,
* or +nil+ otherwise:
* *
* a = [:foo, 'bar', 2] * a = [0, 1, 2, 3]
* a.shift # => :foo * a.shift # => 0
* a # => ['bar', 2] * a # => [1, 2, 3]
* [].shift # => nil
* *
* Returns +nil+ if +self+ is empty. * With non-negative numeric argument +count+ given,
* removes and returns the first +count+ elements:
* *
* When positive Integer argument +n+ is given, removes the first +n+ elements; * a = [0, 1, 2, 3]
* returns those elements in a new +Array+: * a.shift(2) # => [0, 1]
* a # => [2, 3]
* a.shift(1.1) # => [2]
* a # => [3]
* a.shift(0) # => []
* a # => [3]
* *
* a = [:foo, 'bar', 2] * If +count+ is large,
* a.shift(2) # => [:foo, 'bar'] * removes and returns all elements:
* a # => [2]
* *
* If +n+ is as large as or larger than <tt>self.length</tt>, * a = [0, 1, 2, 3]
* removes all elements; returns those elements in a new +Array+: * a.shift(50) # => [0, 1, 2, 3]
* a # => []
* *
* a = [:foo, 'bar', 2] * If +self+ is empty, returns a new empty array.
* a.shift(3) # => [:foo, 'bar', 2]
* *
* If +n+ is zero, returns a new empty +Array+; +self+ is unmodified. * Related: see {Methods for Deleting}[rdoc-ref:Array@Methods+for+Deleting].
*
* Related: #push, #pop, #unshift.
*/ */
static VALUE static VALUE