A slightly gentler walk through :D/:U constraint examples

Author: cfa

doc/Type/Signature.pod6

@@ -214,7 +214,17 @@ part of the L<colon-pair|/type/Pair>.
          type constraint,:D;type constraint,:U;type constraint,:_>
 
 Normally, a type constraint only checks whether the value of the parameter is of the
-correct type.
+correct type. Crucially, both I<object instances> and I<type objects> will satisfy
+such a constraint as illustrated below:
+
+    say  42.WHAT     # OUTPUT: «(Int)␤»
+    say  42 ~~ Int   # OUTPUT: «True␤»
+    say Int ~~ Int   # OUTPUT: «True␤»
+
+Note how both C<42> and C<Int> satisfy the match.
+
+Sometimes we need to distinguish between these object instances (C<42>)
+and type objects (C<Int>). Consider the following code:
 
     sub limit-lines(Str $s, Int $limit) {
         my @lines = $s.lines;
@@ -229,10 +239,20 @@ correct type.
     #     (Str:D $: *%_)»
     say limit-lines "a \n b", Int # Always returns the max number of lines
 
-In the code above, we really only want to deal with string instances, not
-type objects. To do this, we use the C<:D> type constraint.  This constraint
-checks the value passed is an I<object instance>, in a similar fashion to calling
-the C<.DEFINITE> method on the value:
+Here we really only want to deal with string instances, not
+type objects. To do this, we can use the C<:D> type constraint.  This constraint
+checks that the value passed is an I<object instance>, in a similar fashion to calling
+its L<DEFINITE|/language/mop#DEFINITE> method.
+
+To warm up, let's apply C<:D> to the right hand side of our humble C<Int> example:
+
+    say  42 ~~ Int:D  # OUTPUT: «True␤»
+    say Int ~~ Int:D  # OUTPUT: «False␤»
+
+Note how only C<42> matches C<Int:D> in the above.
+
+Returning to C<limit-lines>, we can now amend its signature to catch the error
+early:
 
     sub limit-lines(Str:D $s, Int $limit) { };
     say limit-lines Str, 3;
@@ -243,10 +263,18 @@ the C<.DEFINITE> method on the value:
 This is much better than the way the program failed before, since here the
 reason for failure is clearer.
 
-It's also possible that type objects are the only ones that make
+It's also possible that I<type objects> are the only ones that make
 sense for a routine to accept. This can be done with the C<:U> type
-constraint, which checks the value passed if it is a I<type object>,
-rather than an object instance.
+constraint, which checks whether the value passed is a type object
+rather than an object instance. Here's our C<Int> example again, this
+time with C<:U> applied:
+
+    say  42 ~~ Int:U  # OUTPUT: «False␤»
+    say Int ~~ Int:U  # OUTPUT: «True␤»
+
+Now C<42> fails to match C<Int:U> while C<Int> succeeds.
+
+Here's a more practical example:
 
     sub can-turn-into(Str $string, Any:U $type) {
        return so $string.$type;
@@ -257,6 +285,12 @@ rather than an object instance.
     say can-turn-into("a string", Num);
     # OUTPUT: True True True False
 
+Calling C<can-turn-into> with an object instance as its second parameter
+will yield a constraint violation as intended:
+
+    say can-turn-into("a string", 123);
+    # OUTPUT: «Parameter '$type' of routine 'can-turn-into' must be a type object of type 'Any', not an object instance of type 'Int'...»
+
 For explicitly indicating the normal behaviour, C<:_> can be used, but this is
 unnecessary. C<:(Num:_ $)> is the same as C<:(Num $)>.