Rewrite, remove inaccurate Range truncation info (#1681)

* Rewrite, remove inaccurate Range trucation info

Previously, this section stated that:

* All ranges (including non-lazy ones) will truncate the output/ omit
  undefined elements.

Rewrote the section to remove that inaccuracy and address the following:

* If the element at index [x] does not exist then the result will be an
  undefined element (when subscripting Positionals).
     * This behavior can be modified using the :v adverb.
* Using lazy Iterables as subscripts yields a different behavior. Only
  returns defined elements (most of the time; see bullets below).
    * Behind the scenes the elements of the lazy subscript are being
      reified up until the point that the element in the Positional
      is undefined.
    * Continued use of lazy Lists will begin to return undefined
      elements as new elements in the lazy List are reified.
* Include justification for these behaviors. Sometimes returning
  undefined elements is desirable.
    * DESIRABLE:     assignment. eg @A[^10] = 1..10;
    * NOT DESIRABLE: Out-of-memory due to uncontrolled indexing.

This removes some information about lack of protection against runaway
slices and reification of subscript elements in instances where the
undefined values are not being returned from the collection (eg,
instances where the same index is being used over and over again). This
seemed a little out of place in this section and probably fits better
elsewhere. Perhaps it would be appropriate in the Traps section?

SEE ALSO:
    [Issue #1679](#1679)
    https://irclog.perlgeek.de/perl6/2017-11-18#i_15466865

* Incorporate feedback on "Truncating Slices"

Incorporate feedback by zoffix. Includes:

* Replace "defined" with "exists".
* Remove unnecessarily detailed explanation of reification and Rakudo's
  slicing implementation.
* Move indexing "drift" explanation to Traps.

See <#1681>.

* Revise Lazy Lists section and add index

Added and index for the "Lazy List" section in list.pod6. Revised it a
to address these points:

* Fix error with .elems (outdated behavior?).
* Show small example of laziness and it's semantics.
* Outline the common use case of infinite lists

Also linked to this section from "Truncating Slices".

Author: jstuder-gh

doc/Language/list.pod6

@@ -194,16 +194,35 @@ value, but unlike the above options, it will break L<Scalars|/type/Scalar>.
     say (1, slip($(2, 3)), 4) eqv (1, 2, 3, 4);  # OUTPUT: «False␤»
 
 =head1 Lazy Lists
+X<|lazy (property of List)>
 
 Lists can be lazy, what means that their values are computed on demand and
 stored for later use. To create a lazy list use
 L<gather/take|/language/control#gather/take> or the
 L<sequence operator|/language/operators#infix_...>. You can also write a class that
 implements the role L<Iterable|/type/Iterable> and returns C<True> on a call to
-L<is-lazy|/routine/is-lazy>. Please note that some methods like C<elems> may cause the
-entire list to be computed what will fail if the list is also infinite.
+L<is-lazy|/routine/is-lazy>. Please note that some methods like C<elems> cannot be
+called on a lazy List and will result in a thrown L<Exception|/type/Exception>.
 
-    my @l = 1,2,4,8...Inf;
+    # This list is lazy and elements will not be available
+    # until explicitly requested.
+
+    my @l = lazy 0..5;
+    say @l.is-lazy;     # OUTPUT: «True␤»
+    say @l[];           # OUTPUT: «[...]␤»
+
+    # Once all elements have been retrieved, the List
+    # is no longer considered lazy.
+
+    eager @l;           # Forcing eager evaluation
+    say @l.is-lazy;     # OUTPUT: «False␤»
+    say @l[];           # OUTPUT: «[0 1 2 3 4 5]␤»
+
+A common use case for lazy Lists are the processing of infinite sequences of numbers,
+whose values have not been computed yet and cannot be computed in their entirety.
+Specific values in the List will only be computed when they are needed.
+
+    my @l = 1, 2, 4, 8 ... Inf;
     say @l[0..16];
     # OUTPUT: «(1 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 16384 32768 65536)␤»
 

doc/Language/subscripts.pod6

@@ -208,7 +208,7 @@ Be aware that slices are controlled by the I<type> of what is passed to
 (L<one dimension of|#Multiple dimensions>) the subscript, not its length.
 In particular the I<type> can be any of the following:
 
-=item a Range or a lazy Iterable, that L<truncates|#Truncating slices> in [ ]
+=item a lazy Iterable, that L<truncates|#Truncating slices> in [ ]
 
 =item '*' (whatever-star), that returns the full slice (as if all keys/indices were specified)
 
@@ -251,68 +251,48 @@ dimensions>) the subscript is preserved across the slice operation
 
 =head2 Truncating slices
 
-Normally, referring to nonexistent elements in a slice subscript causes the
-output list to contain undefined values (or L<whatever else|
+Referring to nonexistent elements in a slice subscript causes the
+output C<List> to contain undefined values (or L<whatever else|
 #Nonexistent elements> the collection in question chooses to return for
-nonexistent elements). However if the outer object passed to
-(L<one dimension of|#Multiple dimensions>) of a positional subscript is a
-L<Range>, it will be automatically truncated to the actual size of the
-collection:
+nonexistent elements):
 
-    my @letters = <a b c d e f>;
-    say @letters[3, 4, 5, 6, 7];  # OUTPUT: «(d e f (Any) (Any))␤»
-    say @letters[3 .. 7];         # OUTPUT: «(d e f)␤»
-
-L<From-the-end|#From the end> indices are allowed as range end-points.
-
-    =begin code :preamble<my @array;>
-    say @array[*-3 .. *];       # select the last three elements
+    =begin code
+    my  @letters = <a b c d e f>;
+    say @letters[3..7];  # OUTPUT: «(d e f (Any) (Any))␤»
     =end code
 
-A similar thing is done for lazy sequences, but it is often impossible to
-determine whether the sequence is infinite.  Just as often, the first part
-of the sequence is already known, and it would be silly to pretend we
-did not know it.  As a stopgap measure to prevent runaway generation of huge
-lists, a lazy subscript will not truncate as long as it does not have to
-lazily generate values, but once it starts generating values lazily, it
-will stop if it generates a value that points to a nonexistent index.
+This behavior, while at first glance may seem unintuitive, is desirable in
+instances when you want to assign a value at an index in which a value does
+not currently exist.
 
-    =begin code :skip-test
-    say @letters[0, 2, 4 ... *];     # Every other element of the array.
-    =end code
-
-This feature is more for protection against accidental out-of-memory
-problems than for actual use.  Since some lazy sequences cache their
-results, every time they are used in a truncation, they accumulate one
-more known element.  Things like this should probably be avoided rather
-than used for effect:
+    =begin code
+    my  @letters;
+    say @letters; # OUTPUT: «[]␤»
 
-    =begin code :skip-test
-    my @a = 2, 3 ... *;
-    say flat @letters[0, 7, @a]; # OUTPUT: «(a (Any) c d e f)␤»
-    say flat @letters[0, 7, @a]; # OUTPUT: «(a (Any) c d e f (Any))␤»
+    @letters[^10] = 'a'..'z';
+    say @letters; # OUTPUT: «[a b c d e f g h i j]␤»
     =end code
 
-The runaway protection is not perfect.  The indices are eagerly evaluated,
-with the only stop condition being truncation.  This is to provide
-mostly consistent results when there is self-reference/mutation inside
-the indices.  As such, the following will most likely hang until all
-memory has been consumed:
+If you want the resulting slice to only include existing elements, you can
+silently skip the non-existent elements using the L<#:v> adverb.
 
-    =begin code :preamble<my @letters;>
-    @letters[0 xx *];
+    =begin code
+    my  @letters = <a b c d e f>;
+    say @letters[3..7]:v;  # OUTPUT: «(d e f)␤»
     =end code
 
-So, to safely use lazy indices, they should be one-shot things which
-are guaranteed to overrun the array.  The following alternate formulation
-will produce a fully lazy result (but will not truncate):
+The behavior when indexing a collection via L<lazy|/language/list#Lazy_Lists>
+subscripts is different than when indexing with their eager counterparts.
+When accessing via a lazy subscript, the resulting slice will be truncated.
 
-    =begin code :preamble<my @letters;>
-    my $a = (0 xx *).map({ @letters[$_] }); # "a", "a", "a" ... forever
+    =begin code :preamble<my @letters = <a b c d e f>;>
+    say @letters[lazy 3..7]; # OUTPUT: «(d e f)␤»
+    say @letters[     3..*]; # OUTPUT: «(d e f)␤»
     =end code
 
-If you I<don't> want to specify your slice as a range/sequence but still want
-to silently skip nonexistent elements, you can use the L<#:v> adverb.
+This behavior exists as a precaution to prevent runaway generation of massive,
+potentially infinite C<Lists> and the out-of-memory issues that occur as a
+result.
 
 =head2 Zen slices
 

doc/Language/traps.pod6

@@ -414,6 +414,26 @@ default behavior to unsafe variant, so just by forgetting some quotes
 you are risking to introduce either a bug or maybe even a security
 hole. To stay on the safe side, refrain from using C<«»>.
 
+=head2 "Drift" when indexing with lazy Iterable
+
+If you are L<indexing with a lazy Iterable|/language/subscripts#Truncating_slices>,
+be aware that (in the Rakudo implementation) each subsequent use
+L<reifies|/language/glossary#index-entry-Reify> and caches an additional element in
+the lazy C<Iterable>, introducing undefined elements into the resulting slice. Some
+lazy C<Iterables> (such as C<List>) will cache each newly produced element while
+others (such as C<Seq>) will discard them. Being aware of how each C<Iterable> deals
+with it's lazily produced elements will help you to avoid unexpected results.
+
+    my @letters = <a b c d e f>;
+    my @i = 3..*;
+    .say for @letters[@i] xx 3;
+
+    #`( OUTPUT:
+        (d e f)
+        (d e f (Any))
+        (d e f (Any) (Any))
+    )
+
 =head1 Strings
 
 =head2 Quotes and interpolation