Overloading

We can define a become_older method that accepts a number indicating the years to grow:

  1. class Person
  2.   getter :age
  4.   def initialize(@name : String, @age : Int = 0)
  5.   end
  7.   def become_older
  8.     @age += 1
  9.   end
  11.   def become_older(years)
  12.     @age += years
  13.   end
  14. end
  16. john = Person.new "John"
  17. john.age # => 0
  19. john.become_older
  20. john.age # => 1
  22. john.become_older 5
  23. john.age # => 6

That is, you can have different methods with the same name and different number of parameters and they will be considered as separate methods. This is called method overloading.

Methods overload by several criteria:

  • The number of parameters
  • The type restrictions applied to parameters
  • The names of required named parameters
  • Whether the method accepts a block or not

For example, we can define four different become_older methods:

  1. class Person
  2.   @age = 0
  4.   # Increases age by one
  5.   def become_older
  6.     @age += 1
  7.   end
  9.   # Increases age by the given number of years
  10.   def become_older(years : Int32)
  11.     @age += years
  12.   end
  14.   # Increases age by the given number of years, as a String
  15.   def become_older(years : String)
  16.     @age += years.to_i
  17.   end
  19.   # Yields the current age of this person and increases
  20.   # its age by the value returned by the block
  21.   def become_older(&)
  22.     @age += yield @age
  23.   end
  24. end
  26. person = Person.new "John"
  28. person.become_older
  29. person.age # => 1
  31. person.become_older 5
  32. person.age # => 6
  34. person.become_older "12"
  35. person.age # => 18
  37. person.become_older do |current_age|
  38.   current_age < 20 ? 10 : 30
  39. end
  40. person.age # => 28

Note that in the case of the method that yields, the compiler figured this out because there’s a yield expression. To make this more explicit, you can add a dummy &block parameter at the end:

  1. class Person
  2.   @age = 0
  4.   def become_older(&block)
  5.     @age += yield @age
  6.   end
  7. end

In generated documentation the dummy &block method will always appear, regardless of you writing it or not.

Given the same number of parameters, the compiler will try to sort them by leaving the less restrictive ones to the end:

  1. class Person
  2.   @age = 0
  4.   # First, this method is defined
  5.   def become_older(age)
  6.     @age += age
  7.   end
  9.   # Since "String" is more restrictive than no restriction
  10.   # at all, the compiler puts this method before the previous
  11.   # one when considering which overload matches.
  12.   def become_older(age : String)
  13.     @age += age.to_i
  14.   end
  15. end
  17. person = Person.new "John"
  19. # Invokes the first definition
  20. person.become_older 20
  22. # Invokes the second definition
  23. person.become_older "12"

However, the compiler cannot always figure out the order because there isn’t always a total ordering, so it’s always better to put less restrictive methods at the end.