DOC: examples of label-based slicing of monotonic and non-monotonic indexes

closes pandas-dev#12522

Author: nileracecrew

doc/source/gotchas.rst

@@ -242,6 +242,44 @@ Label-based slicing conventions
 Non-monotonic indexes require exact matches
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+If the index of a ``Series`` or ``DataFrame`` is monotonically increasing or decreasing, then the bounds
+of a label-based slice can be outside the range of the index, much like slice indexing a
+normal Python ``list``. Monotonicity of an index can be tested with the ``is_monotonic_increasing`` and
+``is_monotonic_decreasing`` attributes.
+
+.. ipython:: python
+
+    df = pd.DataFrame(index=[2,3,3,4,5], columns=['data'], data=range(5))
+    df.index.is_monotonic_increasing
+
+    # no rows 0 or 1, but still returns rows 2, 3 (both of them), and 4:
+    df.loc[0:4, :]
+
+    # slice is are outside the index, so empty DataFrame is returned
+    df.loc[13:15, :]
+
+On the other hand, if the index is not monotonic, then both slice bounds must be
+*unique* members of the index.
+
+.. ipython:: python
+
+    df = pd.DataFrame(index=[2,3,1,4,3,5], columns=['data'], data=range(6))
+    df.index.is_monotonic_increasing
+
+    # OK because 2 and 4 are in the index
+    df.loc[2:4, :]
+
+.. code-block:: python
+
+    # 0 is not in the index
+    In [9]: df.loc[0:4, :]
+    KeyError: 0
+
+    # 3 is not a unique label
+    In [11]: df.loc[2:3, :]
+    KeyError: 'Cannot get right slice bound for non-unique label: 3'
+
+
 Endpoints are inclusive
 ~~~~~~~~~~~~~~~~~~~~~~~