set theory filter docs (#77801)

Co-authored-by: flowerysong <junk+github@flowerysong.com>

lib/ansible/plugins/filter/difference.yml

@@ -0,0 +1,35 @@
+DOCUMENTATION:
+  name: difference
+  author: Brian Coca (@bcoca)
+  version_added: "1.4"
+  short_description: the difference of one list from another
+  description:
+    - Provide a unique list of all the elements of the first list that do not appear in the second one.
+  options:
+    _input:
+      description: A list
+      type: list
+      required: true
+    _second_list:
+      description: A list
+      type: list
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.intersect
+    - plugin_type: filter
+      plugin: ansible.builtin.symmetric_difference
+    - plugin_type: filter
+      plugin: ansible.builtin.union
+    - plugin_type: filter
+      plugin: ansible.builtin.unique
+EXAMPLES: |
+  # return the elements of list1 not in list2
+  # list1: [1, 2, 5, 1, 3, 4, 10]
+  # list2: [1, 2, 3, 4, 5, 11, 99]
+  {{ list1 | difference(list2) }}
+  # => [10]
+RETURN:
+  _value:
+    description: A unique list of the elements from the first list that do not appear on the 2nd
+    type: list

lib/ansible/plugins/filter/intersect.yml

@@ -0,0 +1,35 @@
+DOCUMENTATION:
+  name: intersect
+  author: Brian Coca (@bcoca)
+  version_added: "1.4"
+  short_description: intersection of lists
+  description:
+    - Provide a list with the common elements from other lists.
+  options:
+    _input:
+      description: A list
+      type: list
+      required: true
+    _second_list:
+      description: A list
+      type: list
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.difference
+    - plugin_type: filter
+      plugin: ansible.builtin.symmetric_difference
+    - plugin_type: filter
+      plugin: ansible.builtin.unique
+    - plugin_type: filter
+      plugin: ansible.builtin.union
+EXAMPLES: |
+  # return only the common elements of list1 and list2
+  # list1: [1, 2, 5, 3, 4, 10]
+  # list2: [1, 2, 3, 4, 5, 11, 99]
+  {{ list1 | intersect(list2) }}
+  # => [1, 2, 5, 3, 4]
+RETURN:
+  _value:
+    description: A list with unique elements common to both lists, also known as a set
+    type: list

lib/ansible/plugins/filter/symmetric_difference.yml

@@ -0,0 +1,35 @@
+DOCUMENTATION:
+  name: symmetric_difference
+  author: Brian Coca (@bcoca)
+  version_added: "1.4"
+  short_description: different items from 2 lists
+  description:
+    - Provide a unique list of all the elements unique to each list.
+  options:
+    _input:
+      description: A list
+      type: list
+      required: true
+    _second_list:
+      description: A list
+      type: list
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.difference
+    - plugin_type: filter
+      plugin: ansible.builtin.intersect
+    - plugin_type: filter
+      plugin: ansible.builtin.union
+    - plugin_type: filter
+      plugin: ansible.builtin.unique
+EXAMPLES: |
+  # return the elements of list1 not in list2 and the elements in list2 not in list1
+  # list1: [1, 2, 5, 1, 3, 4, 10]
+  # list2: [1, 2, 3, 4, 5, 11, 99]
+  {{ list1 | symmetric_difference(list2) }}
+  # => [10, 11, 99]
+RETURN:
+  _value:
+    description: A unique list of the elements from 2 lists that are unique to each one
+    type: list

lib/ansible/plugins/filter/union.yml

@@ -0,0 +1,35 @@
+DOCUMENTATION:
+  name: union
+  author: Brian Coca (@bcoca)
+  version_added: "1.4"
+  short_description: union of lists
+  description:
+    - Provide a unique list of all the elements of 2 lists.
+  options:
+    _input:
+      description: A list
+      type: list
+      required: true
+    _second_list:
+      description: A list
+      type: list
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.difference
+    - plugin_type: filter
+      plugin: ansible.builtin.intersect
+    - plugin_type: filter
+      plugin: ansible.builtin.symmetric_difference
+    - plugin_type: filter
+      plugin: ansible.builtin.unique
+EXAMPLES: |
+  # return the unique elements of list1 added to list2
+  # list1: [1, 2, 5, 1, 3, 4, 10]
+  # list2: [1, 2, 3, 4, 5, 11, 99]
+  {{ list1 | union(list2) }}
+  # => [1, 2, 5, 1, 3, 4, 10, 11, 99]
+RETURN:
+  _value:
+    description: A unique list of all the elements from both lists
+    type: list

lib/ansible/plugins/filter/unique.yml

@@ -0,0 +1,30 @@
+DOCUMENTATION:
+  name: unique
+  author: Brian Coca (@bcoca)
+  version_added: "1.4"
+  short_description: set of unique items of a list
+  description:
+    - Creates a list of unique elements (a set) from the provided input list.
+  options:
+    _input:
+      description: A list
+      type: list
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.difference
+    - plugin_type: filter
+      plugin: ansible.builtin.intersect
+    - plugin_type: filter
+      plugin: ansible.builtin.symmetric_difference
+    - plugin_type: filter
+      plugin: ansible.builtin.union
+EXAMPLES: |
+  # return only the unique elements of list1
+  # list1: [1, 2, 5, 1, 3, 4, 10]
+  {{ list1 | unique }}
+  # => [1, 2, 5, 3, 4, 10]
+RETURN:
+  _value:
+    description: A list with unique elements, also known as a set
+    type: list