String Functions

In this section:

 

String functions operate on information that is in string form. Such strings can be returned from other functions such as _flatof() or can be literals with operation parameters taken from other operations such as xpath(). This section lists and describes the various string functions that you can use in iWay Service Manager.


Top of page

x
_lcase(): Convert to Lower Case

The _lcase() function converts the input string to lower case. The _lcase() function uses the following format:

_lcase(input)

input

string

The string value to be converted to lower case.


Top of page

x
_ucase(): Convert to Upper Case

The _ucase() function converts the input string to upper case. The _ucase() function uses the following format:

_ucase(input)

input

string

The string value to be converted to upper case.


Top of page

x
_trim(): Eliminate Whitespace

The _trim() function removes leading and trailing white spaces from a string. This includes blanks, tabs, and carriage returns. Whitespace includes blanks, tabs, carriage returns, and any characters defined for the current locale as a whitespace character. The _trim() function uses the following format:

_trim(input)

input

string

The string value to be trimmed.


Top of page

x
_normalizespace(): Eliminate Whitespace

The _normalizespace() function removes leading and trailing white spaces from a string. This includes blanks, tabs, carriage returns, and any characters defined for the current locale as a whitespace character. Within the string multiple blanks are converted to a single blank. For example, if the dot character represents a space, _normalizespace('ab…c') yields 'ab.c'.

The _normalizespace() function uses the following format:

_normalizespace(input)

input

string

The string value to be normalized.


Top of page

x
_entity(): Entity Encoding

The _entity() function replaces XML characters with entities, for example, A&B becomes A&B.

The _entity() function uses the following format:

_entity(input)

input

string

The string value to be operated upon.


Top of page

x
_deentity(): Entity Decoding

The _deentity() function replaces XML entities with characters, for example, A&B becomes A&B.

The _deentity() function uses the following format:

_deentity(input)

input

string

The string value to be operated upon.


Top of page

x
_substr(): Substring

The _substr() function extracts a substring from the input string. The substring begins at the starting position and extends to the ending position, which is not included in the substring. If a specific ending position is omitted, the substring extends to the end of the input string. For example, _substr('abcde',1,3) returns bc.

The _substr() function uses the following format:

_substr(input, start [,end])

input

string

The string value to be operated upon.

start

integer

Starting position, base 0.

end

integer

Ending position, base 0.


Top of page

x
_before(): Substring

The _before() function extracts a substring from the input string. The substring begins at the start of the string and extends to the ending string, which is not included in the substring. If omitted, the substring extends to the end of the input string. For example, _before('abcde','de') returns abc.

The _before() function uses the following format:

_before(input, pattern)

input

string

The string value to be operated upon.

pattern

string

Termination of the string.


Top of page

x
_after(): Substring

The _after() function extracts a substring from the input string. The substring begins at the start trigger and extends to the end of the string. For example, _after('abcde','bc') returns de.

The _after() function uses the following format:

_after(input, pattern)

input

string

The string value to be operated upon.

pattern

string

Trigger of the string.


Top of page

x
_pad(): Pad to Desired Length
_pad(input, length [,type [,character [,control]]])

input

string

The string value to be operated upon.

length

integer

Length of desired output.

type

keyword

Direction of the padding.

  • Right. Pad on the right of the input (default).
  • Left. Pad on the left of the input (right justification).

character

char

One character to be used for padding. Default is blank.

control

keyword

Final disposition of the output.

  • asis. Take no action following padding (default).
  • cut. Cut output to length if input is too long.

The input string is padded and optionally cut to fit an exact length. Padding can be done to the right or left of the string.

For example, given the input abc, the following will be the result, using the character b for blank:

Length

Direction

Character

Control

Result

5

right

omit

omit

abcbb

5

left

omit

omit

bbabc

2

right

omit

cut

ab


Top of page

x
_concat(): Concatenate Strings

The _concat() function joins together to generate a single string. For example, if special register x holds the letter 'b', _concat('a',sreg(x),'c') returns abc.

The compiler attempts automatic concatenation when functions are recognized in input strings. For example, the special register iway.home holds the root of the iWay Server installation. So, if you want to address a file named myfile.txt in the mydir subdirectory off the iWay root, use of sreg('iway.home')/mydir/myfile.txt will return the correct path name.

The _concat() function uses the following format:

_concat(input*)

input

string

The string value to be operated upon.


Top of page

x
_length(): String Length

The _length() function returns the number of characters in the supplied input string. It uses the following format:

_length(input)

input

string

The string value to be operated upon.


Top of page

x
_count(): String Element Count

The _count() function returns the number of items in the supplied input string. It uses the following format:

_count(input [,action][,delim])

input

string

The string value to be operated upon.

action

keyword

What to include in the count

  • value. Only nodes containing values.

  • empty. Only nodes with empty values.

  • all. Total of nodes.

delim

character

The field delimiter.

Returns the number of items in the supplied input string. Usually this is one (1). Sometimes an xpath expression will identify several values meeting a test. In such a case this is the number of matches that the xpath expression located in the current document.

A common use is to determine how many elements of a given type are contained in the document. For example, given the document:

<a>
     <top>
     <b>one</b>
     <b>two</b>
      <x>sreg(iwayhome)</x>
     </top>
</a>

The expression _count(xpath(//b)) yields 2, while the expression _count(xpath(//b),empty) yields 0.

The delimiter is not specified when the first parameter (input) is an xpath expression. For other types of input, it may be needed. For example:

_count(“a,b,,c,d”,empty,’,’) yields 1.

Top of page

x
_contains(): String Contents

The _contains() function returns true if the input string contains the value. The search is case sensitive. The _contains() function uses the following format:

_contains(input,value)

input

string

The string value to be operated upon.

value

string

The search value.


Top of page

x
_startswith(): String Contents

The _startswith() function returns true if the input string starts with the value. For example, _startswith('iWay Software','iW') yields true. The _startswith() function uses the following format:

_startswith(input,value)

input

string

The string value to be operated upon.

value

string

The search value.


Top of page

x
_endswith(): String Contents

The _endswith() function returns true if the input string ends with the value. It uses the following format:

_endswith(input,value)

input

string

The string value to be operated upon.

value

string

The search value.


Top of page

x
_regex(): Replace Portions of a String

The _regex() function searches an input string using the regular expression. Any matches are replaced with the value that is specified for the replacement parameter. Regular expressions are specifications of what is to be located and where, for example, locating the first carriage return. The _regex() function uses the following format:

_regex(input, pattern, replacement)

input

string

The string to be operated upon.

pattern

string

Regular expression pattern.

replacement

string

The replacement text.

For example, to change scat, cat to scat, dog, you can use the following _regex() function call:

_regex('scat, cat','\\bcat','dog')

Double backslash characters are used because the pattern must be \bcat and the iWay Functional Language (iFL) handles a single backslash character as an escape character. The \b pattern character is used to specify a word boundary.

Regular expressions are a standard means of searching data, and there are many books on this topic. Some commonly used online references include:

A good book in this topic is:

Hitchens, Ron, "Java NIO", Cambridge, O'Reilly Media, Inc., 2002. [ISBN 0-00288-2]


Top of page

x
_match(): Perform a String Match Against a Pattern

The _match() function matches an input string against a regular expression. A successful match is returned as true, and an unsuccessful match is returned as false.

_match(input,pattern)

input

string

The input string to be matched against the regular expression.

pattern

string

The regular expression pattern.

For more information on regular expression matching, see _regex(): Replace Portions of a String.

For example, to determine whether an attribute value that is contained in a Special Register (SREG) matches a stored SIC code in category 127xx (to be routed to the appropriate subflow), configure the _match() function as follows:

_if(_match(sreg(insic),'127.*'),_setreg('flowcall','subflow127'),_setreg('flowcall','subflowAny'))

The application could then use the subflow SREG as an input to the Process Flow object (XDPFlowAgent) to call the selected subflow.

To check a string against many patterns simultaneously, use the _propertymatch() function. For more information, see _propertymatch(): Match a String Against a File of Regular Expression Patterns.


Top of page

x
_replace(): Translate Characters in a String

The _replace() function translates characters in a string.

_replace(input, chars, replacements [,eoloption])

input

string

The string to be operated upon.

chars

string

The characters in the string to be replaced.

replacements

string

The replacement characters.

eoloption

keyword

End of line conversions. You can specify one of the following conversion options:

  • NONE. No conversion is specified.
  • LF2CR. Map the linefeed character to a carriage return.
  • LF2CRLF. Map the linefeed character to a carriage return linefeed.
  • CRLF2LF. Map the carriage return linefeed sequence to a single linefeed.

This specification is used most often for Windows/UNIX conversions.

The input string is searched for the designated characters. Each located character in the chars operand is replaced with the replacements operand.

The characters in the chars and replacements operands are replaced on a one-for-one basis. The first character in the chars operand is replaced by the first character in the replacements operand, and so forth. Any ASCII character can be entered into either operand. Additionally, escaped sequences, each representing one character, can be included in the operands.

\n

New line

\t

Tab

\r

Line feed

\\

Backslash

\"

Double quote

\'

Single quote

\xcc

Hex character, where cc is the hex representation. For example, \x01 is hex 01.

Example 1. Replace all bar characters with commas. This example is important, as the _xpath functions return lists of values separated by bars.

_replace(_xpath(/root/childval),'|',',')

Example 2. Replace all new lines with tabs.

_replace(sreg(values),\n,\t)

Example 3. In this example, four backslashes are used to represent a paired backslash in the second parameter. This is because the input handlers see the backslashes as two single backslashes. The function then sees the escaped backslash (\\) as a single character. This allows any backslash in the value in the sreg() to be replaced with an ampersand.

_replace(sreg(abc),'\\\\','&')

Top of page

x
_isnumber(): Is a Value Number

The _isnumber() function tests whether the input is a valid number. A value of true indicates that the input is numeric and false indicates that it is not numeric or is not present. Use this to test the results from functions that are expected to return numeric output but may return NAN (not a number) or another value.

The _isnumber() function uses the following format:

_isnumber (input)

input

string

The string value to be operated upon.


Top of page

x
_xml(): XML Concatenation

The _xml() function treats the input string as XML for parsing purposes. Functional replacement is performed but math operations are ignored. If the XML string is in literals, the entire string is treated as a single literal, and no further operation takes place. However if the literal marks (single quotes) are omitted, the parameter can be evaluated.

In the following example, assume that a special register portno has been set to 3284.

Statement

Result

_xml(<root>sreg(portno)</root>)

<root>3284</root>

_xml('<root>sreg(portno)</root>')

<root>sreg(portno)</root>

The _xml() function uses the following format:

_xml(input)

input

string

The string value to be operated upon.


Top of page

x
_sql(): SQL Concatenation

The input string is treated as a string for parsing purposes. Functional replacement is performed but math operations are ignored. This operates identically to _xml().

The _sql() function uses the following format:

_sql(input)

input

string

The string value to be operated upon.


Top of page

x
_qval(): Quote/Null a String

This function generates a quoted string of the input operand. Optionally, the string NULL can be produced. This function is useful when generating values for an SQL insert or update DML statement.

The _qval() function uses the following format:

_qval(input [,char [,action]]))

input

string

The string value to be operated upon.

char

string

A keyword for the type of quote to be used.

  • single. Use single quote characters.
  • double. Use double quote characters.

action

string

A keyword describing the action to perform for nulls or empty input values.

  • none. Null input is quoted empty string.
  • null. Null input is the word NULL (unquoted).
  • empty. Null or empty input is the word NULL (unquoted).
  • spaces. Maps strings that are filled with spaces to NULL (unquoted).

For example, consider the following SQL expression fragment:

values(_qval(a))

This might be represented in iWay Designer as:

values(?a)

with the user field of:

a

xpath(/root/field)

In this example, the input document field addressed in the xpath() returns a value or a null result. Depending on what is returned and the action parameter, the results would be:

Returned

Action Parameter

Result

iway

any

iway

empty value

none

‘’

empty value

null

‘’

empty value

empty

‘’

empty value

spaces

‘’

null value

none

‘’

null value

null

NULL

null value

empty

NULL

null value

spaces

NULL


Top of page

x
_token(): Tokenize a String

Given a delimited string, this function splits the string on the specified delimiter and returns the token at the requested index. The delimiter can be a regular expression and the index of the first token is 1. This function returns an empty string if:

The _token() function uses the following format:

_token(input, delimiter, index)

input

string

The string value to be operated upon.

delimiter

string

The splitter delimiter, which can be a [Java] regular expression.

index

integer

The index of the token desired, base 1. The default is 1.

Examples:

_token('a,b,c,d,e', ',', 3) = c
_token('a/b/c/d/e', '/', 3) = c
_token('a/b/c/d/e', '/', 18) = empty
_token('a_split_b_split_c_split_','_split_',3)=c

The next example accepts x followed by exactly three percent signs, followed by an x or a p:

_token("ax%%%xbx%%%pcx%%%xdx%%%pe",'x\\%{3}[xp]', 3)=c

Note: iFL uses a single backslash to escape the special meanings most characters have in a string of code. To include a single backslash in a string, it must be escaped as well. Use \\ in a string to represent a single backslash. Another example of how to use a single backslash to escape special character meanings is seen in the following expression:

 _token(B2BIT.reshma,'\\.', 1)

The second parameter is a regular expression. You need the backslash to look for the actual dot character. Because iFL is parsing, and it uses the backslash as an escape, you need to escape it to get the backslash into the regular expression. For a more detailed explanation, see _regex(): Replace Portions of a String.


Top of page

x
_indexof(): Return Offset to a Substring

The _indexof() function uses the following format:

_indexof(input, pattern [,startat])

input

string

The string value to be operated upon.

pattern

string

The characters to be located.

startat

integer

Offset to start the search (base 0).

The input string is searched for the contained pattern. The index of the pattern is returned, base 0. The function is useful when you are parsing or extracting elements of an input string.


Top of page

x
_printable(): Mask Nonprintable Characters

The _printable() function uses the following format:

_printable(input [,keyword])

input

string

The string value to be operated upon.

keyword

string

A control word. If whitespace, carriage returns and tabs are not translated.

Sometimes a string that is to be printed may contain unprintable characters. For example, this can result from the _inflate() or _frombase64() function. This function converts non-printable characters to period characters.


Top of page

x
_murmurhash(): Hash a String Value

The _murmurhash() function implements the MurmurHash standard, a non-cryptographic hash function suitable for general hash-based lookup purposes.

Note: The _murmurhash() function is not a cryptographic hash, since MurmurHash is not specifically designed to be difficult to reverse by an adversary.

MurmurHash is useful, among other purposes, for database key generation and lookup, and for use in Bloom filters.

The _murmurhash() function uses the following format:

_murmurhash(input [,algorithm [, seed [, encoding]]])

input

string

Specifies the value to be hashed. If omitted, then the current document payload is hashed.

algorithm

keyword

Specifies the type of algorithm to be used:

  • H16. Yields a 16-bit hash value.
  • H32. Yields a 32-bit hash value.
  • H64. Yields a 64-bit hash value.

The default is H64.

seed

number

Specifies the initial seed in integer or 0x hex form.

  • H16 (0x3175467)
  • H32 (0x9747b28c)
  • H64 (0xe17a1465)

The default is H64 (0xe17a1465).

encoding

string

The Internet Assigned Numbers Authority (IANA) encoding value of the input. The default IANA value is ISO-8859-1.

The output of the _murmurhash() function is expressed as a base-10 integer.

While the H32 and H64 algorithms are generally suitable for database key use, the H16 algorithm is optimized for use in short Bloom filters. The H16 algorithm is calculated using the MurmurHash approach, but is not part of the standard.


iWay Software