fragment_of_characters

With the function fragment_of_characters you can separate a fragment from the input TEXT based on the number of characters needed and an offset.

The fragment_of_characters function ignores word processor instructions and correctly identifies Unicode characters.

fragment_of_characters ( input_text; offset; fragment_size )

This function yields a value of type TEXT.

The function fragment_of_characters has three parameters separated by semicolons (;):

1. input_text, type TEXT. This is the text of which you want to retrieve a part.
2. offset, type NUMBER. This specifies the starting position of the fragment of characters, the offset. Note that if the offset is 2, that the second character of the input will be the first character of the fragment.
3. fragment_size, type NUMBER. This is the length of the fragment in number of characters.

Classified as a character are:

• Text from the model document.
• Single byte characters from a database (TEXT or C-CHAR datatypes).
• Unicode characters from a database (W-CHAR datatype).
• Some escaped word processor instructions.
• Paragraph breaks.
• Tabs.

Other word processor instructions are ignored.

behavior

• An offset larger than the number of characters of the input_text will result in an empty text.
• An offset smaller than 1 is ignored. The result will be a fragment taken from the start of the input_text.
• A fragment_size smaller than 1 will result in an empty text.
• A fragment_size larger than the length of the input_text from the offset to the end, will result in a fragment containing all text from the offset to the end of input_text.

Escaping Word Processor instructions

Some text can be represented by a Word Processor instruction as well as a character. These Word Processor instructions can be escaped by a "/" (slash) and thus counted. This is, for example, the case with a single quote. A curly, or smart, single quote is a word processor instruction; a straight single quote is a character. An escaped Word Processor instruction is counted as a character.

@( fragment_of_characters ( "abcdefgh"; 2; 4 ) ) 

Result: bcde (Normal behavior)

@( fragment_of_characters ( "abcdefgh"; 1000; 4 ) ) 

Result: (empty text) (Offset too large: empty result)

@( fragment_of_characters ( "abcdefgh"; -2; 4 ) )

Result: abcd (Offset ignored: smaller than 1)

@( fragment_of_characters ( "abcdefgh"; 2; -4 ) )

Result: (empty text) (Fragment-size smaller than 1: empty result)

@( fragment_of_characters ( "abcdefgh"; 2; 20 ) )

Result: bcdefgh (Fragment_length larger than fragment from offset to end: input_text minus offset returned)

@( fragment_of_characters( "abcdefgh"; 2; 4 ) )

Result: bcde. (Bold is a wordprocessor instruction and thus ignored here.)

Fragment_of_characters function versus the text_fragment function

The function fragment_of_characters operates similar to the function text_fragment. The second and third parameter of the text_fragment function specify the starting byte and the number of bytes; where they specify the starting character and the number of characters in the function fragment_of_characters. When bytes are used to create a fragment word processor instructions are counted.

Note

Take care when using the function text_fragment. You can cut Word Processor instructions or Unicode characters in half, which can result in errors and/or unexpected results. To avoid this use the function fragment_of_characters instead.