VASSAL Reference Manual

Home > Module > Expressions > String Expressions

String Functions

Vassal provides a set of functions to manipulate strings of characters. String functions are always applied to an existing String in an expression in the folowing form:

<string>.function(parameters)

The <string> part can be any string in double quotes ("), or any function or expression that returns a string. See the examples below for ideas on typical usage.

The resulting string is returned for use in further processing. The target string (the part before the '.') is NOT updated by the string function.

Note	All String functions in Vassal are implemented by an underlying Java engine (BeanShell). In Java, BeanShell and Vassal, the characters in a string are numbered starting from 0, not 1. So the first character in a string is always character 0, not character 1

Summary

length

Get length of a String

contains

Check if a string contains another string

isEmpty

Check if a string is empty of characters

isBlank

Check if a string is empty, or only contains space characters

startsWith

Check if a string starts with a particular string

endsWith

Check if a string ends with a particular string

indexOf

Find the first position within a string where another string starts

lastIndexOf

Find the last position within a string where another string starts

matches

Test if a string matches a pattern

substring

Return a section of a string

replace

Replace part of a string with a different string

trim

Remove spaces from the start and end of a string

toUpperCase

Convert lowercase characters in a string to uppercase

toLowerCase

Convert uppercase characters in a string to lowercase

toString

Convert a non-string to a String

Functions

Function	Description
.length()	Return the number of characters in the String. LastZone.length() Return the length of the string contained in the LastZone property. "Beach".length() = 5 "".length = 0
.contains(search)	Returns true if the target string contains the search string. Test.contains("x") Return true of the property Test contains the string "x". "Posx23".contains("x") = true "Pos-23".contains("x") = false "".contains("x") = false
.isEmpty()	Returns true if the target string has no characters in it. CurrentMap.isEmpty() Return true of the property CurrentMap_ is empty. "".isEmpty() = true " ".isEmpty() = false " a".isEmpty() = false
.isBlank()	Returns true if the target string is empty, or only contains spaces. Test.isBlank() Return true of the property Test is empty except for space characters. "".isBlank() = true " ".isBlank() = true " a".isBlank() = false
.startsWith(search)	Returns true if the target string starts with the search string. GetProperty("Test-1").startsWith("ZZ") Return true if the property Test-1 starts with the string "ZZ". "ZZ-23".startsWith("ZZ") = true "ZY-23".startsWith("ZZ") = false
.endsWith(search)	Returns true if the target string ends with the search string. Test.endsWith("ZZ") Return true if the property Test ends with the string "ZZ". "23-ZZ".endsWith("ZZ") = true "ZZ-23".endsWith("ZZ") = false
.indexOf(search)	Searches the target string for the search string and returns the character position within the target string where it is first found, or -1 if not found. { Test.indexOf("zone") < 0 ? "Not Found" : "Found" } If the property Test has the String "zone" anywhere in it, then return "Found", otherwise return "Not Found". "ZZ-23".indexOf("ZZ") = 0 "ZY-23".indexOf("ZZ") = -1 "ZY-23-Y2".indexOf("Y") = 1
.lastIndexOf(search)	Searches the target string for the search string and returns the character position within the target string where it is last found, or -1 if not found. Test.lastIndexOf("-") Return the last position of the hyphen character in the property Test. "23-ZZ-23".lastIndexOf("23") = 6 "ZZ-23".lastIndexOf("ZZ") = 0 "abcdefa".lastIndexOf("A") = -1
.matches(regex)	Returns true if the target string matches a Regular Expression. Test.matches("bowler\|batsman") Return true if the property Test is either of the strings "bowler" or "batsman". See the Regular Expressions page for examples and more information.
.substring(start)	Return the right-hand part of the string starting from character position start. Test.substring(1) Strip off the first character from the value in the Test property and return the rest. "abcdef".substring(2) = "cdef" "abcdef".substring(5) = "f"
.substring(start, end)	Return the portion of the string starting from character position start and ending immediately before character position end. Test.substring(1, 3) Strip off the first character from the value in the Test property and return the next 2 characters. "abcdef".substring(0,0) = "" "abcdef".substring(0,1) = "a" "abcdef".substring(0,2) = "ab" "abcdef".substring(3,5) = "de"
.replace(old, new)	Return a new string where all occurences in the target string of old are replace by new. Test.replace(".", "-") Return the string in the property Test with all periods (.) replaced by hyphens (-). "abcabc".replace("a","X") = "XbcXbc" "abcabc".replace("bca","1") = "a1bc" "abcabc".replace("b","42") = "a42ca42c"
.trim()	Remove spaces from the start and end of a string. UserEntry.trim() Return the string in the property UserEntry with any leading or trailing spaced removed. "abc".trim() = "abc" " abc ".trim() = "abc" " abc def ".trim() = "abc def"
.toUpperCase()	Replace all lower case letters with their upper case equivalent. Does not affect non-letters. UserEntry.toUpperCase() Return the string in the property UserEntry with any lowercase letters converted to uppercase.+ "abc".toUpperCase() = "ABC" " abc12DE[]".toUpperCase() = " ABC12DE[]"
.toLowerCase()	Replace all upper case letters with their lower case equivalent. Does not affect non-letters. UserEntry.toLowerCase() Return the string in the property UserEntry with any lowercase letters converted to uppercase.+ "AbC".toLowerCase() = "abc" " abc12DE[]".toLowerCase() = "abc12de[]"
.toString()	Convert a number or a true/false value to a string that can be operated on by String functions. This is for advanced usage where you need to process a number as if it was a String. ANumber.toString() Return the string equivalent of the number in proprety ANumber. If x = 2, x.toString() = "2" if x = false, x.toString = "false"

Function

Description

.length()

Return the number of characters in the String.

LastZone.length()

Return the length of the string contained in the LastZone property.

"Beach".length() = 5
"".length = 0

.contains(search)

Returns true if the target string contains the search string.

Test.contains("x")

Return true of the property Test contains the string "x".

"Posx23".contains("x") = true
"Pos-23".contains("x") = false
"".contains("x") = false

.isEmpty()

Returns true if the target string has no characters in it.

CurrentMap.isEmpty()

Return true of the property CurrentMap_ is empty.

"".isEmpty() = true
"   ".isEmpty() = false
" a".isEmpty() = false

.isBlank()

Returns true if the target string is empty, or only contains spaces.

Test.isBlank()

Return true of the property Test is empty except for space characters.

"".isBlank() = true
"   ".isBlank() = true
" a".isBlank() = false

.startsWith(search)

Returns true if the target string starts with the search string.

GetProperty("Test-1").startsWith("ZZ")

Return true if the property Test-1 starts with the string "ZZ".

"ZZ-23".startsWith("ZZ") = true
"ZY-23".startsWith("ZZ") = false

.endsWith(search)

Returns true if the target string ends with the search string.

Test.endsWith("ZZ")

Return true if the property Test ends with the string "ZZ".

"23-ZZ".endsWith("ZZ") = true
"ZZ-23".endsWith("ZZ") = false

.indexOf(search)

Searches the target string for the search string and returns the character position within the target string where it is first found, or -1 if not found.

{ Test.indexOf("zone") < 0 ? "Not Found" : "Found" }

If the property Test has the String "zone" anywhere in it, then return "Found", otherwise return "Not Found".

"ZZ-23".indexOf("ZZ") = 0
"ZY-23".indexOf("ZZ") = -1
"ZY-23-Y2".indexOf("Y") = 1

.lastIndexOf(search)

Searches the target string for the search string and returns the character position within the target string where it is last found, or -1 if not found.

Test.lastIndexOf("-")

Return the last position of the hyphen character in the property Test.

"23-ZZ-23".lastIndexOf("23") = 6
"ZZ-23".lastIndexOf("ZZ") = 0
"abcdefa".lastIndexOf("A") = -1

.matches(regex)

Returns true if the target string matches a Regular Expression.

Test.matches("bowler|batsman")

Return true if the property Test is either of the strings "bowler" or "batsman".

See the Regular Expressions page for examples and more information.

.substring(start)

Return the right-hand part of the string starting from character position start.

Test.substring(1)

Strip off the first character from the value in the Test property and return the rest.

"abcdef".substring(2) = "cdef"
"abcdef".substring(5) = "f"

.substring(start, end)

Return the portion of the string starting from character position start and ending immediately before character position end.

Test.substring(1, 3)

Strip off the first character from the value in the Test property and return the next 2 characters.

"abcdef".substring(0,0) = ""
"abcdef".substring(0,1) = "a"
"abcdef".substring(0,2) = "ab"
"abcdef".substring(3,5) = "de"

.replace(old, new)

Return a new string where all occurences in the target string of old are replace by new.

Test.replace(".", "-")

Return the string in the property Test with all periods (.) replaced by hyphens (-).

"abcabc".replace("a","X") = "XbcXbc"
"abcabc".replace("bca","1") = "a1bc"
"abcabc".replace("b","42") = "a42ca42c"

.trim()

Remove spaces from the start and end of a string.

UserEntry.trim()

Return the string in the property UserEntry with any leading or trailing spaced removed.

"abc".trim() = "abc"
" abc  ".trim() = "abc"
"  abc  def ".trim() = "abc  def"

.toUpperCase()

Replace all lower case letters with their upper case equivalent. Does not affect non-letters.

UserEntry.toUpperCase()

Return the string in the property UserEntry with any lowercase letters converted to uppercase.+

"abc".toUpperCase() = "ABC"
" abc12DE[]".toUpperCase() = " ABC12DE[]"

.toLowerCase()

Replace all upper case letters with their lower case equivalent. Does not affect non-letters.

UserEntry.toLowerCase()

Return the string in the property UserEntry with any lowercase letters converted to uppercase.+

"AbC".toLowerCase() = "abc"
" abc12DE[]".toLowerCase() = "abc12de[]"

.toString()

Convert a number or a true/false value to a string that can be operated on by String functions. This is for advanced usage where you need to process a number as if it was a String.

ANumber.toString()

Return the string equivalent of the number in proprety ANumber.

If x = 2, x.toString() = "2"
if x = false, x.toString = "false"