Conversion functions
The following list contains the functions that you can use to convert numbers to strings and strings to numbers.
For information about using string and numeric fields in functions, and nesting functions, see Evaluation functions.
printf("format",arguments)
Description
The printf
function builds a string value, based on the a string format and the arguments that you specify.
- You can specify zero or more arguments. The arguments can be string values, numbers, computations, or fields.
The SPL printf
function is similar to the C sprintf()
function and similar functions in other languages such as Python, Perl, and Ruby.
Usage
You can use this function with the eval
, fieldformat
, and where
commands, and as part of eval expressions.
- format
- Description: The
format
is a character string that can include one or more format conversion specifiers. Each conversion specifier can include optional components such as flag characters, width specifications, and precision specifications. Theformat
must be enclosed in quotation marks. - Syntax: "(%[flags][width][.precision]<conversion_specifier>)..."
- arguments
- Description: The
arguments
are optional and can include the width, precision, and the value to format. The value can be a string, number, or field name. - Syntax: [width][.precision][value]
Supported conversion specifiers
The following table describes the supported conversion specifiers.
Conversion specifier | Alias | Description | Examples |
---|---|---|---|
%a or %A | Floating point number in hexadecimal format | This example returns the value of pi to 3 decimal points, in hexadecimal format.
| |
%c | Single Unicode code point | This example returns the unicode code point for 65 and the first letter of the string "Foo".printf("%c,%c",65,"Foo") which returns A,F
| |
%d | %i | Signed decimal integer | This example returns the positive or negative integer values, including any signs specified with those values. printf("%d,%i,%d",-2,+4,30) which returns -2,4,30
|
%e or %E | Floating point number, exponential format | This example returns the number 5139 in exponential format with 2 decimal points. printf("%.2e",5139) which returns 5.14e+03
| |
%f or %F | Floating point number | This example returns the value of pi to 2 decimal points.
| |
%g or %G | Floating point number. This specifier uses either %e or %f depending on the range of the numbers being formatted. | This example returns the value of pi to 2 decimal points (using the %f specifier) and the number 123 in exponential format with 2 decimal points (using %e specifier).
| |
%o | Unsigned octal number | This example returns the base-8 number for 255.
| |
%s | %z | String | This example returns the concatenated string values of "foo" and "bar".
|
%u | Unsigned, or non-negative, decimal integer | This example returns the integer value of the number in the argument. printf("%u",99) which returns 99
| |
%x or %X | %p | Unsigned hexadecimal number (lowercase or uppercase) | This example returns the hexadecimal values that are equivalent to the numbers in the arguments. This example shows both upper and lowercase results when using this specifier.
|
%% | Percent sign | This example returns the string value with a percent sign.
|
Flag characters
The following table describes the supported flag characters.
Flag characters | Description | Examples |
---|---|---|
single quote or apostrophe ( ' ) | Adds commas as the thousands separator. | printf("%'d",12345) which returns 12,345
|
dash or minus ( - ) | Left justify. If this flag is not specified, the result keeps its default justification. The printf function supports right justification of results only when it formats that way by default.
|
printf("%-4d",1) which returns 1
which is left justified in the output. |
zero ( 0 ) | Zero pad | This example returns the value in the argument with leading zeros such that the number has 4 digits.
|
plus ( + ) | Always include the sign ( + or - ). If this flag is not specified, the conversion displays a sign only for negative values. | printf("%+4d",1) which returns +1
|
<space> | Reserve space for the sign. If the first character of a signed conversion is not a sign or if a signed conversion results in no characters, a <space> is added as a prefixed to the result. If both the <space> and + flags are specified, the <space> flag is ignored. | printf("% -4d",1) which returns 1
|
hash, number, or pound ( # ) | Use an alternate form. For the %o conversion specifier, the # flag increases the precision to force the first digit of the result to be zero. For %x or %X conversion specifiers, a non-zero result has 0x (or 0X) prefixed to it. For %a, %A, %e, %E, %f, %F, %%g , and G conversion specifiers, the result always contains a radix character, even if no digits follow the radix character. Without this flag, a radix character appears in the result of these conversions only if a digit follows it. For %g and %G conversion specifiers, trailing zeros are not removed from the result as they normally are. For other conversion specifiers, the behavior is undefined. | printf("%#x", 1) which returns 0x1
|
Specifying field width
You can use an asterisk ( * ) with the printf
function to return the field width or precision from an argument.
Examples
The following example returns the positive or negative integer values, including any signs specified with those values.
printf("%*d", 5, 123)
which returns123
The following example returns the floating point number with 1 decimal point.
printf("%.*f", 1, 1.23)
which returns1.2
The following example returns the value of pi() in exponential format with 2 decimal points.
printf("%*.*e", 9, 2, pi())
which returns3.14e+00
The field width can be expressed using a number or an argument denoted with an asterisk ( * ) character.
Field width specifier | Description | Examples |
---|---|---|
number | The minimum number of characters to print. If the value to print is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger. | |
* (asterisk) | The width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. |
Specifying precision
Precision | Description |
---|---|
%d, %i, %o, %u, %x or %X | Precision specifies the minimum number of digits to be return. If the value to be return is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is returned for the value 0. |
%a or %A, %e or %E, %f or %F | This is the number of digits to be returned after the decimal point. The default is 6 . |
%g or %G | This is the maximum number of significant digits to be returned. |
%s | This is the maximum number of characters to be returned. By default all characters are printed until the ending null character is encountered. |
Specifying the period without a precision value | If the period is specified without an explicit value for precision, 0 is assumed. |
Specifying an asterisk for the precision value, for example .*
|
The precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted. |
Unsupported conversion specifiers
There are a few conversion specifiers from the C sprintf()
function that are not supported, including:
- %C, however %c is supported
- %n
- %S, however %s is supported
- %<num>$ specifier for picking which argument to use
Basic examples
This example creates a new field called new_field
and creates string values based on the values in field_one
and field_two
. The values are formatted with 4 digits before the decimal and 4 digits after the decimal. The -
specifies to left justify the string values. The 30
specifies the width of the field.
...| eval new_field=printf("%04.4f %-30s",field_one,field_two)
tonumber(NUMSTR,BASE)
Description
This function converts the input string NUMSTR to a number. NUMSTR can be a field name or a value.
Usage
You can use this function with the eval
, fieldformat
, and where
commands, and as part of eval expressions.
BASE is optional and used to define the base of the number in NUMSTR. BASE can be 2 to 36. The default is 10 to correspond to the decimal system.
If the tonumber
function cannot parse a field value to a number, for example if the value contains a leading and trailing space, the function returns NULL. Use the trim
function to remove leading or trailing spaces.
If the tonumber
function cannot parse a literal string to a number, it returns an error.
Basic examples
The following example converts the string values for the store_sales field to numbers.
... | eval n=tonumber(store_sales)
The following example takes the hexadecimal number and uses a BASE of 16 to return the number "164".
... | eval n=tonumber("0A4",16)
The following example trims any leading or trailing spaces from the values in the celsius
field before converting it to a number.
... | eval temperature=tonumber(trim(celsius))
tostring(X,Y)
Description
This function converts the input value to a string. If the input value is a number, it reformats it as a string. If the input value is a Boolean value, it returns the corresponding string value, "True" or "False".
Usage
You can use this function with the eval
, fieldformat
, and where
commands, and as part of eval expressions.
This function requires at least one argument X.
When used with the eval
command, the values might not sort as expected because the values are converted to ASCII. Use the fieldformat
command with the tostring
function to format the displayed values. The underlying values are not changed with the fieldformat
command.
If X is a number, the second argument Y is optional and can be "hex"
, "commas"
, or "duration"
.
Examples | Description |
---|---|
tostring(X,"hex")
|
Converts X to hexadecimal. |
tostring(X,"commas")
|
Formats X with commas. If the number includes decimals, the function rounds to nearest two decimal places. |
tostring(X,"duration")
|
Converts seconds X to the readable time format HH:MM:SS. |
Basic examples
The following example returns "True 0xF 12,345.68".
... | eval n=tostring(1==1) + " " + tostring(15, "hex") + " " + tostring(12345.6789, "commas")
The following example returns foo=615
and foo2=00:10:15
. The 615 seconds is converted into minutes and seconds.
... | eval foo=615 | eval foo2 = tostring(foo, "duration")
The following example formats the column totalSales to display values with a currency symbol and commas. You must use a period between the currency value and the tostring
function.
... | fieldformat totalSales="$".tostring(totalSales,"commas")
See also
Comparison and Conditional functions | Cryptographic functions |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12
Feedback submitted, thanks!