Adding subset constraints, refs #1464

doc/Language/containers.pod6

@@ -4,7 +4,11 @@
 
 =SUBTITLE A low-level explanation of Perl 6 containers
 
-This section explains the levels of indirection involved in dealing with variables and container elements. The difference types of containers used in Perl 6 are explained and the actions applicable to them like assigning, binding and flattening. More advanced topics like self-referencial data, type constraints and custom containers are discussed at the end.
+This section explains the levels of indirection involved in dealing with
+variables and container elements. The difference types of containers used in
+Perl 6 are explained and the actions applicable to them like assigning, binding
+and flattening. More advanced topics like self-referencial data, type
+constraints and custom containers are discussed at the end.
 
 =head1 What is a variable?
 
@@ -26,10 +30,10 @@ container>.
 
 =head1 Scalar containers
 
-Although objects of type L<C<Scalar>|/type/Scalar> are everywhere in Perl 6, you rarely
-see them directly as objects, because most operations
-I<decontainerize>, which means they act on the C<Scalar> container's
-contents instead of the container itself.
+Although objects of type L<C<Scalar>|/type/Scalar> are everywhere in Perl 6, you
+rarely see them directly as objects, because most operations I<decontainerize>,
+which means they act on the C<Scalar> container's contents instead of the
+container itself.
 
 In code like
 
@@ -295,8 +299,8 @@ The C<@> character can also be used as a prefix to coerce the argument to a list
     my $x = (1, 2, 3);
     .say for @$x;               # 3 iterations
 
-However, the I<decont> operator C«<>» is more appropriate to decontainerize items that aren't
-lists:
+However, the I<decont> operator C«<>» is more appropriate to decontainerize
+items that aren't lists:
 
     my $x = ^Inf .grep: *.is-prime;
     say "$_ is prime" for @$x;  # WRONG! List keeps values, thus leaking memory
@@ -325,13 +329,20 @@ Perl 6 does not prevent you from creating and using self-referential
 data; You may end up in a loop trying to dump the data; as a
 last resort, you can use Promises to L<handle|/type/Promise#method_in> timeouts.
 
-=head1 Type Constraints
+=head1 Type constraints
 
-Any container can have a type constraint in the form of
-a L<type object|/language/typesystem#Type_objects> or a L<subset|/language/typesystem#subset>.
-Both can be placed between a declarator and the variable name or after the trait L<of|/type/Variable#trait_is_dynamic>.
+Any container can have a type constraint in the form of a L<type
+object|/language/typesystem#Type_objects> or a
+L<subset|/language/typesystem#subset>. Both can be placed between a declarator
+and the variable name or after the trait L<of|/type/Variable#trait_is_dynamic>.
 The constraint is a property of the variable, not the container.
 
+    subset Three-letter of Str where .chars == 3;
+    my Three-letter $acronym = "ÞFL";
+
+In this case, the type constraint is the (compile-type defined) subset
+C<Three-letter>.
+
 Variables may have no container in them, yet still offer the ability to
 re-bind and typecheck that rebind. The reason for that is in such cases the
 binding operator L<:=|/operators#infix_:=> performs the typecheck:
@@ -340,14 +351,13 @@ binding operator L<:=|/operators#infix_:=> performs the typecheck:
     z := 100; # OK
     z := "x"; # Typecheck failure
 
-The same isn't the case when, say, binding to a L<Hash> key, as there the
-binding is handled by a method call (even though the syntax remains the same,
-using C<:=> operator).
+The same isn't the case when, say, binding to a L<Hash> key, as the binding is
+then handled by a method call (even though the syntax remains the same, using
+C<:=> operator).
 
-The default type constraint of a C<Scalar> container is L<Mu>.
-Introspection of type constraints on containers is provided by C<.VAR.of>
-method, which for C<@> and C<%> sigiled variables gives the constraint for
-values:
+The default type constraint of a C<Scalar> container is L<Mu>. Introspection of
+type constraints on containers is provided by C<.VAR.of> method, which for C<@>
+and C<%> sigiled variables gives the constraint for values:
 
     my Str $x;
     say $x.VAR.of;  # OUTPUT: «(Str)␤»