lang: add setsubtract function (hashicorp#23424)

* add setdifference and setsubtract functions and docs
* remove setdifference as it is not implemented correct in underlying lib

* Update setintersection.html.md
* Update setproduct.html.md
* Update setunion.html.md

Author: jamesgoodhouse

lang/functions.go

@@ -100,6 +100,7 @@ func (s *Scope) Functions() map[string]function.Function {
 			"rsadecrypt":       funcs.RsaDecryptFunc,
 			"setintersection":  stdlib.SetIntersectionFunc,
 			"setproduct":       funcs.SetProductFunc,
+			"setsubtract":      stdlib.SetSubtractFunc,
 			"setunion":         stdlib.SetUnionFunc,
 			"sha1":             funcs.Sha1Func,
 			"sha256":           funcs.Sha256Func,

lang/functions_test.go

@@ -687,6 +687,15 @@ func TestFunctions(t *testing.T) {
 			},
 		},
 
+		"setsubtract": {
+			{
+				`setsubtract(["a", "b", "c"], ["a", "c"])`,
+				cty.SetVal([]cty.Value{
+					cty.StringVal("b"),
+				}),
+			},
+		},
+
 		"setunion": {
 			{
 				`setunion(["a", "b"], ["b", "c"], ["d"])`,

website/docs/configuration/functions/setintersection.html.md

@@ -40,5 +40,6 @@ the ordering of the given elements is not preserved.
   a given element value.
 * [`setproduct`](./setproduct.html) computes the _Cartesian product_ of multiple
   sets.
+* [`setsubtract`](./setsubtract.html) computes the _relative complement_ of two sets
 * [`setunion`](./setunion.html) computes the _union_ of
   multiple sets.

website/docs/configuration/functions/setproduct.html.md

@@ -224,5 +224,6 @@ elements in the input variables.
   object types are defined explicitly.
 * [`setintersection`](./setintersection.html) computes the _intersection_ of
   multiple sets.
+* [`setsubtract`](./setsubtract.html) computes the _relative complement_ of two sets
 * [`setunion`](./setunion.html) computes the _union_ of multiple
   sets.

website/docs/configuration/functions/setsubtract.html.md

@@ -0,0 +1,49 @@
+---
+layout: "functions"
+page_title: "setsubtract - Functions - Configuration Language"
+sidebar_current: "docs-funcs-collection-setsubtract"
+description: |-
+  The setsubtract function returns a new set containing the elements
+  from the first set that are not present in the second set
+---
+
+# `setsubtract` Function
+
+-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
+earlier, see
+[0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
+
+The `setsubtract` function returns a new set containing the elements from the first set that are not present in the second set. In other words, it computes the
+[relative complement](https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement) of the first set in the second set.
+
+```hcl
+setsubtract(a, b)
+```
+
+## Examples
+
+```
+> setsubtract(["a", "b", "c"], ["a", "c"])
+[
+  "b",
+]
+```
+
+### Set Difference (Symmetric Difference)
+
+```
+> setunion(setsubtract(["a", "b", "c"], ["a", "c", "d"]), setsubtract(["a", "c", "d"], ["a", "b", "c"]))
+[
+  "b",
+  "d",
+]
+```
+
+
+## Related Functions
+
+* [`setintersection`](./setintersection.html) computes the _intersection_ of multiple sets
+* [`setproduct`](./setproduct.html) computes the _Cartesian product_ of multiple
+  sets.
+* [`setunion`](./setunion.html) computes the _union_ of
+  multiple sets.

website/docs/configuration/functions/setunion.html.md

@@ -45,3 +45,4 @@ the ordering of the given elements is not preserved.
   multiple sets.
 * [`setproduct`](./setproduct.html) computes the _Cartesian product_ of multiple
   sets.
+* [`setsubtract`](./setsubtract.html) computes the _relative complement_ of two sets

website/layouts/functions.erb

@@ -222,6 +222,10 @@
                 <a href="/docs/configuration/functions/setproduct.html">setproduct</a>
               </li>
 
+              <li>
+                <a href="/docs/configuration/functions/setsubtract.html">setsubtract</a>
+              </li>
+
               <li>
                 <a href="/docs/configuration/functions/setunion.html">setunion</a>
               </li>