To understand if you should use/implement to_s
/to_str
, let's look at some exemples. It is revealing to consider when these method fail.
1.to_s # returns "1"
Object.new.to_s # returns "#<Object:0x4932990>"
1.to_str # raises NoMethodError
Object.new.to_str # raises NoMethodError
As we can see, to_s
is happy to turn any object into a string. On the other hand, to_str
raises an error when its parameter does not look like a string.
Now let us look at Array#join
.
[1,2].join(',') # returns "1,2"
[1,2].join(3) # fails, the argument does not look like a valid separator.
It is useful that Array#join
converts to string the items in the array (whatever they really are) before joining them, so Array#join
calls to_s
on them.
However, the separator is supposed to be a string -- someone calling [1,2].join(3)
is likely to be making a mistake. This is why Array#join
calls to_str
on the separator.
The same principle seems to hold for the other methods. Consider to_a
/to_ary
on a hash:
{1,2}.to_a # returns [[1, 2]], an array that describes the hash
{1,2}.to_ary # fails, because a hash is not really an array.
In summary, here is how I see it:
- call
to_s
to get a string that describes the object.
- call
to_str
to verify that an object really acts like a string.
- implement
to_s
when you can build a string that describes your object.
- implement
to_str
when your object can fully behave like a string.
I think a case when you could implement to_str
yourself is maybe a ColoredString
class -- a string that has a color attached to it. If it seems clear to you that passing a colored comma to join
is not a mistake and should result in "1,2"
(even though that string would not be colored), then do implement to_str
on ColoredString.