› KCM Template Scripting Developer's Guide › Functions › Text functions › text_fragment

text_fragment

The text_fragmentfunction has been superseded by the fragment_of_charactersfunction. Unless Enhanced Unicode Support is disabled, all calls to text_fragment are automatically mapped to the fragment_of_characters function.

Use the text_fragmentfunction function to extract a fragment from a larger text. 

 text_fragment ( input; offset; length )

The result of this function is of type TEXT.

This function has three parameters:

  1. input, type TEXT. The text from which the fragment is taken.
  2. offset, type NUMBER. The position of the first character of the fragment.
  3. length, type NUMBER. The number of characters in the fragment.

offset starts at 1 for the first character in input. A negative or 0 value is interpreted as the beginning of the value.

A negative or 0 value for length results in an empty result.

If the requested fragment exceeds the number of available characters in the input, the result only contains the available characters from input.

Examples

text_fragment ("abcdefgh"; 2; 4) results in "bcde"

text_fragment ("abcdefgh"; 20; 4) results in ""

text_fragment ("abcdefgh"; -2; 4) results in "abcd"

text_fragment ("abcdefgh"; 2; -4) results in ""

text_fragment ("abcdefgh"; 2; 20) results in "bcdefgh"

The text_fragment function is limited to content that only consists of latin-1 text. This function does not support word processor instructions or Unicode content. Use of this function with non latin-1 content can result in run-time errors or broken result documents.