Working with Strings

QIE runs your JavaScript inside a Java application, so a "string" in a script is not always the same kind of object it appears to be. This page covers the distinction and the null-safe utility library QIE provides to sidestep it.

Java Strings vs. JavaScript Strings

When dealing with strings in QIE, consideration should be given to the difference between a Java String and a JavaScript String.

QIE is a Java based application so all of the code wizard functions are executed on the back end using Java. All of the customized scripts written by the user in the front end of QIE are written in JavaScript. This means that when a built-in QIE function (functions found in the code wizard) is used it returns a Java "String" (like message.getNode()), the "String" value that is returned is a Java string because the function is executed on the server side or back end.

Problems arise when attempting to compare a Java String to a JavaScript String or vice versa if the comparison does not take into consideration that the values might not be the same type.

In order to prevent these types of errors the java string can be converted to a JavaScript string. To convert a Java String to a JavaScript string simply add + ' ' to the variable. The plus symbol is a JavaScript concatenation operator and the double single quotes represent an empty string value.

This code example shows converting a java string to a JavaScript string.

var jsString = javaString + '';
// The jsString variable will now hold a string value of type
// JavaScript.

Incorrect Example

var orderType = source.getNode('ORC-1');
if (orderType === 'NW') {
  // This code block within this if statement will never get
  // executed because orderType is a Java String,
  // and 'NW' is a JavaScript String and the triple equals
  // compares both the value and the type
}

Correct Example

var orderType = source.getNode('ORC-1') + '';
if (orderType === 'NW') {
  // This code block within this if statement will now
  // get executed if orderType is 'NW' because both
  // are JavaScript Strings
}

Best Practice: Be careful with surmising that you can just use the double equals over the triple equals to solve this problem. Using double equals can lead to unexpected results and should be used by experienced programmers. Best practice would be to use the triple equals, or even better yet use the StringUtils discussed below.

StringUtils

To avoid the problems caused by Java String vs. JavaScript String, QIE provides a StringUtils library that is bound into every script. Its functions are listed in the Code Wizard menu under QIE System Functions and then String Utils.

Note

One advantage to using the StringUtils, is that all of the functions are null safe.

The table below lists some of the most common StringUtils functions compared to the Java and JavaScript string methods.

Best Practice: Whenever possible always use the StringUtils before using either the JavaScript or Java string methods.

Example

var orderType = source.getNode('ORC-1');
if (StringUtils.equals(orderType, 'NW')) {
  // using the StringUtils, this script will now work as
  // intended even though orderType is a Java String
  // and 'NW' is a JavaScript String
}

String methods
	Java	Javascript	StringUtils
Same	charAt(index)	charAt(index)
	indexOf(string)	indexOf(string)	indexOf(text, string)
	indexOf(string, fromIndex)	indexOf(string, fromIndex)	indexOf(text, string, fromIndex)
	lastIndexOf(string)	lastIndexOf(string)	lastIndexOf(text, string)
	lastIndexOf(string, fromIndex)	lastIndexOf(string, fromIndex)	lastIndexOf(text, string, fromIndex)
	replace(target, replacement)	replace(target, replacement)	replace(text, target, replacement)
	split(regexp)	split(regexp)
	split(regexp, limit)	split(regexp, limit)
	substring(beginIndex)	substring(beginIndex)	substring(text, beginIndex)
	substring(beginIndex, endIndex)	substring(beginIndex, endIndex)	substring(text, beginIndex, endIndex)
	toLowerCase()	toLowerCase()	lowerCase(text)
	toUpperCase()	toUpperCase()	upperCase(text)
Similar	length()	length	length(text)
	matches(regexp)	match(regexp)
different	contains(string)		contains(text, string)
			containsIgnoreCase(text, string)
	endsWith(suffix)		endsWith(text, suffix)
			endsWithIgnoreCase(text, suffix)
	equals(anObject)		equals(string, string)
	equalsIgnoreCase(anotherString)		equalsIgnoreCase(string, string)
			isBlank(text)
			isNotBlank(text)
			isAlpha(text)
			isAlphanumeric(text)
			isNumeric(text)
			leftPad(text, size, padStr)
	replaceAll(regexp, replacement)
	replaceFirst(regexp, replacement)
			rightPad(text, size, padString)
	startsWith(prefix)		startsWith(text, prefix)
			startsWithIgnoreCase(text, prefix)
	startsWith(prefix, offset)
			substringBefore(text, separator)
			substringAfter(text, separator)
	trim()		trim(text)
		search(string or regexp)
		split()	split(text)
		split(string)	split(text, string)
		split(string, limit)	split(text, string, limit)
		substr(beginIndex)
		substr(beginIndex, length)

For full documentation, see:

• StringUtils: the Code Wizard, under QIE System Functions -> String Utils, is the authoritative list. QIE's StringUtils is a Qvera-maintained library that began as Apache Commons Lang 2's string utilities; it was kept when Lang 3 changed those APIs, and it has since gained functions with no Apache equivalent. An Apache javadoc therefore does not match what QIE binds. Use the Code Wizard.
• Java: java.lang.String. QIE runs on Java 17.
• JavaScript: String on MDN.