Merge pull request #796 from stan-dev/clarify-range-indexing

clarify range indexing, fixes #638

Author: bob-carpenter

src/reference-manual/expressions.qmd

@@ -782,8 +782,10 @@ In addition to single integer indexes, as described in
 [the language indexing section](#language-indexing.section), Stan supports multiple indexing.
 Multiple indexes can be integer arrays of indexes, lower
 bounds, upper bounds, lower and upper bounds, or simply shorthand for
-all of the indexes.  A complete table of index types is given in the
-following table.
+all of the indexes.  If the upper bound is smaller than the lower bound, 
+the range is empty (unlike, e.g., in R). The upper bound and lower bound can be 
+expressions that evaluate to integer. A complete list of index types is 
+given in the following table.
 
 ##### Indexing Options Table {- #index-types-table}
 
@@ -797,9 +799,18 @@ following table.
  |  lower bound  | `a[3:]`  |     `a[3]`, ..., `a[N]`     |
  |  upper bound  | `a[:5]`  |     `a[1]`, ..., `a[5]`     |
  |     range     | `a[2:7]` |    `a[2]`, ...,  `a[7]`     |
+ |     range     | `a[7:2]` |             []              |
+ |     range     | `a[5-3:5+2]` |    `a[2]`, ...,  `a[7]`     |
  |      all      |  `a[:]`  |     `a[1]`, ..., `a[N]`     |
  |      all      |  `a[]`   |     `a[1]`, ..., `a[N]`     |
 
+The range indexing with `:` allows only increasing sequences. Indexing
+with a decereasing sequence can be made by creating an integer array in
+the following way:
+```stan
+  array[6] int ii = reverse(linspaced_int_array(6, 2, 7));
+```
+Then `a[ii]` evaluates to `a[7]`, ...,  `a[2]`.
 
 ### Multiple index semantics {-}