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

Glossary Item Box

Function Name
Length
Category
String
Icon
Length
Description
Return the length of a String
Inputs
String Text String to calculate length of
Outputs
Result Number of characters in the input String
Properties
None -

Usage

The Data Mapper String Length function calculates the length of an input String. If you need to carry out transformations on your input data, you may need to calculate the length of particular items as part of that process. For this reason, the Length function is most likely to be used in conjunction with other mapping functions. To apply the String Length 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="98765klmno">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789pqrst">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

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

Data Mapper Source and Target

Drag the String Length function from the Component Palette into the mapping area:

String Length Component

String Length Transform Added

The String Length function takes a single input and gives a single numerical output. The input should be connected to the source text String item to calculate the length of. The output should be connected to the target item, in most cases another function rather than an item in the XML Writer. Let's assume in this case that we want all but the first 5 characters in the String, for demonstration. Add a Constant to the Mapper:

Constant Added

Alter the Constant properties by right-clicking it, choosing show Properties. Select an integer type from the drop-down list and enter 5 as the Value.

Constant Properties

We will use the Right function to retrieve all of the input String except the first 5 characters. Drag a Right function onto the Mapper:

Right Function Added

Assuming we know nothing about the length of the input String except that we don't want the first 5 characters, we need to calculate the length of the String we want the Right function to return. To achieve this, we need a Subtract function added to the Mapper:

Subtract Function Added

Let's start making some connections. First, connect the "ref" item in the XML Reader to the Length function input and the Length output to the first Subtract input:

Length and Subtract Connected

Next connect the Constant output to the second Subtract input:

Constant to Subtract

Now the output of the Subtract function is what we want to use as the Length input for the Right function, so connect it, also connecting the "ref" item in the XML Reader to the String input of the Right function:

Subtract to Right

Finally, connect the Right function output to the "reference" input in the XML Writer and complete the remaining connections between Reader and Writer:

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="abcde">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="fghij">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The reference attribute value has been restricted to all but the first 5 characters as part of the mapping process. In this case we knew that the String as a whole was length 10, but in reality you may not always know the total length of your input data Strings, which is when the Length function may prove useful.

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

See Also