[DOCS] EQL: Document between function

Author: jrodewig

docs/reference/eql/functions.asciidoc

@@ -8,11 +8,129 @@ experimental::[]
 
 {es} supports the following EQL functions:
 
+* <<eql-fn-between>>
 * <<eql-fn-endswith>>
 * <<eql-fn-length>>
 * <<eql-fn-startswith>>
 * <<eql-fn-substring>>
 
+[discrete]
+[[eql-fn-between]]
+=== `between`
+
+Extracts a substring that's between a provided `left` and `right` text in a
+source string.
+
+[%collapsible]
+====
+*Example*
+[source,eql]
+----
+// file.path = "C:\\Windows\\System32\\cmd.exe"
+between(file.path, "system32\\\\", ".exe")   // returns "cmd"
+between(file.path, "workspace\\\\", ".exe")  // returns ""
+
+
+// Greedy matching defaults to false.
+between(file.path, "\\\\", "\\\\", false)  // returns "Windows"
+// Sets greedy matching to true
+between(file.path, "\\\\", "\\\\", true)  // returns "Windows\\System32"
+
+// Case sensitivity defaults to false.
+between(file.path, "system32\\\\", ".exe", false, false)  // returns "cmd"
+// Sets case sensitivity to true
+between(file.path, "system32\\\\", ".exe", false, true)   // returns ""
+between(file.path, "System32\\\\", ".exe", false, true)   // returns "cmd"
+
+// empty source string
+between("", "system32\\\\", ".exe")          // returns ""
+between("", "", "")                          // returns ""
+
+// null handling
+between(null, "system32\\\\", ".exe")                   // returns null
+between(null, null, null)                               // returns null
+between(file.path, null, ".exe")                        // returns 400 error
+between(file.path, "system32\\\\", null)                // returns 400 error
+between(file.path, "system32\\\\", ".exe", null)        // returns 400 error
+between(file.path, "system32\\\\", ".exe", false, null) // returns 400 error
+----
+
+*Syntax*
+
+[source,txt]
+----
+between(<source>, <left>, <right>[, <greedy_matching>, <case_sensitive>])
+----
+
+*Parameters*
+
+`<source>`::
++
+--
+(Required, string or `null`)
+Source string. Empty strings return an empty string (`""`), regardless of the
+`<left>` or `<right>` parameters. If `null`, the function returns `null`.
+
+If using a field as the argument, this parameter only supports the following
+field datatypes:
+
+* <<keyword,`keyword`>>
+* <<constant-keyword,`constant_keyword`>>
+* <<text,`text`>> field with a <<keyword,`keyword`>> or
+  <<constant-keyword,`constant_keyword`>> sub-field
+
+Fields containing <<array,array values>> use the first array item only.
+--
+
+`<left>`::
++
+--
+(Required, string)
+Text to the left of the substring to extract. This text should include
+whitespace.
+
+If using a field as the argument, this parameter only supports the following
+field datatypes:
+
+* <<keyword,`keyword`>>
+* <<constant-keyword,`constant_keyword`>>
+* <<text,`text`>> field with a <<keyword,`keyword`>> or
+  <<constant-keyword,`constant_keyword`>> sub-field
+
+<<array,Array values>> are not supported.
+--
+
+`<right>`::
++
+--
+(Required, string)
+Text to the right of the substring to extract. This text should include
+whitespace.
+
+If using a field as the argument, this parameter only supports the following
+field datatypes:
+
+* <<keyword,`keyword`>>
+* <<constant-keyword,`constant_keyword`>>
+* <<text,`text`>> field with a <<keyword,`keyword`>> or
+  <<constant-keyword,`constant_keyword`>> sub-field
+
+<<array,Array values>> are not supported.
+--
+
+`<greedy_matching>`::
+(Optional, boolean)
+If `true`, match the longest possible substring, similar to `.*` in regular
+expressions. If `false`, match the shortest possible substring, similar to `.*?`
+in regular expressions. Defaults to `false`.
+
+`<case_sensitive>`::
+(Optional, boolean)
+If `true`, matching is case-sensitive. Defaults to `false`.
+
+*Returns:* string or `null`
+====
+
 [discrete]
 [[eql-fn-endswith]]
 === `endsWith`