Type restrictions

Type restrictions are applied to method arguments to restrict the types accepted by that method.

  1. def add(x : Number, y : Number)
  2. x + y
  3. end
  4. # Ok
  5. add 1, 2
  6. # Error: no overload matches 'add' with types Bool, Bool
  7. add true, false

Note that if we had defined add without type restrictions, we would also have gotten a compile time error:

  1. def add(x, y)
  2. x + y
  3. end
  4. add true, false

The above code gives this compile error:

  1. Error in foo.cr:6: instantiating 'add(Bool, Bool)'
  2. add true, false
  3. ^~~
  4. in foo.cr:2: undefined method '+' for Bool
  5. x + y
  6. ^

This is because when you invoke add, it is instantiated with the types of the arguments: every method invocation with a different type combination results in a different method instantiation.

The only difference is that the first error message is a little more clear, but both definitions are safe in that you will get a compile time error anyway. So, in general, it’s preferable not to specify type restrictions and almost only use them to define different method overloads. This results in more generic, reusable code. For example, if we define a class that has a + method but isn’t a Number, we can use the add method that doesn’t have type restrictions, but we can’t use the add method that has restrictions.

  1. # A class that has a + method but isn't a Number
  2. class Six
  3. def +(other)
  4. 6 + other
  5. end
  6. end
  7. # add method without type restrictions
  8. def add(x, y)
  9. x + y
  10. end
  11. # OK
  12. add Six.new, 10
  13. # add method with type restrictions
  14. def restricted_add(x : Number, y : Number)
  15. x + y
  16. end
  17. # Error: no overload matches 'restricted_add' with types Six, Int32
  18. restricted_add Six.new, 10

Refer to the type grammar for the notation used in type restrictions.

Note that type restrictions do not apply to the variables inside the actual methods.

  1. def handle_path(path : String)
  2. path = Path.new(path) # *path* is now of the type Path
  3. # Do something with *path*
  4. end

self restriction

A special type restriction is self:

  1. class Person
  2. def ==(other : self)
  3. other.name == name
  4. end
  5. def ==(other)
  6. false
  7. end
  8. end
  9. john = Person.new "John"
  10. another_john = Person.new "John"
  11. peter = Person.new "Peter"
  12. john == another_john #=> true
  13. john == peter #=> false (names differ)
  14. john == 1 #=> false (because 1 is not a Person)

In the previous example self is the same as writing Person. But, in general, self is the same as writing the type that will finally own that method, which, when modules are involved, becomes more useful.

As a side note, since Person inherits Reference the second definition of == is not needed, since it’s already defined in Reference.

Note that self always represents a match against an instance type, even in class methods:

  1. class Person
  2. getter name : String
  3. def initialize(@name)
  4. end
  5. def self.compare(p1 : self, p2 : self)
  6. p1.name == p2.name
  7. end
  8. end
  9. john = Person.new "John"
  10. peter = Person.new "Peter"
  11. Person.compare(john, peter) # OK

You can use self.class to restrict to the Person type. The next section talks about the .class suffix in type restrictions.

Classes as restrictions

Using, for example, Int32 as a type restriction makes the method only accept instances of Int32:

  1. def foo(x : Int32)
  2. end
  3. foo 1 # OK
  4. foo "hello" # Error

If you want a method to only accept the type Int32 (not instances of it), you use .class:

  1. def foo(x : Int32.class)
  2. end
  3. foo Int32 # OK
  4. foo String # Error

The above is useful for providing overloads based on types, not instances:

  1. def foo(x : Int32.class)
  2. puts "Got Int32"
  3. end
  4. def foo(x : String.class)
  5. puts "Got String"
  6. end
  7. foo Int32 # prints "Got Int32"
  8. foo String # prints "Got String"

Type restrictions in splats

You can specify type restrictions in splats:

  1. def foo(*args : Int32)
  2. end
  3. def foo(*args : String)
  4. end
  5. foo 1, 2, 3 # OK, invokes first overload
  6. foo "a", "b", "c" # OK, invokes second overload
  7. foo 1, 2, "hello" # Error
  8. foo() # Error

When specifying a type, all elements in a tuple must match that type. Additionally, the empty-tuple doesn’t match any of the above cases. If you want to support the empty-tuple case, add another overload:

  1. def foo
  2. # This is the empty-tuple case
  3. end

A simple way to match against one or more elements of any type is to use Object as a restriction:

  1. def foo(*args : Object)
  2. end
  3. foo() # Error
  4. foo(1) # OK
  5. foo(1, "x") # OK

Free variables

You can make a type restriction take the type of an argument, or part of the type of an argument, using forall:

  1. def foo(x : T) forall T
  2. T
  3. end
  4. foo(1) #=> Int32
  5. foo("hello") #=> String

That is, T becomes the type that was effectively used to instantiate the method.

A free variable can be used to extract the type parameter of a generic type within a type restriction:

  1. def foo(x : Array(T)) forall T
  2. T
  3. end
  4. foo([1, 2]) #=> Int32
  5. foo([1, "a"]) #=> (Int32 | String)

To create a method that accepts a type name, rather than an instance of a type, append .class to a free variable in the type restriction:

  1. def foo(x : T.class) forall T
  2. Array(T)
  3. end
  4. foo(Int32) #=> Array(Int32)
  5. foo(String) #=> Array(String)

Multiple free variables can be specified too, for matching types of multiple arguments:

  1. def push(element : T, array : Array(T)) forall T
  2. array << element
  3. end
  4. push(4, [1, 2, 3]) # OK
  5. push("oops", [1, 2, 3]) # Error