Skip to content

Commit f81802d

Browse files
zakamezoffixznet
authored andcommitted
(Try to) clarify type smileys for .DEFINITE-ness (#1502)
Based on conversation with @zoffixznet, try to add more context (and definiteness) to the current elaboration for the `:D`, `:U`, and `:_` type constraints. I realize this is also a good place here to show type objects and instances, to support the concept of definiteness. Fixes #1469.
1 parent cc66622 commit f81802d

File tree

1 file changed

+37
-6
lines changed

1 file changed

+37
-6
lines changed

doc/Type/Signature.pod6

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -220,8 +220,10 @@ correct type.
220220
# (Str:D $: *%_)»
221221
say limit-lines "a \n b", Int # Always returns the max number of lines
222222
223-
In this case, we really only want to deal with defined strings. To do this, we
224-
use the C<:D> type constraint.
223+
In the code above, we really only want to deal with defined strings. To
224+
do this, we use the C<:D> type constraint. This constraint checks the
225+
value passed is an I<object instance>, in a similar fashion to calling
226+
the C<.DEFINITE> method on the value:
225227
226228
sub limit-lines(Str:D $s, Int $limit) { };
227229
say limit-lines Str, 3;
@@ -232,10 +234,12 @@ use the C<:D> type constraint.
232234
This is much better than the way the program failed before, since here the
233235
reason for failure is clearer.
234236
235-
It's also possible undefined types are the only ones that make sense for a
236-
routine to accept. This can be constrained with the C<:U> type constraint. For
237-
example, we can turn the C<&limit-lines> into a multi function to make use of
238-
the C<:U> constraint.
237+
It's also possible that undefined types are the only ones that make
238+
sense for a routine to accept. This can be done with the C<:U> type
239+
constraint, which checks the value passed if it is a I<type object>,
240+
rather than an object instance. For example, we can turn the
241+
C<&limit-lines> into a multi function to make use of the C<:U>
242+
constraint:
239243
240244
=for code :allow<B L>
241245
multi limit-lines(Str $s, Int:D $limit) { }
@@ -245,6 +249,33 @@ say limit-lines "a \n b \n c", Int; # OUTPUT: «"a \n b \n c"␤»
245249
For explicitly indicating the normal behaviour, C<:_> can be used, but this is
246250
unnecessary. C<:(Num:_ $)> is the same as C<:(Num $)>.
247251
252+
To recap, here is a quick illustration of these type constraints, also
253+
known collectively as I<type smileys>:
254+
255+
# Checking a type object
256+
say Int ~~ Any:D; # OUTPUT: «False␤»
257+
say Int ~~ Any:U; # OUTPUT: «True␤»
258+
say Int ~~ Any:_; # OUTPUT: «True␤»
259+
260+
# Checking an object instance
261+
say 42 ~~ Any:D; # OUTPUT: «True␤»
262+
say 42 ~~ Any:U; # OUTPUT: «False␤»
263+
say 42 ~~ Any:_; # OUTPUT: «True␤»
264+
265+
# Checking a user-supplied class
266+
class Foo {};
267+
say Foo ~~ Any:D; # OUTPUT: «False␤»
268+
say Foo ~~ Any:U; # OUTPUT: «True␤»
269+
say Foo ~~ Any:_; # OUTPUT: «True␤»
270+
my $f = Foo.new;
271+
say $f ~~ Any:D; # OUTPUT: «True␤»
272+
say $f ~~ Any:U; # OUTPUT: «False␤»
273+
say $f ~~ Any:_; # OUTPUT: «True␤»
274+
275+
The L<Classes and Objects|/language/classtut#Starting_with_class>
276+
document further elaborates on the concepts of instances and type
277+
objects and discovering them with the C<.DEFINITE> method.
278+
248279
=head3 X«Constraining signatures of Callables|function reference (constrain)»
249280
250281
To constrain L<block|/type/Block> and L<subroutine|/type/Sub> references based

0 commit comments

Comments
 (0)