When to use S() and nodeValue() for String Conversion

Here are some examples of when to use :nodeValue(), or :S() for string conversion:

:S() to convert an argument of any type to a string

• Use :S() to serialize a non-leaf node (tree) as a string.

• The :S() function performs escaping on values, if the protocol requires it:

  • For XML nodes, it will convert > to >, etc.

  • For HL7 and X12 nodes, it will convert & to \T\, etc.

  • For all other node type no escaping is performed.

The :S() method is simply a shorthand for the Lua tostring() method. They behave the same:

Info

Due to the escaping of special characters on HL7, X12, and XML node types, you will not often want to use :S() on leaf nodes. Instead we recommend :nodeValue().

:nodeValue() to convert a lead node to a string

• Use :nodeValue() to convert a leaf node to a string.

• It is important to use :nodeValue() when converting leaf nodes, particularly with HL7 and XML that use escape characters.

This example shows how :nodeValue() works correctly, but :S() incorrectly escapes XML delimiters:

For more information on working with the different data types see Node Types and Iguana Node Trees.