String

String module provides Juttle functions to manipulate strings and convert from/to other data types to String. Juttle strings are subject to string coercion and interpolation rules, also described here.

String Interpolation

In Juttle, your string literals can include placeholders that contain expressions that generate variable values. Values that aren't originally strings are automatically converted.

Placeholders have this format:

${expression}

Example: simple string interpolation

const total = 3;
emit -limit total
| put count = count()
| put message = "finished ${count} of ${total}"

Because the values of count and total are numbers, Jut automatically converts them to strings.

Placeholders can include more complex expressions, too.

Example: complex string interpolation

const total = 3;
emit -limit total
| put count = count()
| put message = "finished ${Math.round((count / total) * 100)}%"

String Coercion

These are the basic string coercion rules:

Values for Juttle options are not subject to string coercion.

That is, if you specify an option like -option myvalue then myvalue must be defined somewhere in your program as a constant or a variable. If the value of the option should be literally "myvalue", use -option 'myvalue'.
Arguments for reducer calls are not subject to string coercion

For example, if your program includes reduce count(host) then host must be defined elsewhere in your program. If you want to reduce by counting the instances of each value of your data's host field, use reduce count('host').

toString Conversion

While not part of the String module, these functions are listed here for convenience.

Date.toString()

Duration.toString()

Number.toString()

Boolean.toString()

Convert a value of type Boolean to type String.

Boolean.toString(boolean)

Example: print a true/false statement

emit -limit 1 | put a=Math.random(), b=Math.random()
| put c = "a > b: " + Boolean.toString(a > b)

RegExp.toString()

Convert a value of type RegExp to type String.

RegExp.toString(regular_expression)

This function replaces the first string it finds. To replace globally, append the /g modifier to your regular expression, like this:

/hi/g

String.charAt

Given a string and an index, returns the character at that index in the string. Returns an empty string if the index is out of bounds.

String.charAt(string, index)

Parameter	Description	Required?
`string`	The string to return a character from	Yes
`index`	The index in `string`of the character to return	Yes

Example

emit -points [{hello: 'hello'}]
| put message = String.charAt(hello, 1)

String.charCodeAt

Given a string and an index, returns the character code at that index in the string. Returns null if the index is out of bounds.

String.charCodeAt(string, index)

Parameter	Description	Required?
`string`	The string to return a character from	Yes
`index`	The index in `string`of the character code to return	Yes

Example

emit -points [{hello: 'hello'}]
| put message = String.charCodeAt(hello, 1)

String.concat

Combine two or more strings and return a new string.

String.concat(string1, string2 [, string3 [, ..] ])

Tip: There are simpler ways to combine strings; see String interpolation. Strings can also be concatenated via the + operator; in the example below, String.concat could also be replaced by host + "." + domain.

Example

emit -limit 1 
| put host = "jupiter", domain = "milkyway.org" 
| put fqdn = String.concat(host, ".", domain) 
| view text

String.fromCharCode

Given a character code, returns a one-character string consisting of the character for that code.

String.fromCharCode(code)

Parameter	Description	Required?
`code`	The code of the character to be stringified	Yes

Example

emit
| put message = String.fromCharCode(123)

String.indexOf

Perform a substring search and return the index of the first match, or -1 if there is no match. See also String.search for regex-based searches.

String.indexOf(string, searchstring)

Parameter	Description	Required?
`string`	The string in which to perform the search	Yes
`searchstring`	The string to search for	Yes

Example: Find the first instance of "voodoo"

emit -limit 1 
| put name="The voodoo that you voodoo"
| put newname=String.indexOf(name, "voodoo")
| view text

String.length

Return the length of a string.

String.length(string)

Example

emit -limit 1 
| put len = String.length("jupiter.milkway.org") 
| view text

String.match

Given a string and a regular expression, returns an array containing the matching substring and any captured substrings if the string matches the regular expression. Returns null if the string does not match the regular expression.

String.match(string, regexp)

Parameter	Description	Required?
`string`	The string to check for a match	Yes
`regexp`	The regular expression to check `string`with	Yes

Example

emit -points [{result: String.match("abcd", /bc/)}]

String.replace

Replace all or part of a string with another string.

String.replace("original_string", "string_to_replace", "replacement_string")

Parameter	Description	Required?
`original_string`	The original string to manipulate	Yes
`string_to_replace`	The segment of the string to replace; this can be a regular expression	Yes
`replacement_string`	The new string	Yes

Example: Transform "hayneedlehay" into "hayFOUNDhay"

emit -from :0: -limit 1 
| put result = String.replace("hayneedlehay", "needle", "FOUND")
| view text

Example: Transform "hayneeeeeeedlehay" (or a similar string with one or more "e" characters) into "hayFOUNDhay"

emit -from :0: -limit 1 
| put result = String.replace("hayneeeeeeedlehay", /ne+dle/, "FOUND") 
| view text

String.search

Search for a match between a regular expression and a string. See also String.indexOf for simple substring searches.

String.search(string, regexp)

If successful, this function returns the index of the first match of the regular expression inside the string. Otherwise, it returns -1. Regular expression syntax follows common conventions; see for example the JavaScript documentation.

Example

function host_type(host) {
    if (String.search(host, /^(web|db)?server$/) >= 0) {
    return "server";
    }
    if (String.search(host, /switch/) >= 0) {
    return "switch";
    }
    return "unknown";
}
emit -limit 1 
| put a = host_type("webserver"), b = host_type("dbserver"), c=host_type("switch") 
| view text

String.slice

Extract a section of a string and return it as a new string. See also String.substr for length-based extraction.

String.slice(string, beginSlice[, endSlice])

Parameter	Description	Required?
`string`	The string from which to extract the slice	Yes
`beginSlice`	The zero-based index at which to begin extraction If this value is negative, it is treated as `(sourceLength+beginSlice)`` where sourceLength is the length of the string. For example, if beginSlice is -3 it is treated as sourceLength-3, or three characters before the end of the string.	Yes
`endSlice`	The zero-based index at which to end extraction If negative, it is treated as (sourceLength-endSlice) where sourceLength is the length of the string.	No; defaults to the end of the string

Example

const name = "host-a341-4a29";
emit -limit 1 
| put id = String.slice(name, -9) 
| view text

String.split

Split a string into an array of strings by separating the string into substrings.

String.split(string, separator)

Parameter	Description	Required?
`string`	The string to split. String is converted to an array of characters.	Yes
`separator`	One or more characters to use for separating the string. The separator is treated as if it is an empty string.	Yes

Example

emit -limit 1 
| put host = "alphaserver-22" 
| put parts = String.split(host, '-') 
| put id = parts[0] 
| view text

String.substr

Extract a portion of a string beginning at the start location through the specified length number of characters. Similar to String.slice, except the optional parameter is length rather than ending offset.

String.substr(string, start[, length])

Parameter	Description	Required?
`string`	The string from which to extract the substring	Yes
`start`	The character index at which to begin extraction. The `start`location of zero (0) maps to the first character of the string; the index of the last character is `String.length - 1`. If `start`is positive, it is used as character index counting from the start of the string. If `start`equals or exceeds the length of the string, an empty string will be returned. If `start`value is negative, it is used as character index counting from the end of the string. If the absolute value of a negative `start`exceeds the length of the string, zero will be used as the starting index.	Yes
`length`	The number of characters to extract. If `length`extends beyond the end of the string, fewer characters than `length`will be returned. If `length`is zero or negative, an empty string will be returned.	No; defaults to extracting until the end of the string is reached.

If start is zero and length is omitted, the whole string will be returned.

Example: substr parameters

emit 
| put s = "Hello World!" 
| put ss0 = String.substr(s, 0),       // Hello World!
      ss6 = String.substr(s, 6),       // World!
      ss05 = String.substr(s, 0, 5),   // Hello 
      ss_65 = String.substr(s, -6, 5)  // World

Example: using substr to shorten a name

// convert a long identifier into a short label

emit -points [
  {name: "f79ca0aed8914533269a", value: 123},
  {name: "15adb9cced74531343b8", value: 456}
]
| put label = String.substr(name, 0, 6)
| keep time, label, value

String.toLowerCase

Convert a string to lowercase characters.

String.toLowerCase(string)

Parameter	Description	Required?
`string`	The string to convert to lowercase	Yes

Example: Convert a camel-case string to lowercase

emit -limit 1 
| put name="NorthDakota"
| put newname=String.toLowerCase(name)
| view text

String.toUpperCase

Convert a string to uppercase characters.

String.toUpperCase(string)

Parameter	Description	Required?
`string`	The string to convert to uppercase	Yes

Example: Convert a camel-case string to uppercase

emit -limit 1 
| put name="NorthDakota"
| put newname=String.toUpperCase(name)
| view text

String.trim

Returns the given string, minus any leading or trailing whitespace.

String.trim(string)

Parameter	Description	Required?
`string`	The string to trim	Yes

Example

emit -points [{string: ' hello \t'}]
| put trim = String.trim(string)