added documentation for the preverse_keys argument of the reverse filter (closes...
authorFabien Potencier <fabien.potencier@gmail.com>
Thu, 6 Jun 2013 05:56:57 +0000 (07:56 +0200)
committerFabien Potencier <fabien.potencier@gmail.com>
Thu, 6 Jun 2013 05:56:57 +0000 (07:56 +0200)
doc/filters/reverse.rst

index 54fafb4..ea0326b 100644 (file)
@@ -8,7 +8,7 @@ The ``reverse`` filter reverses a sequence, a mapping, or a string:
 
 .. code-block:: jinja
 
-    {% for use in users|reverse %}
+    {% for user in users|reverse %}
         ...
     {% endfor %}
 
@@ -16,8 +16,32 @@ The ``reverse`` filter reverses a sequence, a mapping, or a string:
 
     {# outputs 4321 #}
 
+.. tip::
+
+    For sequences and mappings, numeric keys are not preserved. To reverse
+    them as well, pass ``true`` as an argument to the ``reverse`` filter:
+
+    .. code-block:: jinja
+
+        {% for key, value in {1: "a", 2: "b"}|reverse %}
+            {{ key }}: {{ value }}
+        {%- endfor %}
+
+        {# output: 0: c    1: b    2: a #}
+
+        {% for key, value in {1: "a", 2: "b"}|reverse(true) %}
+            {{ key }}: {{ value }}
+        {%- endfor %}
+
+        {# output: 3: c    2: b    1: a #}
+
 .. note::
 
     It also works with objects implementing the `Traversable`_ interface.
 
+Arguments
+---------
+
+ * ``preserve_keys``: Preserve keys when reversing a mapping or a sequence.
+
 .. _`Traversable`: http://php.net/Traversable