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 stringof 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 stringof 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 [, ..] ])

bulb 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 stringwith 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 startlocation of zero (0) maps to the first character of the string; the index of the last character is String.length - 1.

If startis positive, it is used as character index counting from the start of the string. If startequals or exceeds the length of the string, an empty string will be returned.

If startvalue is negative, it is used as character index counting from the end of the string. If the absolute value of a negative startexceeds the length of the string, zero will be used as the starting index.
Yes
length The number of characters to extract.

If lengthextends beyond the end of the string, fewer characters than lengthwill be returned. If lengthis 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)