From d95db40838d9d78751f670a5f0050f66efe0fa50 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Fri, 13 Jan 2012 13:14:08 +0100 Subject: [PATCH] tweaked doc for the merge filter --- doc/filters/merge.rst | 37 +++++++++++++++++++++++++++++++++---- 1 files changed, 33 insertions(+), 4 deletions(-) diff --git a/doc/filters/merge.rst b/doc/filters/merge.rst index dfcb2f1..4348e7a 100644 --- a/doc/filters/merge.rst +++ b/doc/filters/merge.rst @@ -1,12 +1,41 @@ ``merge`` ========= -The ``merge`` filter merges an array or a hash with the given value: +The ``merge`` filter merges an array with the another array: .. code-block:: jinja - {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %} + {% set values = [1, 2] %} - {% set items = items|merge({ 'peugeot': 'car' }) %} + {% set values = values|merge(['apple', 'orange']) %} - {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car' } #} + {# values now contains [1, 2, 'apple', 'orange'] #} + +New values are added at the end of the existing ones. + +The ``merge`` filter also works on hashes: + +.. code-block:: jinja + + {% set items = { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'unknown' } %} + + {% set items = items|merge({ 'peugeot': 'car', 'renault': 'car' }) %} + + {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'renault': 'car' } #} + +For hashes, the merging process occurs on the keys: if the key does not +already exist, it is added but if the key already exists, its value is +overridden. + +.. tip:: + + If you want to ensure that some values are defined in an array (by given + default values), reverse the two elements in the call: + + .. code-block:: jinja + + {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %} + + {% set items = { 'apple': 'unknown' }|merge(items) %} + + {# items now contains { 'apple': 'fruit', 'orange': 'fruit' } #} -- 1.7.2.5