Merge pull request #4070 from dumarchie/master

Document X::Cannot::Empty

doc/Type/X/Cannot/Empty.pod6

@@ -0,0 +1,58 @@
+=begin pod :kind("Type") :subkind("class") :category("exception")
+
+=TITLE class X::Cannot::Empty
+
+=SUBTITLE Error due to inappropriate usage of an empty collection
+
+    class X::Cannot::Empty is Exception { }
+
+Error, typically wrapped in a L<Failure|/type/Failure>, when inappropriately
+using an empty collection.
+
+For example, the following stack implementation fails when trying to pop a value
+from an empty stack. Sink context causes the returned C<Failure> to throw.
+
+=begin code
+class Stack {
+    my class Node {
+        has $.value;
+        has Node $.next;
+    }
+    has Node $!next;
+
+    method push($value) {
+        $!next .= new(:$value, :$!next);
+        self;
+    }
+
+    method pop() {
+        fail X::Cannot::Empty.new(:action<pop>, :what(self.^name))
+         unless $!next;
+
+        my $value = $!next.value;
+        $!next .= next;
+        $value;
+    }
+}
+
+my $stack = Stack.new.push(42);
+say $stack.pop; # OUTPUT: «42␤»
+try $stack.pop;
+say $!.message; # OUTPUT: «Cannot pop from an empty Stack␤»
+=end code
+
+=head1 Methods
+
+=head2 method action
+
+    method action()
+
+Verbal description of the inappropriate action.
+
+=head2 method what
+
+    method what()
+
+Returns the type that was the target of the action.
+
+=end pod

doc/Type/independent-routines.pod6

@@ -1203,8 +1203,9 @@ Defined as:
     multi sub pop(@a) is raw
 
 Calls method C<pop> on the C<Positional> argument. That method is supposed to
-remove and return the last element, or return a L<C<Failure>|/type/Failure> if
-the collection is empty.
+remove and return the last element, or return a L<C<Failure>|/type/Failure>
+wrapping an L<C<X::Cannot::Empty>|/type/X::Cannot::Empty> if the collection is
+empty.
 
 See the documentation of the L<C<Array> method|/routine/pop#(Array)_method_pop>
 for an example.

type-graph.txt

@@ -304,6 +304,8 @@ class Deprecation
 [Exceptions]
 # Exceptions: Misc
 class X::AdHoc                      is Exception
+class X::Cannot::Empty              is Exception
+class X::Cannot::Lazy               is Exception
 class X::Method::NotFound           is Exception
 class X::Method::InvalidQualifier   is Exception
 class X::OutOfRange                 is Exception
@@ -462,7 +464,6 @@ class X::Undeclared                                does X::Comp
 class X::Undeclared::Symbols                       does X::Comp
 class X::Value::Dynamic                            does X::Comp
 class X::Dynamic::NotFound                         is Exception
-class X::Cannot::Lazy                              is Exception
 
 [Exceptions]
 # Exceptions: Syntax