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::[] * <> * <> * <> +* <> * <> * <> * <> @@ -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 is explicitly null. +number("0xdeadbeef", null) // returns 3735928559 + +// otherwise, strings are treated as decimal (base 10) +// if the is explicitly null. +number("1337", null) // returns 1337 +---- + +*Syntax* +[source,txt] +---- +number([, ]) +---- + +*Parameters* + +``:: ++ +-- +(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 `` 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 +`` 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: + +* <> +* <> +* <> field with a <> or + <> sub-field + +If this argument is `null`, the function returns `null`. +-- + +``:: ++ +-- +(Optional, integer or `null`) +Radix or base used to convert the string. If the `` 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`