String Manipulation

toUpper

Description: This function converts the Subject into an all upper-case String. Said another way, it replaces any lowercase letter with the uppercase equivalent.

Subject Type: String

Arguments: No arguments

Return Type: String

Examples: If the "filename" attribute is "abc123.txt", then the Expression ${filename:toUpper()} will return "ABC123.TXT"

toLower

Description: This function converts the Subject into an all lower-case String. Said another way, it replaces any uppercase letter with the lowercase equivalent.

Subject Type: String

Arguments: No arguments

Return Type: String

Examples: If the "filename" attribute is "ABC123.TXT", then the Expression ${filename:toLower()} will return "abc123.txt"

trim

Description: The trim function will remove any leading or trailing white space from its subject.

Subject Type: String

Arguments: No arguments

Return Type: String

Examples: If the attribute attr has the value " 1 2 3 ", then the Expression ${attr:trim()} will return the value "1 2 3".

substring

Description: Returns a portion of the Subject, given a starting index and an optional ending index. If the ending index is not supplied, it will return the portion of the Subject starting at the given 'start index' and ending at the end of the Subject value.

The starting index and ending index are zero-based. That is, the first character is referenced by using the value 0, not 1.

If either the starting index is or the ending index is not a number, this function call will result in an error.

If the starting index is larger than the ending index, this function call will result in an error.

If the starting index or the ending index is greater than the length of the Subject or has a value less than 0, this function call will return an empty string.

Subject Type: String

Arguments:

starting index : The 0-based index of the first character to capture (inclusive)
ending index : The 0-based index of the last character to capture (exclusive)

Return Type: String

Examples:

If we have an attribute named "filename" with the value "a brand new filename.txt", then the following Expressions will result in the following values:

Table 1. Table 3. Substring Examples
Expression	Value
`${filename:substring(0,1)}`	`a`
`${filename:substring(2)}`	`brand new filename.txt`
`${filename:substring(12)}`	`filename.txt`
`${filename:substring( ${filename:length():minus(2)} )}`	`xt`

substringBefore

Description: Returns a portion of the Subject, starting with the first character of the Subject and ending with the character immediately before the first occurrence of the argument. If the argument is not present in the Subject, the entire Subject will be returned.

Subject Type: String

Arguments:

value : The String to search for in the Subject

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will result in the following values:

Table 2. Table 4. SubstringBefore Examples
Expression	Value
`${filename:substringBefore('.')}`	`a brand new filename`
`${filename:substringBefore(' ')}`	`a`
`${filename:substringBefore(' n')}`	`a brand`
`${filename:substringBefore('missing')}`	`a brand new filename.txt`

substringBeforeLast

Description: Returns a portion of the Subject, starting with the first character of the Subject and ending with the character immediately before the last occurrence of the argument. If the argument is not present in the Subject, the entire Subject will be returned.

Subject Type: String

Arguments:

value : The String to search for in the Subject

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will result in the following values:

Table 3. Table 5. SubstringBeforeLast Examples
Expression	Value
`${filename:substringBeforeLast('.')}`	`a brand new filename`
`${filename:substringBeforeLast(' ')}`	`a brand new`
`${filename:substringBeforeLast(' n')}`	`a brand`
`${filename:substringBeforeLast('missing')}`	`a brand new filename.txt`

substringAfter

Description: Returns a portion of the Subject, starting with the character immediately after the first occurrence of the argument and extending to the end of the Subject. If the argument is not present in the Subject, the entire Subject will be returned.

Subject Type: String

Arguments:

value : The String to search for in the Subject

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will result in the following values:

Table 4. Table 6. SubstringAfter Examples
Expression	Value
`${filename:substringAfter('.')}`	`txt`
`${filename:substringAfter(' ')}`	`brand new filename.txt`
`${filename:substringAfter(' n')}`	`ew filename.txt`
`${filename:substringAfter('missing')}`	`a brand new filename.txt`

substringAfterLast

Description: Returns a portion of the Subject, starting with the character immediately after the last occurrence of the argument and extending to the end of the Subject. If the argument is not present in the Subject, the entire Subject will be returned.

Subject Type: String

Arguments:

value : The String to search for in the Subject

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will result in the following values:

Table 5. Table 7. SubstringAfterLast Examples
Expression	Value
`${filename:substringAfterLast('.')}`	`txt`
`${filename:substringAfterLast(' ')}`	`filename.txt`
`${filename:substringAfterLast(' n')}`	`ew filename.txt`
`${filename:substringAfterLast('missing')}`	`a brand new filename.txt`

getDelimitedField

Description: Parses the Subject as a delimited line of text and returns just a single field from that delimited text.

Subject Type: String

Arguments:

index : The index of the field to return. A value of 1 will return the first field, a value of 2 will return the second field, and so on.
delimiter : Optional argument that provides the character to use as a field separator. If not specified, a comma will be used. This value must be exactly 1 character.
quoteChar : Optional argument that provides the character that can be used to quote values so that the delimiter can be used within a single field. If not specified, a double-quote (") will be used. This value must be exactly 1 character.
escapeChar : Optional argument that provides the character that can be used to escape the Quote Character or the Delimiter within a field. If not specified, a backslash (\) is used. This value must be exactly 1 character.
stripChars : Optional argument that specifies whether or not quote characters and escape characters should be stripped. For example, if we have a field value "1, 2, 3" and this value is true, we will get the value 1, 2, 3, but if this value is false, we will get the value "1, 2, 3" with the quotes. The default value is false. This value must be either true or false.

Return Type: String

Examples: If the "line" attribute contains the value "Jacobson, John", 32, Mr. and the "altLine" attribute contains the value Jacobson, John|32|Mr. then the following Expressions will result in the following values:

Table 6. Table 8. GetDelimitedField Examples
Expression	Value
`${line:getDelimitedField(2)}`	_(space)_32
`${line:getDelimitedField(2):trim()}`	32
`${line:getDelimitedField(1)}`	"Jacobson, John"
`${line:getDelimitedField(1, ',', '"', '\\', true)}`	Jacobson, John
`${altLine:getDelimitedField(1, '\|')}`	Jacobson, John

append

Description: The append function returns the result of appending the argument to the value of the Subject. If the Subject is null, returns the argument itself.

Subject Type: String

Arguments:

value : The String to append to the end of the Subject

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the Expression ${filename:append('.gz')} will return "a brand new filename.txt.gz".

prepend

Description: The prepend function returns the result of prepending the argument to the value of the Subject. If the subject is null, returns the argument itself.

Subject Type: String

Arguments:

value : The String to prepend to the beginning of the Subject

Return Type: String

Examples: If the "filename" attribute has the value "filename.txt", then the Expression ${filename:prepend('a brand new ')} will return "a brand new filename.txt".

replace

Description: Replaces all occurrences of one literal String within the Subject with another String.

Subject Type: String

Arguments:

Search String : The String to find within the Subject
Replacement : The value to replace Search String with

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 7. Table 9. Replace Examples
Expression	Value
`${filename:replace('.', '_')}`	`a brand new filename_txt`
`${filename:replace(' ', '.')}`	`a.brand.new.filename.txt`
`${filename:replace('XYZ', 'ZZZ')}`	`a brand new filename.txt`
`${filename:replace('filename', 'book')}`	`a brand new book.txt`

replaceFirst

Description: Replaces the first occurrence of one literal String or regular expression within the Subject with another String.

Subject Type: String

Arguments:

Search String : The String (literal or regular expression pattern) to find within the Subject
Replacement : The value to replace Search String with

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 8. Table 10. ReplaceFirst Examples
Expression	Value
`${filename:replaceFirst('a', 'the')}`	`the brand new filename.txt`
`${filename:replaceFirst('[br]', 'g')}`	`a grand new filename.txt`
`${filename:replaceFirst('XYZ', 'ZZZ')}`	`a brand new filename.txt`
`${filename:replaceFirst('\w{8}', 'book')}`	`a brand new book.txt`

replaceAll

Description: The replaceAll function takes two String arguments: a literal String or Regular Expression (NiFi uses the Java Pattern syntax), and a replacement string. The return value is the result of substituting the replacement string for all patterns within the Subject that match the Regular Expression.

Subject Type: String

Arguments:

Regex : The Regular Expression (in Java syntax) to match in the Subject
Replacement : The value to use for replacing matches in the Subject. If the regular expression argument uses Capturing Groups, back references are allowed in the replacement.

Return Type: String

Examples: If the "filename" attribute has the value "a brand new filename.txt", then the following Expressions will provide the following results:

Table 9. Table 11. ReplaceAll Examples
Expression	Value
`${filename:replaceAll('\..*', '')}`	`a brand new filename`
`${filename:replaceAll('a brand (new)', '$1')}`	`new filename.txt`
`${filename:replaceAll('XYZ', 'ZZZ')}`	`a brand new filename.txt`
`${filename:replaceAll('brand (new)', 'somewhat $1')}`	`a somewhat new filename.txt`

padLeft

Description: The padLeft function prepends the given padding string (or '_', if nothing is provided) to the argument String until the passed desired length is reached.

It returns the argument as is if its length is already equal or higher than the desired length, if the padding string is null, and if the desired length is either negative or greater than Integer.MAX_VALUE. It returns null if the argument string is not a valid attribute.

Subject Type: String

Arguments:

DesiredLength : The integer value to pad to.
PaddingString : The optional string to pad with. "_" will be used if a PaddingString is not provided. If the PaddingString is not an exact multiple of the actual pad size, it will be trimmed to fit in DesiredLength.

Return Type: String

Examples: If the "greetings" attribute has the value "hello", then the following Expressions will provide the following results:

Table 10. Table 12. PadLeft Examples
Expression	Value
`${greetings:padLeft(10)}`	`_____hello`
`${greetings:padLeft(10, '@')}`	`@@@@@hello`
`${greetings:padLeft(10, 'xy')}`	`xyxyxhello`
`${greetings:padLeft(10, 'aVeryLongPaddingString')}`	`aVeryhello`

padRight

Description: The padRight function appends the given padding string (or '_', if nothing is provided) to the argument String until the passed desired length is reached.

It returns the argument as is if its length is already equal or higher than the desired length, if the padding string is null, and if the desired length is either negative or greater than Integer.MAX_VALUE. It returns null if the argument string is not a valid attribute.

Subject Type: String

Arguments:

DesiredLength : The integer value to pad to.
PaddingString : The optional string to pad with. "_" will be used if a PaddingString is not provided. If the PaddingString is not an exact multiple of the actual pad size, it will be trimmed to fit in DesiredLength.

Return Type: String

Examples: If the "greetings" attribute has the value "hello", then the following Expressions will provide the following results:

Table 11. Table 13. PadLeft Examples
Expression	Value
`${greetings:padRight(10)}`	`hello_____`
`${greetings:padRight(10, '@')}`	`hello@@@@@`
`${greetings:padRight(10, 'xy')}`	`helloxyxyx`
`${greetings:padLeft(10, 'aVeryLongPaddingString')}`	`helloaVery`

replaceNull

Description: The replaceNull function returns the argument if the Subject is null. Otherwise, returns the Subject.

Subject Type: Any

Arguments:

Replacement : The value to return if the Subject is null.

Return Type: Type of Subject if Subject is not null; else, type of Argument

Examples: If the attribute "filename" has the value "a brand new filename.txt" and the attribute "hello" does not exist, then the Expression ${filename:replaceNull('abc')} will return "a brand new filename.txt", while ${hello:replaceNull('abc')} will return "abc".

replaceEmpty

Description: The replaceEmpty function returns the argument if the Subject is null or if the Subject consists only of white space (new line, carriage return, tab, space). Otherwise, returns the Subject.

Subject Type: String

Arguments:

Replacement : The value to return if the Subject is null or empty.

Return Type: String

Examples: If the attribute "filename" has the value "a brand new filename.txt" and the attribute "hello" has the value " ", then the Expression ${filename:replaceEmpty('abc')} will return "a brand new filename.txt", while ${hello:replaceEmpty('abc')} will return "abc".

length

Description: Returns the length of the Subject

Subject Type: String

Arguments: No arguments

Return Type: Number

Examples: If the attribute "filename" has a value of "a brand new filename.txt" and the attribute "hello" does not exist, then the Expression ${filename:length()} will return 24. ${hello:length()} will return 0.

evaluateELString

Description: This function evaluates the Expression Language inside the variable value.

Subject Type: String

Arguments: No arguments

Return Type: String

Examples: If one of the registry variable named "query" has value "SELECT * FROM TABLE WHERE ID = ${id}" and the value of the "id" field, we are getting from the flowfile attributes (i.e. id=20) then the Expression ${query:evaluateELString()} will return SELECT * FROM TABLE WHERE ID = 20

repeat

Description: Returns a string that is the Subject repeated a random number of times between min repeats and max repeats. If max repeats is not supplied, it will return the Subject repeated exactly min repeats times.

The min repeats and max repeats must be positive numbers, with max repeats greater than or equal to min repeats

If either min repeats or max repeats is not a number, this function call will result in an error.

Subject Type: String

Arguments:

min repeats : The minimum number (inclusive) of times to repeat the subject, or the exact number of times to repeat the subject if max repeats is not supplied.
max repeats : The maximum number (inclusive) of times to repeat the subject.

Return Type: String

Examples:

If we have an attribute named "str" with the value "abc", then the following Expressions will result in the following values:

Table 12. Table 14. Repeat Examples
Expression	Value
`${str:repeat(1)}`	`abc`
`${str:repeat(2)}`	`abcabc`
`${str:repeat(1,2)}`	`abc` or `abcabc` (at random)
`${str:repeat( ${str:length()} )}`	`abc` or `abcabc` or `abcabcabc` (at random)