fn:string-join

In the Graphical Data Mapping editor, you can use the fn:string-join transform to create an output element that is the result of concatenating a sequence of input elements with a delimiter as optional.

Overview

The XPath 2.0 function fn:string-join(arg1, arg2) takes two arguments, converts them to their string representation, and concatenates them, returning a single string.

The fn:string-join transform is the representation of the fn:string-join XPath function in the Graphical Data Mapping editor.

You can have any number of inputs to the fn:string-join transform. These inputs can be used to define the arguments of the fn:string-join function.

Inputs to the transform

You can connect one or more inputs to the fn:string-join transform. These inputs are used to define the arguments of the fn:string-join function.
  • One of the primary inputs must be a repeatable simple element. This input is used to define the first argument of the fn:string-join function. It defines the sequence of elements that you want to concatenate.
    Note: When the type of the repeating elements is different from xs:string, the Graphical Data Mapping editor will cast the element to a xs:string type.
  • One of the primary inputs can be a simple type element. This input is used to define the second argument of the fn:string-join function. It defines the delimiter used between the elements that you want to concatenate.
    Note: If the simple type is not of type xs:string, the transform will fail at run time with BIP3945E. Cast the element to a string if you want to use a non-string input element as your delimiter. For more information, see Cast type (xs:type).

    This figure shows the cats of an input integer element used as a delimiter.

  • More inputs can be connected to the fn:string-join transform. You can use these inputs as additional information to the transform. For example, you can use these inputs as arguments of the XPath expression that you can define in the Condition tab to determine whether the transform is applied at run time.

Arguments of the XPath function

You define the arguments to the fn:string-join function in the General tab of the fn:string-join transform properties view.
  • The first argument is a sequence of elements.
  • The second argument is a delimiter. The delimiter is optional. If the separator defined for the fn:string-join function is a zero-length string, no delimiter is used.

In the following figure, the fn:string-join transform has one input. The input is used to define the first argument of the fn:string-join function. No delimiter is configured.

This figure shows the fn:string-join transform.

The following figure shows the fn:string-join transform with one repeating element as input, and a separator. To add the delimiter, you must select the General tab in the Properties view, click Edit, and then enter the value.

This figure shows the fn:string-join transform.

Cardinality

The Cardinality property determines the elements (also known as indexes) in the repeating input element that are processed by the fn:string-join transform.

You can configure the Input array indexes section to select specific instances of the input array. For more information, see Selecting the indexes of input array elements.

This figure shows the Cardinality tab of the XPath transform properties.

Control the instances to be concatenated

When the instances that you need to concatenate need to be calculated at run time based on a condition, you can filter dynamically the input indexes by defining a custom XPath conditional expression for the first argument named strings in the General tab. The expression determines which elements of the repeating structure are applied at run time.

For example, to calculate the value of the output element a, you must concatenate the elements in the repeating structure C whose length is greater than 4. You can use the following XPath expression:

$C2[fn:string-length() > 4]

Note: Always use content-assist to build your XPath expressions. You must use the element names used by the Graphical Data Mapping editor.

This figure shows the Cardinality tab of the XPath transform properties.

Define when the transform is applied at run time

You can use any of the input elements to the fn:string-join transform to define a conditional expression that defines the condition under which the transform is applied. If the condition evaluates to true, the transform is applied.

For more information, see Configuring the properties of a transform.