Liquid XML Studio
SubString
See Also Send Feedback
Data Mapping > Data Mapper Functions > By Category > String > SubString

Glossary Item Box

Function Name
SubString
Category
String
Icon
SubString
Description
Retrieve section of input String
Inputs
String Text String to retrieve SubString from
Start String index to start the SubString from
Length Length of desired SubString
Outputs
Result Text String representing SubString from input String
Properties
None -

Usage

The Data Mapper String SubString function retrieves a portion of a source String as a SubString. Often, when mapping data, you may face limitations in terms of storage or differing application logic within the target context which requires you to map only a portion of selected input Strings. The SubString function allows you to map sections of input Strings by defining start position and length. To apply the String SubString transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using office_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<office>
 <file type="corporate">
  <ref>12345abcde</ref>
  <title>Smith and Mitchell</title>
 </file>
 <file type="individual">
  <ref>54321fghij</ref>
  <title>James Black</title>
 </file>
</office>

For our target schema we will be using office_target.xsd, inferred from the following XML:

Target XML Copy Code
<associates>
 <account reference="98765">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

The data models office files for an organisation. Here is the Data Mapper with Source and Target imported:

Data Mapper String Upper Function

Let's assume that we only want to map the numerical part of the "ref" item in the source, which represents the first 5 characters in the String. Drag the String SubString function from the Component Palette into the mapping area:

String SubString Component

String SubString Transform Added

The String SubString function takes three inputs and gives a String output. The String input should be connected to the source String you want to retrieve part of. The Start and Length inputs should be connected to numbers, for which we will use Constants. The output should be connected to the target item, which may be in the XML Writer or another mapping component if you need to apply further transformations.

Connect the SubString String input to the "ref" output in the XML Reader, and the SubString output to the "reference" item in the XML Writer.

String SubString Transform Mapped

Now we need to represent the Start and Length numbers, so drag 2 Constants from the Component Palette onto the Mapper. For each one, we need to right-click and choose Show Properties. For the first one, enter "start" as the Name, choose an integer Data Type from the drop-down list and enter 0 as the Value, so that we start the SubString at the beginning of the source String. Setting the name is not strictly necessary but it does help when working with the Mapper.

Start Constant Properties

For the second Constant, set "length" as the Name, an integer Data Type and 5 as the Value.

Length Constant Properties

Now you can see clearly which Constant is which without having to view the properties.

String SubString Constants Added

Now let's map the Constants. Connect the "start" Constant output to the Start input of the SubString function, and the "length" Constant output to the Length input.

String SubString Constants Connected

Finally let's connect the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button (Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<associates>
 <account reference="12345">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="54321">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The input item has been restricted to the first 5 characters as part of the mapping process. If the SubStrings you need are either at the start or end of an input String, you can alternatively use the Left and Right functions.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also