Use built-in conversion functions

Indications

You really, really want to convert an input object into a core type, no matter what the original type is. For instance, you need to ensure that any input is coerced into an Integer if there is any reasonable way to do so; whether the incoming data is a Float, a nil, or even a hexidecimal string.

Synopsis

Use Ruby's capitalized conversion functions, such as Integer and Array.

Rationale

When a method's internals deal with core types, using a conversion function to pre-process input values allows maximum flexibility for inputs while preventing

nonsensical conversions.

Example: Pretty-printing numbers

Ruby's conversion methods don't stop with the #to_* methods discussed in previous sections. The Kernel module also provides a set of unusually-named conversion functions: Array(), Float(), String(), Integer(), Rational(), and Complex(). As you can see, these all break character for Ruby methods in that they begin with capital letters. Even more unusually, they each share a name with a Ruby core class. Technically, these are all ordinary methods; but we'll call them

"functions" since they are available everywhere and they interact only with their arguments, not with self.

Some standard libraries also provide capitalized conversion methods. The uri library provides the URI() method. And the pathname library defines, you guessed it… a Pathname() method.

For the most part, these capitalized conversion functions share two traits:

1. They are idempotent. Calling the method with an argument which is not of the target class will cause it to attempt a conversion. Calling it with an argument of the target type will simply return the unmodified argument.

2. They can convert a wider array of input types than the equivalent #to_*

methods.

Take the Integer() method, for example.

1. Given a Numeric value, it will convert it to an Integer or Bignum. A Floatwill be truncated.

2. It will convert strings containing integers in decimal, hexidecimal, octal, or binary formats to an integer value.

3. It will attempt to convert other objects using #to_int if it exists.

4. It will fall back to #to_i if none of the above rules apply.

To demonstrate:

Integer(10) # => 10

Integer(10.1) # => 10

Integer("0x10") # => 16 Integer("010") # => 8 Integer("0b10") # => 2

# Time defines #to_i

Integer(Time.now) # => 1341469768

Interestingly, despite accepting a wide array of inputs, the Integer function is actually more picky about string arguments than is String#to_i:

"ham sandwich".to_i # => 0 Integer("ham sandwich") # =>

# ~> -:2:in `Integer': invalid value for Integer(): "ham sandwich"

(ArgumentError)

# ~> from -:2:in `<main>'

When we call Integer(), we are effectively saying "convert this to an Integer, if there is any sensible way of doing so".

Here's a method which formats integers for human-readability. It doesn't much care what the class of the argument is, so long as it's convertable to an integer.

def pretty_int(value)

decimal = Integer(value).to_s

leader = decimal.slice!(0, decimal.length % 3) decimal.gsub!(/\d{3}(?!$)/,'\0,')

decimal = nil if decimal.empty?

leader = nil if leader.empty?

[leader,decimal].compact.join(",") end

pretty_int(1000) # => "1,000"

pretty_int(23) # => "23"

pretty_int(4567.8) # => "4,567"

pretty_int("0xCAFE") # => "51,966"

pretty_int(Time.now) # => "1,341,500,601"

Note that built-in conversion functions aren't completely consistent in their

operation. String(), for instance, simply calls #to_s on its argument. Consult the Kerneldocumentation [page 0] to learn more about how each conversion function works.

As I mentioned earlier, some standard libraries define conversion functions as well.

require 'pathname' require 'uri'

path = Pathname.new("/etc/hosts") # => #<Pathname:/etc/hosts>

Pathname(path) # => #<Pathname:/etc/hosts>

Pathname("/etc/hosts") # => #<Pathname:/etc/hosts>

uri_str = "http://example.org"

uri = URI.parse(uri_str) URI(uri_str)

# => #<URI::HTTP:0x0000000180a740 URL:http://example.org>

URI(uri)

# => #<URI::HTTP:0x00000001708748 URL:http://example.org>

As we can see, not only are these conversion functions a little more succinct than calling a constructor method; they are also idempotent. They can be called on an object of the target class and they will just return the original object.

Here's a method which, given a filename, reports the size of a file. The filename can be either a Pathname or something convertable to a Pathname.

require 'pathname' def file_size(filename)

filename = Pathname(filename) filename.size

end

file_size(Pathname.new("/etc/hosts")) # => 889 file_size("/etc/hosts") # => 889

Hash.[]

Before we move on from this discussion of Ruby's built-in conversion functions, we should discuss one odd duck of a method. Strangely, there is no Hash() conversion function. The closest thing to it is the subscript (square brackets) method on the Hashclass. Given an even-numbered list of arguments, Hash[] will produce a Hashwhere the first argument is a key, the second is a value, the third is a key, the fourth is its value, and so on. This is useful for converting flat arrays of keys and values into hashes.

inventory = ['apples', 17, 'oranges', 11, 'pears', 22]

Hash[*inventory]

# => {"apples"=>17, "oranges"=>11, "pears"=>22}

With its very specific expectations of how it will be called, Hash.[] bears almost nothing in common with conversion functions. However, since it is sometimes used to convert arrays to hashes I thought it worth a brief mention.

Conclusion

By using a conversion function, we ensure that an input will be converted to the expected type, while providing maximum leeway for the class of incoming objects.