Add `Array#extract!`

The method removes and returns the elements for which the block returns a true value.
If no block is given, an Enumerator is returned instead.

```
numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
odd_numbers = numbers.extract! { |number| number.odd? } # => [1, 3, 5, 7, 9]
numbers # => [0, 2, 4, 6, 8]
```

1 files changed, 13 insertions, 0 deletions

diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md
index dfd21915b0..f9fc7044ba 100644
--- a/guides/source/active_support_core_extensions.md
+++ b/guides/source/active_support_core_extensions.md
@@ -2156,6 +2156,19 @@ This method is an alias of `Array#<<`.
 
 NOTE: Defined in `active_support/core_ext/array/prepend_and_append.rb`.
 
+### Extracting
+
+The method `extract!` removes and returns the elements for which the block returns a true value.
+If no block is given, an Enumerator is returned instead.
+
+```ruby
+numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+odd_numbers = numbers.extract! { |number| number.odd? } # => [1, 3, 5, 7, 9]
+numbers # => [0, 2, 4, 6, 8]
+```
+
+NOTE: Defined in `active_support/core_ext/array/extract.rb`.
+
 ### Options Extraction
 
 When the last argument in a method call is a hash, except perhaps for a `&block` argument, Ruby allows you to omit the brackets: