YouTrack Standalone 2017.2 Help

String, Date, and Period Operations

The YouTrack workflow language supports several string and date operations that are used in standard Java libraries.

String Operations

Date Operations

Period Operations

The syntax for these operations is applied differently from other programming languages. When you want to use an operation, simply write the operation after the method or property that returns the appropriate data type. The syntax for each operation is presented in the format: [name]([data type] parameter): [data type].

The workflow editor applies constraints that let you enter only parameters and options that are supported by the workflow programming language. With code completion, the workflow editor displays a description and the available parameters for each operation.

workflowEditorStringOperations thumbnail

The following example demonstrates how to use an operation in a workflow rule.

var extractedUsername = comments.added.first.text.substringBetween("@", " "); project.getUser(extractedUsername).notify("[Youtrack, Comment notice]", "You were mentioned in the comment of issue " + "", true);

This rule extracts the login for a user who is mentioned in comment from the @username substring and sends a notification to the mentioned user.

String Operations

The following operations can be used with fields, methods, and operations that return a string data type.

isEmpty(): Boolean

Description

Checks whether the preceding string is empty ("") or null.

isNotEmpty(): Boolean

Description

Checks whether the preceding string is not empty ("") and not null.

isBlank(): Boolean

Description

Checks whether the preceding string is whitespace, empty ("") or null.

isNotBlank(): Boolean

Description

Checks whether the preceding string is not whitespace, not empty ("") and not null.

trim(enum side[both, start, end], enum mode[asis, blankToNull, nullToEmpty]): string

Parameters

side

Determines which side of the string is trimmed.

mode

Determines how to handle blank and null values.

Description

Removes whitespace from the beginning, end, or both sides of a string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[side: both, mode: asis]

strip()

Strips whitespace from the start and end of a string.

[side: both, mode: blankToNull]

stripToNull()

Strips whitespace from the start and end of a string. If the string is empty ("") after the operation, returns a null value.

[side: both, mode: nullToEmpty]

stripToEmpty()

Strips whitespace from the start and end of a string. If the input string is null, returns an empty string

[side: start, mode: asis]

stripStart(string: const null)

Strips any of a set of characters from the start of a string.

[side: end, mode: asis]

stripEnd(string: const null)

Strips any of a set of characters from the end of a string.

eq(string that, flag ignoreCase): Boolean

Parameters

that

The string to compare to the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Checks whether a string matches a specified string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ignoreCase: false]

equals(string: that)

Checks whether a string matches a specified string. The comparison is case sensitive.

[ignoreCase: true]

equalsIgnoreCase(string: that)

Checks whether a string matches a specified string, ignoring case.

indexOf(string searchStr, [int startPos], flag last): integer

Parameters

searchStr

The string to find in the preceding string.

startPos

Sets the starting position inside the string.

last

Determines whether to search from the start or end of the string.

Description

Finds an index within a string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[last: false]

indexOf(string: searchStr)

Finds the first index within a string, handling null.

[int: startPos, last: false]

indexOf(string: searchStr, int: startPos)

Finds the first index within a string from a start position, handling null.

[last: true]

lastIndexOf(string: searchStr)

Finds the last index within a string, handling null.

[int: startPos, last: true]

lastIndexOf(string: searchStr, int: startPos)

Finds the last index within a string from a start position, handling null.

ordinalIndexOf(string searchStr, int ordinal): integer

Parameters

searchStr

The string to find in the preceding string.

ordinal

The n-th searchStr to find.

Description

Finds an ordinal index within a string.

contains(string searchStr, flag ignoreCase): Boolean

Parameters

searchStr

The search string to find in the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Checks if a string contains a search string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ignoreCase: false]

contains(string: searchStr)

Checks if a string contains a search string, handling null. The comparison is case sensitive.

[ignoreCase: true]

containsIgnoreCase(string: searchStr)

Checks if a string contains a search string, ignoring case, handling null.

containsChars(string searchStr, enum mode[any, none, only]): Boolean

Parameters

searchStr

The search characters to find in the preceding string.

mode

Determines whether to find any, none, or only the specified characters.

Description

Checks if a string contains a search character. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[mode: any]

containsAny(string: searchStr)

Checks if the string contains any character in the given set of characters.

[mode: none]

containsNone(string: searchStr)

Checks that the string does not contain certain characters.

[mode: only]

containsOnly(string: searchStr)

Checks if the string contains only certain characters.

substring(int start, [int end]): string

Parameters

start

The position to start from. A negative integer counts back from the end of the string.

end

The position to end at (exclusive). A negative integer counts back from the end of the string.

Description

Gets a substring from the specified string avoiding exceptions. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[int: start]

substring(int: start)

Gets a substring from the specified string avoiding exceptions. A negative start position can be used to start start number of characters from the end of the string.

[int: start, int: end]

substring(int: start, int: end)

Gets a substring from the specified string avoiding exceptions. A negative start position can be used to start start number of characters from the end of the string. The returned substring starts with the character in the start position and ends before the end position. Position counting is zero-based.

substringOfLength(int length, [int fromPosition], enum side[left, mid, right]): string

Parameters

length

The length of the required string.

fromPosition

The position to start from. A negative integer is treated as zero.

side

Determines whether the string is taken from the left, middle, or right side of the string.

Description

Returns a substring of a specified length from the preceding string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[side: left]

left(int: length)

Gets the leftmost length characters of a string.

[side: right]

right(int: length)

Gets the rightmost length characters of a string.

[int: fromPosition, side: mid]

mid(int: length, int: fromPosition)

Gets the length characters from the middle of a string starting from the specified position.

substringRelative(string separator, enum pos[before, after], flag last): string

Parameters

separator

The string to search for.

pos

The position to start from. A negative integer is treated as zero.

last

Determines whether to search for the first or last occurrence of the separator.

Description

Checks whether a string contains a specified substring relative to a specified separator. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[pos: after, last: false]

substringAfter(string: separator)

Returns the substring after the first occurrence of a separator. The separator is not returned.

[pos: after, last: true]

substringAfterLast(string: separator)

Returns the substring after the last occurrence of a separator. The separator is not returned.

[pos: before, last: false]

substringBefore(string: separator)

Returns the substring before the first occurrence of a separator. The separator is not returned.

[pos: before, last: true]

substringBeforeLast(string: separator)

Returns the substring before the last occurrence of a separator. The separator is not returned.

substringBetween(string open, string close): string

Parameters

open

The string before the substring.

close

The string after the substring.

Description

Returns a string that is nested in between two strings. Only the first match is returned.

split([string separator], [int max], flag preserveAllTokens): sequence<string>

Parameters

separator

The character to use as a delimiter.

max

The maximum number of elements to include in the sequence. A zero or negative value implies no limit.

preserveAllTokens

Determines whether adjacent separators are treated as separators for empty tokens.

Description

Splits a string into a sequence. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[preserveAllTokens: false]

split()

Splits the string into a sequence, using whitespace as the separator.

(string: const "") [preserveAllTokens: true]

splitByWholeSeparatorPreserveAllTokens

Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens.

(string: separator) [preserveAllTokens: false]

splitByWholeSeparator

Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as one separator.

(string: separator, int: max) [preserveAllTokens: false]

splitByWholeSeparator

Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as one separator. Returns a maximum of max substrings.

(string: separator) [preserveAllTokens: true]

splitByWholeSeparatorPreserveAllTokens

Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens.

(string: separator, int: max) [preserveAllTokens: true]

splitByWholeSeparatorPreserveAllTokens

Splits the string into a sequence, separator string specified. The separator is not returned. Adjacent separators are treated as separators for empty tokens. Returns a maximum of max substrings.

remove(string remove, flag ignoreCase, enum side[start, end]): string

Parameters

remove

The string to remove from the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

side

Determines whether to search from the start or end of the preceding string.

Description

Removes all occurrences of a substring from within the source string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ignoreCase: false, side: start]

removeStart(string: remove)

Removes a substring only if it is at the beginning of a source string, otherwise returns the source string. The comparison is case sensitive.

[ignoreCase: true, side: start]

removeStartIgnoreCase(string str, string remove)

Case insensitive removal of a substring if it is at the beginning of a source string, otherwise returns the source string.

[ignoreCase: false, side: end]

removeEnd(string str, string remove)

Removes a substring only if it is at the end of a source string, otherwise returns the source string. The comparison is case sensitive.

[ignoreCase: true, side: end]

removeEndIgnoreCase(string str, string remove)

Case insensitive removal of a substring if it is at the end of a source string, otherwise returns the source string.

replace(string searchString, string replacement, [int max]): string

Parameters

searchString

The string to find in the preceding string.

replacement

The string to replace the searchString with.

max

The maximum number of values to replace.

Description

Replaces all occurrences of a string within another string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

string: searchString, string: replacement

replace(string: searchString, string: replacement)

Replaces a string with another string inside a larger string.

string: searchString, string: replacement, int: max

replace(string: searchString, string: replacement, int: max)

Replaces a string with another string inside a larger string, for the first max values of the search string.

replaceChars(string searchChars, string replaceChars): string

Parameters

searchChars

The characters to find in the preceding string.

replaceChars

The characters to replace the searchChars with.

Description

Replaces multiple characters in a string in one go. This method can also be used to delete characters.

chomp(): string

Description

Removes a new line from the end of a string, if present.

repeat(int times): string

Parameters

times

The number of times to repeat the preceding string.

Description

Repeat a string times number of times to form a new string.

align(int size, [string padStr], enum to[left, right, center]): string

Parameters

size

Specified the length of the new string.

padStr

Determines which characters are added to the preceding string.

to

Determines which part of the string the padStr characters are added to.

Description

Align a string to the specified length. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

(int: size) [to: left]

rightPad

Right pad a string in a larger string of size size using the space character (' ').

(int: size, string: padStr) [to: left]

rightPad(string padStr)

Right pad a string in a larger string of size size. Uses a supplied string as the value to pad the string with.

(int: size) [to: right]

leftPad

Left pad a string in a larger string of size size using the space character (' ').

(int: size, string: padStr) [to: right]

leftPad(string padStr)

Left pad a string in a larger string of size size. Uses a supplied string as the value to pad the string with.

(int: size) [to: center]

center

Centers a string in a larger string of size size using the space character (' ').

(int: size, string: padStr) [to: center]

center(string padStr)

Centers a string in a larger string of size size. Uses a supplied string as the value to pad the string with.

length(): integer

Description

Gets a the length of a string or 0 if the string is null.

upperCase(): string

Description

Converts a string to upper case.

lowerCase(): string

Description

Converts a string to lower case.

capitalize(): string

Description

Capitalizes a string, changing the first letter to title case.

uncapitalize(): string

Description

Uncapitalizes a string, changing the first letter to lower case. No other letters are changed.

is(flag alpha, flag space, flag numeric): Boolean

Parameters

alpha

Determines whether to search for alphabetic characters.

space

Determines whether to search for space characters.

numeric

Determines whether to search for numeric characters.

Description

Checks a string for specific characters. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[alpha: false, space: false, numeric: true]

isNumeric()

Checks if the string contains only unicode digits. A decimal point is not a unicode digit and returns false.

[alpha: false, space: true, numeric: false]

isWhitespace()

Checks if the string contains only whitespace.

[alpha: false, space: true, numeric: true]

isNumericSpace()

Checks if the string contains only unicode digits or space (' '). A decimal point is not a unicode digit and returns false.

[alpha: true, space: false, numeric: false]

isAlpha()

Checks if the string contains only unicode letters.

[alpha: true, space: false, numeric: true]

isAlphanumeric()

Checks if the string contains only unicode letters or digits.

[alpha: true, space: true, numeric: false]

isAlphaSpace()

Checks if the string contains only unicode letters and space (' ').

[alpha: true, space: true, numeric: true]

isAlphanumericSpace()

Checks if the string contains only unicode letters, digits or space (' ').

isAsciiPrintable(): Boolean

Description

Checks if the string contains only ASCII printable characters.

default([string defaultString], flag ifEmpty): string

Parameters

defaultString

The default string to return if the input is null.

ifEmpty

Determines how to handle blank values.

Description

Returns either the current string, an empty string, or the value of a default string. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ifEmpty: false]

defaultString()

Returns either the passed in string, or if the string is null, an empty string ("").

(string: defaultString) [ifEmpty: false]

defaultString(string: defaultStr)

Returns either the passed in string, or if the string is null, the value of defaultStr.

(string: defaultString) [ifEmpty: true]

defaultIfEmpty(string defaultString)

Returns either the passed in string, or if the string is empty or null, the value of defaultStr.

abbreviate(int maxWidth, [int offset]): string

Parameters

maxWidth

The maximum length of the result string. Must be a value of 4 or higher.

offset

The left edge of the source string.

Description

Abbreviates a string using ellipses. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

(int: maxWidth)

abbreviate(int: maxWidth)

Abbreviates a string using ellipses.

(int: offset, int: maxWidth)

abbreviate(int: offset, int: maxWidth)

Abbreviates a string using ellipses with a "left edge" offset.

getLevenshteinDistance(string target): integer

Parameters

target

The string to compare to the preceding string.

Description

Finds the Levenshtein distance between the preceding string and a target string.

startsWith(string prefix, flag ignoreCase): Boolean

Parameters

prefix

The string to find at the start of the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Check if a string starts with a specified prefix. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ignoreCase: false]

startsWith(string: prefix)

Checks if a string starts with a specified prefix.

[ignoreCase: true]

startsWithIgnoreCase(string: prefix)

Case insensitive check if a string starts with a specified prefix.

endsWith(string suffix, flag ignoreCase): Boolean

Parameters

suffix

The string to find at the end of the preceding string.

ignoreCase

Determines whether the comparison is case sensitive.

Description

Check if a string ends with a specified suffix. The parameters determine which of the following operations is performed.

Operations

Parameters

Operation

Description

[ignoreCase: false]

endsWith(string: suffix)

Checks if a string ends with a specified suffix.

[ignoreCase: true]

endsWithIgnoreCase(string: suffix)

Case insensitive check if a string ends with a specified suffix.

Date Operations

The following operation can be used with fields, methods, and operations that return a date data type.

format(string format): string

Parameters

format

The format to apply to the preceding date value.

Description

Applies the specified UTC format to the date value. Returns a string. You can select a pre-defined date format or enter a custom format. Custom date formats start with # and specify date values with the variables y, M, d, and so on.

The difference between two fields with date data types is returned as a duration. The following operation can be used with an operation that returns a duration data type.

millis(): long

Description

Returns the the number of milliseconds in a duration as a long number.

Period Operations

The following operations can be used with fields that return a period data type.

getPeriodFieldValueInMinutes(string fieldName): integer

Parameters

fieldName

The name of a custom field that stores a period type.

Description

Returns the value that is stored in the specified custom field. Returns the value in minutes as an integer.

getPeriodFieldOldValueInMinutes(string fieldName): integer

Parameters

fieldName

The name of a custom field that stores a period type.

Description

Returns the previous value that was stored in the specified custom field before the changes that are applied in the current transaction. Returns the value in minutes as an integer.

setPeriodFieldValueInMinutes(string fieldName, int value): void

Parameters

fieldName

The name of a custom field that stores a period type.

value

The value in minutes to assign to the specified custom field.

Description

Assigns a value to the specified custom field.

Last modified: 7 March 2019
Methods and OperationsWorking with Dates and Times

See Also

Concepts: