arturoherrero/powercore

View on GitHub
README.md

Summary

Maintainability
Test Coverage
# PowerCore

[![Code Climate](https://codeclimate.com/github/arturoherrero/powercore/badges/gpa.svg)](https://codeclimate.com/github/arturoherrero/powercore)
[![Build Status](https://travis-ci.org/arturoherrero/powercore.svg?branch=master)](https://travis-ci.org/arturoherrero/powercore)

PowerCore extends the Ruby Core with useful extensions.

There are Ruby gems that do something similar, such as
[ActiveSuppor Core Extensions][1] or [Powerpack][2].

In this case, this is just a collection of extensions for reference, *not* a
Ruby gem. Who wants a new dependency in the code base? Just borrow the code
that you consider useful, but be careful; most of the time I have created new
methods but sometimes I have overridden the default Ruby implementation, or even
worse, I have removed Ruby methods to do some tricks. Come and see!

- [Array](#array)
  - [`average`](#average)
  - [Negative index `drop`](#negative-index-drop)
  - [`except`](#except)
  - [`fetch_dig`](#fetch_dig)
  - [`head`](#head)
  - [`histogram`](#histogram)
  - [`init`](#init)
  - [`mean`](#mean)
  - [`median`](#median)
  - [`mode`](#mode)
  - [`percentile`](#percentile)
  - [Negative index `take`](#negative-index-take)
  - [`tail`](#tail)
  - [`transpose` array of ranges](#transpose-array-of-ranges)
- [Date](#date)
  - [`now`](#now)
- [Integer](#integer)
  - [`clamp`](#clamp)
  - [`degrees`](#degrees)
  - [`negative`](#negative)
  - [`ordinal`](#ordinal)
- [Hash](#hash)
  - [`except`](#except-1)
  - [`fetch_dig`](#fetch_dig-1)
  - [`first`](#first)
  - [`head`](#head-1)
  - [`init`](#init-1)
  - [`last`](#last)
  - [`tail`](#tail-1)
- [Kernel](#kernel)
  - [`λ`](#λ)
- [Object](#object)
  - [`assert`](#assert)
  - [`in?`](#in)
  - [`metaclass`](#metaclass)
  - [`not_in?`](#not_in)
  - [`not_nil?`](#not_nil)
  - [Pipe operator](#pipe-operator)
- [Range](#range)
  - [`head`](#head-2)
  - [`init`](#init-2)
  - [`tail`](#tail-2)
- [String](#string)
  - [`first`](#first-1)
  - [`head`](#head-3)
  - [`init`](#init-3)
  - [`last`](#last-1)
  - [`tail`](#tail-3)
  - [`to_bool`](#to_bool)


## Array

#### `average`

Calculates the mean of the elements.

```ruby
[1, 2, 3, 4].average  # => 2.5
```

#### Negative index `drop`

Drops n elements from end of the array.

```ruby
[1, 2, 3, 4].drop(-2)  # => [1, 2]
```

If you pass a positive number, it delegates to the original implementation.

```ruby
[1, 2, 3, 4].drop(2)  # => [3, 4]
```

#### `except`

Returns the array without the indexes specified.

```ruby
[1, 2, 3, 4].except(1, 2)  # => [1, 4]
```

#### `fetch_dig`

Extracts the nested value specified by the sequence of indexes.

```ruby
[[1, [2, 3]]].fetch_dig(0, 1, 1)  # => 3
```

If the key can’t be found with no other arguments, it will raise an `IndexError` exception.

```ruby
[[1, [2, 3]]].fetch_dig(1, 2, 3)  # => IndexError
```

If the key can’t be found and an optional code block is specified, then that will be run and its result returned.

```ruby
[[1, [2, 3]]].fetch_dig(1, 2, 3) { 2 }  # => 2
```

#### `head`

Returns the head of the array.

```ruby
[1, 2, 3].head  # => 1
```

#### `histogram`

Builds the histogram in a hash.

```ruby
[2, 1, 2, 2, 3, 3].histogram  # => {1=>1, 2=>3, 3=>2}
```

#### `init`

The initial part of the array without its last element.

```ruby
[1, 2, 3].init  # => [1, 2]
```

#### `mean`

Calculates the mean of the elements.

```ruby
[1, 2, 3, 4].mean  # => 2.5
```

#### `median`

Calculates the median of the elements.

```ruby
[1, 2, 3, 4, 5].median  # => 3
[1, 2, 3, 4].median     # => 2.5
```

#### `mode`

Finds the mode value/s.

```ruby
[1, 2, 3, 4].mode     # => [1, 2, 3, 4]
[1, 2, 2, 4].mode     # => [2]
[1, 1, 2, 4, 4].mode  # => [1, 4]
```

#### `percentile`

Returns the percentile value for a given percentage.

```ruby
[1, 2, 3, 4].percentile(49)     # => 2
[1, 2, 3, 4].percentile(50)     # => 3
[1, 2, 3, 4, 5].percentile(50)  # => 3
```

#### Negative index `take`

Returns n elements from end of the array.

```ruby
[1, 2, 3, 4].take(-2)  # => [3, 4]
```

If you pass a positive number, it delegates to the original implementation.

```ruby
[1, 2, 3, 4].take(2)  # => [1, 2]
```

#### `tail`

Returns the tail of the array.

```ruby
[1, 2, 3, 4].tail  # => [2, 3, 4]
```

#### `transpose` array of ranges

Assumes that self is an array of ranges and transposes the rows and columns.

```ruby
[(1..2), (3..4)].transpose  # => [[1, 3], [2, 4]]
```

It also works with the original implementation, assuming an array of arrays.

```ruby
[[1, 2], [3, 4]].transpose  # => [[1, 3], [2, 4]]
```


## Date

#### `now`

Returns the current day.

```ruby
Date.now  # => #<Date: 2016-03-29 ((2457477j,0s,0n),+0s,2299161j)>
```


## Integer

#### `clamp`

Clamps a comparable between a lower and upper bound.

```ruby
1.clamp(3, 6)  # => 3
5.clamp(3, 6)  # => 5
8.clamp(3, 6)  # => 6

1.clamp(3..6)  # => 3
5.clamp(3..6)  # => 5
8.clamp(3..6)  # => 6
```

#### `degrees`

Converts a number of degrees into radians.

```ruby
90.degrees  # => 1.5707963267948966
```

#### `negative`

Negates the number.

```ruby
1.negative  # => -1
```

#### `ordinal`

Returns the ordinal of the number.

```ruby
1.ordinal  # => "1st"
2.ordinal  # => "2nd"
```


## Hash

#### `except`

Returns the hash without the keys specified.

```ruby
{ a: 1, b: nil, c: nil, d: 4 }.except(:b, :d)  # => {a: 1, c: nil}
```

#### `fetch_dig`

Extracts the nested value specified by the sequence of keys.

```ruby
{ foo: { bar: { baz: 1 } }}.fetch_dig(:foo, :bar, :baz)  # => 1
```

If the key can’t be found with no other arguments, it will raise an `KeyError` exception.

```ruby
{ foo: { bar: { baz: 1 } } }.fetch_dig(:foo, :zot, :xyz)  # => KeyError
```

If the key can’t be found and an optional code block is specified, then that will be run and its result returned.

```ruby
{ foo: { bar: { baz: 1 } } }.fetch_dig(:foo, :zot, :xyz) { 2 }  # => 2
```

#### `first`

Returns the first elements of the hash.

```ruby
{ a: 1, b: 2, c: 3 }.first     # => { a: 1 }
{ a: 1, b: 2, c: 3 }.first(2)  # => { a: 1, b: 2 }
```

#### `head`

Returns the first element of the hash.

```ruby
{ a: 1, b: 2, c: 3 }.head  # => { a: 1 }
```

#### `init`

The initial part of the hash without its last element.

```ruby
{ a: 1, b: 2, c: 3 }.init  # => { a: 1, b: 2 }
```

#### `last`

The initial part of the hash without its last element.

```ruby
{ a: 1, b: 2, c: 3 }.last  # => { c: 3 }
```

#### `tail`

The rest of the hash without its first element

```ruby
{ a: 1, b: 2, c: 3 }.tail  # => { b: 2, c: 3 }
```

## Kernel

#### `λ`

λ is lambda.

```ruby
my_proc = λ { }
```


## Object

#### `assert`

Asserts an expression.

```ruby
assert(1 == 2)  # => AssertError: AssertError
assert(1 == 1)  # => nil
```

#### `in?`

Returns true if self is present in the given object.

```ruby
1.in?([1, 2, 3])            # => true
"lo".in?("hello")           # => true
:b.in?({ a: 100, b: 200 })  # => true
```

#### `metaclass`

Returns the eigenclass.

```ruby
Object.new.metaclass  # => #<Class:#<Object:0x007fc6427d1058>>
```

#### `not_in?`

Returns true if self is not present in the given object.

```ruby
4.not_in?([1, 2, 3])            # => true
"mo".not_in?("hello")           # => true
:c.not_in?({ a: 100, b: 200 })  # => true
```

#### `not_nil?`

Returns true when an object is not nil.

```ruby
nil.not_nil?  # => false
1.not_nil?    # => true
```

#### Pipe operator

Pipe operator à la Bash/Elixir.

```ruby
[1, 2, 3] |
  ->(array)  { array.first } |
  ->(int)    { int.to_s } |
  ->(string) { string + "2" }
# => "12"

[1, 2, 3] | :first | :to_s | ->(s) { s + "2" }  # => "12"
```


## Range

#### `head`

Returns the first object in the range.

```ruby
(0..3).head      # => 0
("a".."z").head  # => "a"
```

#### `init`

The initial part of the range without its last element.

```ruby
(0..3).init      # => 0..2
("a".."z").init  # => "a".."y"
```

#### `tail`

The rest of the range without its first element.

```ruby
(0..3).tail      # => 1..3
("a".."z").tail  # => "b".."z"
```


## String

#### `first`

Returns the first characters of the string.

```ruby
"abc".first     # => "a"
"abc".first(2)  # => "ab"
```

#### `head`

Returns the first characters of the string.

```ruby
"abc".head  # => "a"
```

#### `init`

The initial part of the string without its last element.

```ruby
"abc".init  # => "ab"
```

#### `last`

Returns the last characters of the string.

```ruby
"abc".last     # => "c"
"abc".last(2)  # => "bc"
```

#### `tail`

The rest of the string without its first element.

```ruby
"abc".tail  # => "bc"
```

#### `to_bool`

Converts a string to boolean.

```ruby
"true".to_bool   # => true
"false".to_bool  # => false
```


## Who made this?

This was made by Arturo Herrero under the MIT License. Find me on Twitter
[@ArturoHerrero][3].


[1]: http://edgeguides.rubyonrails.org/active_support_core_extensions.html
[2]: https://github.com/bbatsov/powerpack
[3]: https://twitter.com/ArturoHerrero