Type coercion is the changing of an object's type into another type, together with its value. For example, changing an Integer into a String with #to_s or a Float into an Integer with #to_i. The perhaps lesser-known #to_str and #to_int methods some objects implement do the same at first glance, but there are some differences.

In this edition of AppSignal academy, we'll dive into explicitly casting and implicitly coercing types in Ruby, while briefy touching on typecasting actors. We'll cover the differences between both methods, and discuss how they're used.

Let's first look at how we usually coerce values to different types in Ruby with explicit casting helpers.

Explicit Casting Helpers

The most common casting helpers are #to_s, #to_i, #to_a and #to_h. These are explicit casting methods. They help us easily transform a value from one type to another.

The explicit helpers come with a clear promise. Whenever #to_s is called on an object, it'll always return a string, even if the object doesn't really convert to a string well. It's like casting Michael Keaton as Batman. You'll get a batman, even if a comedy actor isn't especially suited for the role.

Ruby offers these helper methods on almost any basic object in the Ruby standard library.

1:foo.to_s # => "foo"
210.0.to_i # => 10
3"10".to_i # => 10

These methods, especially #to_s, are implemented on most basic types in Ruby. While the casting almost always returns a value, the result may not be what we expect.

1"foo10".to_i          # => 0
2[1, 2, 3].to_s        # => "[1, 2, 3]"
3{ :foo => :bar }.to_s # => "{:foo=>:bar}"
4{ :foo => :bar }.to_a # => [[:foo, :bar]]
5Object.to_s           # => "Object"
6Object.new.to_s       # => "#<Object:0x00007f8e6d053a90>"

Calling the #to_s, #to_i, #to_a and #to_h helpers forces any value to the selected type. They return a representation of the type it's coerced to regardless of what happens to the value.

Implicit Coercion Methods

Calling type casting methods on values that do not act like the type we are casting to can cause errors or loss of data. Ruby also offers implicit coercion methods which only return a value when objects act like the type. This way we can be sure that the value acts like the type we want. These implicit coercion methods are #to_str, #to_int, #to_ary and #to_hash.

Implicit coercion is like casting Leonard Nimoy as any role but Spock. They'll work if the character is close enough to Spock, but fail if they're not. The #to_str helper tries to convert to a string, but will raise a NoMethodError if the object doesn't implement the method and can't be implicitly coerced.

110.to_int                           # => 10
210.0.to_int                         # => 10
3require "bigdecimal"
4BigDecimal.new("10.0000123").to_int # => 10
5
6# Unsuccessful coercions
7"10".to_int             # => NoMethodError
8"foo10".to_int          # => NoMethodError
9[1, 2, 3].to_str        # => NoMethodError
10{ :foo => :bar }.to_str # => NoMethodError
11{ :foo => :bar }.to_ary # => NoMethodError
12Object.to_str           # => NoMethodError
13Object.new.to_str       # => NoMethodError

We can see that Ruby is a bit more strict now in what it does and doesn't coerce to the requested types. If the coercion is not possible, the #to_* method is not implemented on the object and calling it raises a NoMethodError.

When using implicit coercions, e.g. #to_str, we ask the function to return a String object, only if the original type also acts like a String. For this reason, #to_str is only implemented on String in the Ruby Standard Library.

How Ruby Uses Implicit Coercion

Other than being more precise in what we're asking for during a coercion, what else is implicit coercion useful for? Turns out Ruby uses implicit coercions itself in a fair bit of scenarios. For instance, when combining objects with +.

1name = "world!"
2"Hello " + name # => "Hello world!"
3
4# Without #to_str
5class Name
6  def initialize(name)
7    @name = name
8  end
9end
10"Hello " + Name.new("world!") # => TypeError: no implicit conversion of Name into String

Here, we see Ruby raise a TypeError since it can't do an implicit conversion from the Name type to a String.

If we implement #to_str on the class, Ruby knows how to coerce the Name type.

1# With #to_str
2class Name
3  def to_str
4    @name
5  end
6end
7"Hello " + Name.new("world!") # => "Hello world!"

The same works for Arrays and #to_ary.

1class Options
2  def initialize
3    @internal = []
4  end
5
6  def <<(value)
7    @internal << value
8  end
9end
10
11options = Options.new
12options << :foo
13[:some_prefix] + options # => TypeError: no implicit conversion of Options into Array
14
15class Options
16  def to_ary
17    @internal
18  end
19end
20[:some_prefix] + options # => [:some_prefix, :foo]

But #to_ary is used in more scenarios. We can use it to destructure an Array into separate variables.

1options = Options.new
2options << :first
3options << :second
4options << :third
5first, second, third = options
6first  # => :first
7second # => :second
8third  # => :third

It also does conversion of the object into block parameters.

1[options].each do |(first, second)|
2  first # => :first
3  second # => :second
4end

There are more scenarios where the implicit coercion methods are used, such as #to_hash with **. This coerces the value to a hash with #to_hash before passing it to the parse_options method.

1class Options
2  def to_hash
3    # Create a hash from the Options Array
4    Hash[*@internal]
5  end
6end
7
8def parse_options(opts)
9  opts
10end
11
12options = Options.new
13options << :key
14options << :value
15parse_options(**options) # => {:key=>:value}

Enforcing Types

Ruby also offers more resilient coercion methods when the type is of an unknown type and we want to make sure we get the correct type. There's one for every basic type (String(...), Integer(...), Float(...), Array(...), Hash(...), etc.).

1String(self)       # => "main"
2String(self.class) # => "Object"
3String(123456)     # => "123456"
4String(nil)        # => ""
5
6Integer(123.999)   # => 123
7Integer("0x1b")    # => 27
8Integer(Time.new)  # => 1204973019
9Integer(nil)       # => TypeError: can't convert nil into Integer

The String(...) method first tries to call #to_str on the value, and when that fails, it calls its #to_s method. Not all objects define a #to_str method, therefore checking with both the implicit coercion (#to_str) and explicit (#to_s) casting methods increases the chances that the String conversion will work and you'll get the value you want. By first calling for implicit coercion we're more likely to get a result that has the same value but is of the coerced type, and not something like "#<Object:0x00007f8e6d053a90>".

1class MyString
2  def initialize(value)
3    @value = value
4  end
5
6  def to_str
7    @value
8  end
9end
10
11s = MyString.new("hello world")
12s.to_s    # => "#<MyString:0x...>"
13s.to_str  # => "hello world"
14String(s) # => "hello world"

You should only implement the implicit casting methods for objects that act like the to be coerced type, e.g. #to_str for your own String class.

Other than first trying implicit coercion, the String(...) helper also checks the returned type. #to_str is just a method which can return any type of value, even non-Strings. To ensure we get a value of the requested type String(...) raises a TypeError if the types don't match.

1class MyString
2  def to_str
3    nil
4  end
5end
6
7s = MyString.new("hello world")
8s.to_s    # => "#<MyString:0x...>"
9s.to_str  # => nil
10String(s) # => "#<MyString:0x...>"

Here, we can see that Ruby ignores the result of #to_str because it returned nil, which is not of the String-type. Instead, it falls back to the #to_s result.

If #to_s also returns nil and thus isn't of the correct type, String(...) will raise a TypeError.

1class MyString
2  def to_str
3    nil
4  end
5
6  def to_s
7    nil
8  end
9end
10
11s = MyString.new("hello world")
12s.to_s    # => nil
13s.to_str  # => nil
14String(s) # => TypeError: can't convert MyString to String (MyString#to_s gives NilClass)

While they may be more reliable in enforcing type coercion, note that the casting helper methods (String(...), Integer(...), etc.) are usually a bit slower as they need to perform more checks on the given value.

In Conclusion

When you want to make sure you're dealing with the right type of data for an object, type coercion is a useful process. In this post, we refreshed our knowledge of explicit casting helpers like #to_s, #to_i, #to_a and #to_h. We also looked at instances when implicit helpers like #to_str, #to_int, #to_ary and #to_hash are useful and how they're used by Ruby itself.

We hope you found this type coercion overview useful and how you found the actor typecasting analogy. As always, let us know if there's a topic you'd like us to cover. If you have any questions or comments, don't hesitate to drop us a line @AppSignal.