initial Range docs

Author: moritz

lib/Range.pod

@@ -0,0 +1,60 @@
+=begin pod
+
+=head1 Range
+
+    class Range is Iterable does Positional { ... }
+
+Ranges serve two main purposes: to generate lists of consecutive
+numbers or strings, and to act as a matcher to check if a number
+or string is within a certain range.
+
+Ranges are constructed using one of the four possible range operators,
+which consist of two dots, and optionally a caret which indicates that
+the endpoint marked with it is excluded from the range.
+
+    1 .. 5
+    1^.. 5  # start point excluded
+    1 ..^5  # end point excluded
+    1^..^5  # start and end point excluded
+
+The caret is also a prefix operator for constructing numeric ranges
+starting from zero:
+
+    ^$x     # same as 0 ..^ $x.Numeric
+
+Iterating a range (or calling the C<list> method) uses the same semantics as
+the C<++> prefix and postfix operators, ie it calls the C<succ> method on
+the start point, and then generated elements).
+
+Ranges always go from small to larger elements; if the start point is bigger
+than the end point, the range is considered empty.
+
+=head2 Methods
+
+=head3 min
+
+Returns the start point of the range
+
+=head3 excludes_min
+
+Returns C<True> if the start point is excluded from the range, and C<False>
+otherwise.
+
+=head3 max
+
+Returns the end point of the range
+
+=head3 excludes_max
+
+Returns C<True> if the end point is excluded from the range, and C<False>
+otherwise.
+
+=head3 list
+
+Generates the list of elements that the range represents.
+
+=head3 flat
+
+Generates the list of elements that the range represents.
+
+=end pod