diff --git a/docs/contrib/sequences.rst b/docs/contrib/sequences.rst index 58e7ec0..1c675e0 100644 --- a/docs/contrib/sequences.rst +++ b/docs/contrib/sequences.rst @@ -4,40 +4,40 @@ Lazy sequences .. versionadded:: 0.12.0 -The Sequences module contains few macros for declaring sequences that are -evaluated only as much as the client code requests elements. Compared to -generators, they allow accessing same the element multiple times. Since they -cache calculated values, they aren't suited for infinite sequences. However, -the implementation allows for recursive definition of sequences, without -resulting recursive computation. +The sequences module contains a few macros for declaring sequences that are +evaluated only as much as the client code requires. Unlike generators, they +allow accessing the same element multiple times. They cache calculated values, +and the implementation allows for recursive definition of sequences without +resulting in recursive computation. -To use these macros, you need to require them and import other types like: +To use these macros, you need to require them and import some other names like +so: .. code-block:: hy (require [hy.contrib.sequences [defseq seq]]) (import [hy.contrib.sequences [Sequence end-sequence]]) -The simplest sequence can be defined as ``(seq [n] n)``. This defines a -sequence that starts as ``[0 1 2 3 ...]`` and continues forever. In order to -define a finite sequence, ``end-sequence`` needs to be called to signal the end -of the sequence: +The simplest sequence can be defined as ``(seq [n] n)``. This defines a sequence +that starts as ``[0 1 2 3 ...]`` and continues forever. In order to define a +finite sequence, you need to call ``end-sequence`` to signal the end of the +sequence: .. code-block:: hy (seq [n] "sequence of 5 integers" (cond [(< n 5) n] - [true (end-sequence)])) + [True (end-sequence)])) -This creates following sequence: ``[0 1 2 3 4]``. For such a sequence, ``len`` -returns the amount of items in the sequence and negative indexing is supported. -Because both of thse require evaluating the whole sequence, calling such a -function would take forever (or at least until available memory has been -exhausted). +This creates the following sequence: ``[0 1 2 3 4]``. For such a sequence, +``len`` returns the amount of items in the sequence and negative indexing is +supported. Because both of these require evaluating the whole sequence, calling +one on an infinite sequence would take forever (or at least until available +memory has been exhausted). -Sequences can be defined recursively. The canonical example of fibonacci numbers -is defined as: +Sequences can be defined recursively. For example, the Fibonacci sequence could +be defined as: .. code-block:: hy @@ -45,10 +45,10 @@ is defined as: "infinite sequence of fibonacci numbers" (cond [(= n 0) 0] [(= n 1) 1] - [true (+ (get fibonacci (- n 1)) + [True (+ (get fibonacci (- n 1)) (get fibonacci (- n 2)))])) -This results the sequence of ``[0 1 1 2 3 5 8 13 21 34 ...]``. +This results in the sequence ``[0 1 1 2 3 5 8 13 21 34 ...]``. .. _seq: @@ -75,6 +75,7 @@ end-sequence Usage: ``(seq [n] (if (< n 5) n (end-sequence)))`` -Signals end of a sequence when iterator reaches certain point of sequence. -Internally this is done by raising ``IndexError``, catching that in iterator -and raising ``StopIteration``. +Signals the end of a sequence when an iterator reaches the given +point of the sequence. Internally, this is done by raising +``IndexError``, catching that in the iterator, and raising +``StopIteration``.