Merge pull request #102 from SethMMorton/document-units

This pull request adds an example of how to sort based on units, and also exposes
a new function that helps building custom functions easier.

2 files changed, 58 insertions, 1 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 5e7a482..8052606 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -91,7 +91,14 @@ Help With Creating Function Keys
 If you need to create a complicated *key* argument to (for example)
 :func:`natsorted` that is actually multiple functions called one after the other,
 the following function can help you easily perform this action. It is
-used internally to :mod:`natsort`, and has been exposed publically for
+used internally to :mod:`natsort`, and has been exposed publicly for
 the convenience of the user.
 
 .. autofunction:: chain_functions
+
+If you need to be able to search your input for numbers using the same definition
+as :mod:`natsort`, you can do so using the following function. Given your chosen
+algorithm (selected using the :class:`~natsort.ns` enum), the corresponding regular
+expression to locate numbers will be returned.
+
+.. autofunction:: numeric_regex_chooser
diff --git a/docs/examples.rst b/docs/examples.rst
index e44aa1c..04ca632 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -245,6 +245,56 @@ sort key so that:
     >>> natsorted(b, key=attrgetter('bar'))
     [Foo('num2'), Foo('num3'), Foo('num5')]
 
+.. _unit_sorting:
+
+Accounting for Units When Sorting
++++++++++++++++++++++++++++++++++
+
+:mod:`natsort` does not come with any pre-built mechanism to sort units,
+but you can write your own `key` to do this. Below, I will demonstrate sorting
+imperial lengths (e.g. feet an inches), but of course you can extend this to any
+set of units you need. This example is based on code from
+`this issue <https://github.com/SethMMorton/natsort/issues/100#issuecomment-530659310>`_,
+and uses the function :func:`natsort.numeric_regex_chooser` to build a regular
+expression that will parse numbers in the same manner as :mod:`natsort` itself.
+
+.. code-block:: pycon
+
+    >>> import re
+    >>> import natsort
+    >>>
+    >>> # Define how each unit will be transformed
+    >>> conversion_mapping = {
+    ...         "in": 1,
+    ...         "inch": 1,
+    ...         "inches": 1,
+    ...         "ft": 12,
+    ...         "feet": 12,
+    ...         "foot": 12,
+    ... }
+    >>>
+    >>> # This regular expression searches for numbers and units
+    >>> all_units = "|".join(conversion_mapping.keys())
+    >>> float_re = natsort.numeric_regex_chooser(natsort.FLOAT | natsort.SIGNED)
+    >>> unit_finder = re.compile(r"({})\s*({})".format(float_re, all_units), re.IGNORECASE)
+    >>>
+    >>> def unit_replacer(matchobj):
+    ...     """
+    ...     Given a regex match object, return a replacement string where units are modified
+    ...     """
+    ...     number = matchobj.group(1)
+    ...     unit = matchobj.group(2)
+    ...     new_number = float(number) * conversion_mapping[unit]
+    ...     return "{} in".format(new_number)
+    ...
+    >>> # Demo time!
+    >>> data = ['1 ft', '5 in', '10 ft', '2 in']
+    >>> [unit_finder.sub(unit_replacer, x) for x in data]
+    ['12.0 in', '5.0 in', '120.0 in', '2.0 in']
+    >>>
+    >>> natsort.natsorted(data, key=lambda x: unit_finder.sub(unit_replacer, x))
+    ['2 in', '5 in', '1 ft', '10 ft']
+
 Generating a Natsort Key
 ------------------------