mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
102a0857db
New filters lists_union, lists_intersect, lists_difference and lists_symmetric_difference added. Signed-off-by: Christoph Fiehe <c.fiehe@eurodata.de> Co-authored-by: Christoph Fiehe <c.fiehe@eurodata.de>
81 lines
3.2 KiB
ReStructuredText
81 lines
3.2 KiB
ReStructuredText
..
|
|
Copyright (c) Ansible Project
|
|
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
Union, intersection and difference of lists
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Starting with Ansible Core 2.16, the builtin filters :ansplugin:`ansible.builtin.union#filter`, :ansplugin:`ansible.builtin.intersect#filter`, :ansplugin:`ansible.builtin.difference#filter` and :ansplugin:`ansible.builtin.symmetric_difference#filter` began to behave differently and do no longer preserve the item order. Items in the resulting lists are returned in arbitrary order and the order can vary between subsequent runs.
|
|
|
|
The Ansible community.general collection provides the following additional list filters:
|
|
|
|
- :ansplugin:`community.general.lists_union#filter`
|
|
- :ansplugin:`community.general.lists_intersect#filter`
|
|
- :ansplugin:`community.general.lists_difference#filter`
|
|
- :ansplugin:`community.general.lists_symmetric_difference#filter`
|
|
|
|
These filters preserve the item order, eliminate duplicates and are an extended version of the builtin ones, because they can operate on more than two lists.
|
|
|
|
.. note:: Stick to the builtin filters, when item order is not important or when you do not need the n-ary operating mode. The builtin filters are faster, because they rely mostly on sets as their underlying datastructure.
|
|
|
|
Let us use the lists below in the following examples:
|
|
|
|
.. code-block:: yaml
|
|
|
|
A: [9, 5, 7, 1, 9, 4, 10, 5, 9, 7]
|
|
B: [4, 1, 2, 8, 3, 1, 7]
|
|
C: [10, 2, 1, 9, 1]
|
|
|
|
The union of ``A`` and ``B`` can be written as:
|
|
|
|
.. code-block:: yaml+jinja
|
|
|
|
result: "{{ A | community.general.lists_union(B) }}"
|
|
|
|
This statement produces:
|
|
|
|
.. code-block:: yaml
|
|
|
|
result: [9, 5, 7, 1, 4, 10, 2, 8, 3]
|
|
|
|
If you want to calculate the intersection of ``A``, ``B`` and ``C``, you can use the following statement:
|
|
|
|
.. code-block:: yaml+jinja
|
|
|
|
result: "{{ A | community.general.lists_intersect(B, C) }}"
|
|
|
|
Alternatively, you can use a list of lists as an input of the filter
|
|
|
|
.. code-block:: yaml+jinja
|
|
|
|
result: "{{ [A, B] | community.general.lists_intersect(C) }}"
|
|
|
|
or
|
|
|
|
.. code-block:: yaml+jinja
|
|
|
|
result: "{{ [A, B, C] | community.general.lists_intersect(flatten=true) }}"
|
|
|
|
All three statements are equivalent and give:
|
|
|
|
.. code-block:: yaml
|
|
|
|
result: [1]
|
|
|
|
.. note:: Be aware that in most cases, filter calls without any argument require ``flatten=true``, otherwise the input is returned as result. The reason for this is, that the input is considered as a variable argument and is wrapped by an additional outer list. ``flatten=true`` ensures that this list is removed before the input is processed by the filter logic.
|
|
|
|
The filters ansplugin:`community.general.lists_difference#filter` or :ansplugin:`community.general.lists_symmetric_difference#filter` can be used in the same way as the filters in the examples above. They calculate the difference or the symmetric difference between two or more lists and preserve the item order.
|
|
|
|
For example, the symmetric difference of ``A``, ``B`` and ``C`` may be written as:
|
|
|
|
.. code-block:: yaml+jinja
|
|
|
|
result: "{{ A | community.general.lists_symmetric_difference(B, C) }}"
|
|
|
|
This gives:
|
|
|
|
.. code-block:: yaml
|
|
|
|
result: [5, 8, 3, 1]
|
|
|