## 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"