From 2a943a58a4c5bfdf4dbd272d6c81d6a98e8a7f9a Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Thu, 14 May 2020 15:44:04 -0400
Subject: [PATCH] [DOCS] EQL: Document `number` function (#56770)

Co-authored-by: Ross Wolf <31489089+rw-access@users.noreply.github.com>
---
 docs/reference/eql/functions.asciidoc | 97 +++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc
index bc33abf895d..413945849f4 100644
--- a/docs/reference/eql/functions.asciidoc
+++ b/docs/reference/eql/functions.asciidoc
@@ -19,6 +19,7 @@ experimental::[]
 * <<eql-fn-match>>
 * <<eql-fn-modulo>>
 * <<eql-fn-multiply>>
+* <<eql-fn-number>>
 * <<eql-fn-startswith>>
 * <<eql-fn-string>>
 * <<eql-fn-stringcontains>>
@@ -805,6 +806,102 @@ If using a field as the argument, this parameter supports only
 *Returns:* integer, float, or `null`
 ====
 
+[discrete]
+[[eql-fn-number]]
+=== `number`
+
+Converts a string to the corresponding integer or float.
+
+[%collapsible]
+====
+*Example*
+[source,eql]
+----
+number("1337")              // returns 1337
+number("42.5")              // returns 42.5
+number("deadbeef", 16)      // returns 3735928559
+
+// integer literals beginning with "0x" are auto-detected as hexadecimal
+number("0xdeadbeef")        // returns 3735928559
+number("0xdeadbeef", 16)    // returns 3735928559
+
+// "+" and "-" are supported
+number("+1337")             // returns 1337
+number("-1337")             // returns -1337
+
+// surrounding whitespace is ignored
+number("  1337  ")          // returns 1337
+
+// process.pid = "1337"
+number(process.pid)         // returns 1337
+
+// null handling
+number(null)                // returns null
+number(null, 16)            // returns null
+
+// strings beginning with "0x" are treated as hexadecimal (base 16),
+// even if the <base_num> is explicitly null.
+number("0xdeadbeef", null) // returns 3735928559
+
+// otherwise, strings are treated as decimal (base 10)
+// if the <base_num> is explicitly null.
+number("1337", null)        // returns 1337
+----
+
+*Syntax*
+[source,txt]
+----
+number(<string>[, <base_num>])
+----
+
+*Parameters*
+
+`<string>`::
++
+--
+(Required, string or `null`)
+String to convert to an integer or float. If this value is a string, it must be
+one of the following:
+
+* A string representation of an integer (e.g., `"42"`)
+* A string representation of a float (e.g., `"9.5"`)
+* If the `<base_num>` parameter is specified, a string containing an integer
+  literal in the base notation (e.g., `"0xDECAFBAD"` in hexadecimal or base
+  `16`)
+
+Strings that begin with `0x` are auto-detected as hexadecimal and use a default
+`<base_num>` of `16`.
+
+`-` and `+` are supported with no space between. Surrounding whitespace is
+ignored. Empty strings (`""`) are not supported.
+
+If using a field as the argument, this parameter supports only the following
+field datatypes:
+
+* <<keyword,`keyword`>>
+* <<constant-keyword,`constant_keyword`>>
+* <<text,`text`>> field with a <<keyword,`keyword`>> or
+  <<constant-keyword,`constant_keyword`>> sub-field
+
+If this argument is `null`, the function returns `null`.
+--
+
+`<base_num>`::
++
+--
+(Optional, integer or `null`)
+Radix or base used to convert the string. If the `<string>` begins with `0x`,
+this parameter defaults to `16` (hexadecimal). Otherwise, it defaults to base
+`10`.
+
+If this argument is explicitly `null`, the default value is used.
+
+Fields are not supported as arguments.
+--
+
+*Returns:* integer or float or `null`
+====
+
 [discrete]
 [[eql-fn-startswith]]
 === `startsWith`