Feat: Add strcontains function and documentation (#33069)

* add strcontains function and documentation

internal/lang/funcs/descriptions.go

@@ -391,6 +391,10 @@ var DescriptionList = map[string]descriptionEntry{
 		Description:      "`startswith` takes two values: a string to check and a prefix string. The function returns true if the string begins with that exact prefix.",
 		ParamDescription: []string{"", ""},
 	},
+	"strcontains": {
+		Description:      "`strcontains` takes two values: a string to check and an expected substring. The function returns true if the string has the substring contained within it.",
+		ParamDescription: []string{"", ""},
+	},
 	"strrev": {
 		Description:      "`strrev` reverses the characters in a string. Note that the characters are treated as _Unicode characters_ (in technical terms, Unicode [grapheme cluster boundaries](https://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries) are respected).",
 		ParamDescription: []string{""},

internal/lang/funcs/string.go

@@ -103,3 +103,29 @@ var ReplaceFunc = function.New(&function.Spec{
 func Replace(str, substr, replace cty.Value) (cty.Value, error) {
 	return ReplaceFunc.Call([]cty.Value{str, substr, replace})
 }
+
+// StrContainsFunc searches a given string for another given substring,
+// if found the function returns true, otherwise returns false.
+var StrContainsFunc = function.New(&function.Spec{
+	Params: []function.Parameter{
+		{
+			Name: "str",
+			Type: cty.String,
+		},
+		{
+			Name: "substr",
+			Type: cty.String,
+		},
+	},
+	Type: function.StaticReturnType(cty.Bool),
+	Impl: func(args []cty.Value, retType cty.Type) (ret cty.Value, err error) {
+		str := args[0].AsString()
+		substr := args[1].AsString()
+
+		if strings.Contains(str, substr) {
+			return cty.True, nil
+		}
+
+		return cty.False, nil
+	},
+})

internal/lang/funcs/string_test.go

@@ -71,3 +71,66 @@ func TestReplace(t *testing.T) {
 		})
 	}
 }
+
+func TestStrContains(t *testing.T) {
+	tests := []struct {
+		String cty.Value
+		Substr cty.Value
+		Want   cty.Value
+		Err    bool
+	}{
+		{
+			cty.StringVal("hello"),
+			cty.StringVal("hel"),
+			cty.BoolVal(true),
+			false,
+		},
+		{
+			cty.StringVal("hello"),
+			cty.StringVal("lo"),
+			cty.BoolVal(true),
+			false,
+		},
+		{
+			cty.StringVal("hello1"),
+			cty.StringVal("1"),
+			cty.BoolVal(true),
+			false,
+		},
+		{
+			cty.StringVal("hello1"),
+			cty.StringVal("heo"),
+			cty.BoolVal(false),
+			false,
+		},
+		{
+			cty.StringVal("hello1"),
+			cty.NumberIntVal(1),
+			cty.UnknownVal(cty.Bool),
+			true,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("includes(%#v, %#v)", test.String, test.Substr), func(t *testing.T) {
+			got, err := StrContains(test.String, test.Substr)
+
+			if test.Err {
+				if err == nil {
+					t.Fatal("succeeded; want error")
+				}
+				return
+			} else if err != nil {
+				t.Fatalf("unexpected error: %s", err)
+			}
+
+			if !got.RawEquals(test.Want) {
+				t.Errorf("wrong result\ngot:  %#v\nwant: %#v", got, test.Want)
+			}
+		})
+	}
+}
+
+func StrContains(str, substr cty.Value) (cty.Value, error) {
+	return StrContainsFunc.Call([]cty.Value{str, substr})
+}

internal/lang/functions.go

@@ -117,6 +117,7 @@ func (s *Scope) Functions() map[string]function.Function {
 			"sort":             stdlib.SortFunc,
 			"split":            stdlib.SplitFunc,
 			"startswith":       funcs.StartsWithFunc,
+			"strcontains":      funcs.StrContainsFunc,
 			"strrev":           stdlib.ReverseFunc,
 			"substr":           stdlib.SubstrFunc,
 			"sum":              funcs.SumFunc,

internal/lang/functions_test.go

@@ -906,6 +906,17 @@ func TestFunctions(t *testing.T) {
 			},
 		},
 
+		"strcontains": {
+			{
+				`strcontains("hello", "llo")`,
+				cty.BoolVal(true),
+			},
+			{
+				`strcontains("hello", "a")`,
+				cty.BoolVal(false),
+			},
+		},
+
 		"strrev": {
 			{
 				`strrev("hello world")`,

website/data/language-nav-data.json

@@ -337,6 +337,10 @@
             "title": "<code>startswith</code>",
             "href": "/language/functions/startswith"
           },
+          {
+            "title": "<code>strcontains</code>",
+            "href": "/language/functions/strcontains"
+          },
           {
             "title": "<code>strrev</code>",
             "href": "/language/functions/strrev"

website/docs/language/functions/strcontains.mdx

@@ -0,0 +1,25 @@
+---
+page_title: strcontains - Functions - Configuration Language
+description: |-
+  The strcontains function checks whether a given string can be found within another string.
+---
+
+# `strcontains` Function
+
+`strcontains` function checks whether a substring is within another string.
+
+```hcl
+strcontains(string, substr)
+```
+
+## Examples
+
+```
+> strcontains("hello world", "wor")
+true
+```
+
+```
+> strcontains("hello world", "wod")
+false
+```

website/layouts/language.erb

@@ -418,6 +418,10 @@
                 <a href="/docs/language/functions/startswith.html">startswith</a>
               </li>
 
+              <li>
+                <a href="/docs/language/functions/strcontains.html">strcontains</a>
+              </li>
+
               <li>
                 <a href="/docs/language/functions/strrev.html">strrev</a>
               </li>