---
# 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

DOCUMENTATION:
  name: lists_union
  short_description: Union of lists with a predictive order
  version_added: 8.4.0
  description:
    - Provide a unique list of all the elements of two or more lists.
    - The order of the items in the resulting list is preserved.
  options:
    _input:
      description: A list.
      type: list
      elements: any
      required: true
    flatten:
      description: Whether to remove one hierarchy level from the input list.
      type: boolean
      default: false
  author:
    - Christoph Fiehe (@cfiehe)

EXAMPLES: |
  - name: Return the union of list1, list2 and list3.
    ansible.builtin.debug:
      msg: "{{ list1 | community.general.lists_union(list2, list3) }}"
    vars:
      list1: [1, 2, 5, 3, 4, 10]
      list2: [1, 2, 3, 4, 5, 11, 99]
      list3: [1, 2, 3, 4, 5, 10, 99, 101]
  # => [1, 2, 5, 3, 4, 10, 11, 99, 101]
  
  - name: Return the union of list1 and list2.
    ansible.builtin.debug:
      msg: "{{ [list1, list2] | community.general.lists_union(flatten=true) }}"
    vars:
      list1: [1, 2, 5, 3, 4, 10]
      list2: [1, 2, 3, 4, 5, 11, 99]
  # => [1, 2, 5, 3, 4, 10, 11, 99]

RETURN:
  _value:
    description: A unique list of all the elements from the provided lists.
    type: list
    elements: any