Find your way
into Facets.

01 / GET READY

Install Facets

Facets 4.0.0 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.

gem install facets

gem 'facets', require: false

require: false keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.

02 / CHOOSE YOUR SCOPE

Load what fits

Most core extension methods are stored in individual files. You can require one method, a class's core methods, or the core collection.

# One method
require 'facets/array/to_ranges'

# A class's core extensions
require 'facets/string'

# Most core extensions
require 'facets'

The core collection is light. require 'facets' adds about 35 ms of load time and 2 MB of memory, loading roughly 860 methods from 448 small files. That covers the core library only; standard library extensions load only when you require them. (Measured with Ruby 3.3 on Linux; your numbers will vary.)

Standard library extensions are separate from the core collection. Require each one explicitly. For example, require 'facets/ostruct' loads Ruby's ostruct and the Facets additions for it.

03 / SEE IT WORK

A few useful facets

These examples use methods present in the 3.2 release.

require 'facets/array/to_ranges'
[1, 2, 3, 6, 7].to_ranges
#=> [1..3, 6..7]

require 'facets/string/dashcase'
'Ruby Facets'.dashcase
#=> "ruby-facets"

require 'facets/range/intersection'
Range.intersection(1..10, 5..15)
#=> 5..10

Extensions add methods to Ruby's existing classes. When combining libraries that extend the same classes, choose your requires deliberately and check for method name overlap.

04 / KEEP EXPLORING

Find the right method

RubyDoc.info hosts generated API documentation; check the displayed gem version when browsing. In the published 3.2.2 gem, lib/core belongs to the core collection and lib/standard contains separately loaded libraries. The source repository also contains unreleased changes, including a new lib/rails area.