Group	Basic functions

This function is deprecated.

The function can sequentially deliver the component values of a structure data type. In addition, general collection operations are provided.

This function is based on a specific object type, the splitter object, which is similar to named list or named map. Usually, successively different methods are called for a splitter object at different locations of the destination tree. To access a splitter object, no other functions exist as the one described here. It encapsulates all the operations for splitter objects.

Methods

The function has various methods, which are addressed by the mandatory parameter a. It is sufficient to specify the first character of the method name in a. These names are not case-sensitive.

For better understanding, we group the methods into basic methods and advanced methods.

Mode fix or csv

In the operating mode fix, a Fixed Record structure is processed and in mode csv a CSV structure. The operating mode is set during initialization of the splitter object and remains the same throughout the life of the object. During its life, the status of the object is changed by the use of methods. The result of a call of this function depends on the following factors:

Mode in which the object was initialized.
Method a and optional parameters b and c.
Content of current values and status of the splitter.
Context to which the call refers.

Context

A splitter object is assigned to a particular node of the destination structure. The assignment is implicitly about the name of the node. The node and its immediate child fields, but not the subnodes, together form a common context. The function can be assigned to either a node or its children fields and then refers to the context of the node. To this context, by initializing a splitter object can be associated or not.

In any context, at most, one splitter can exist. All methods that relate to a specific context, relate therefore to the same splitter object. If in this context no splitter object exists, all methods refer to no splitter object.

Methods without explicitly specifying a context in b refer to the current context in which they are executed.

The optional context b can be the unique name of another destination node (including #xy). In this case, the method refers to the splitter object that is associated with this other destination node. If there is no splitter object in the context b , the method refers to no splitters.

Basic Methods

Method a	Parameter b	Parameter c	Result	Short Description
init	fix	Structure in FixRecord format.	Number of characters in the splitter.	Creates und initializes the splitter in mode fix.
init	csvdelimiter	Structure in CSV format.	Number of values in the splitter.	Creates und initializes the Splitter in mode csv.
exist	Optional: The context.		Boolean: true/false	Does as splitter exist in the context?
hasNext	Optional: The context.		Boolean: true/false	Does the splitter have another value?
key	Optional: The context.		Context name.	Returns the name of addressed context. Placeholders in b are resolved.
destroy	Optional: The context.	Optional flag: first	Integer: 0	Destroys the splitter.
bomb		Optional flag: first	no value	Destroys all splitters in this profile job.

The life cycle of the splitter object starts within the context of the node by initializing with the method init. The mode is determined at this time and will not change until the end of the lifetime of the splitter. If in this context already existed a splitter, it is destroyed. If the structure value of parameter c was an empty value (see notes on Empty Flag), no splitter is created. But a preexisting splitter is destroyed in this case too.

In CSV mode, the delimiter in parameter b should, of course, be the same as the separator within the token list c. Parameter b for CSV mode can optionally have the prefix csv or be given as a single character or in the Unicode description \uXXXX. The single character is case-sensitive, but the Unicode circumscription is not case-sensitive. For example, if the delimiter is A: csvA or csv\u0041 or A or \u0041 are equivalent. If in b, more than one character is given as a delimiter, only the first character is used, but leading spaces are ignored. Circumscription of Unicode (\uXXXX), NewLine (\n or \NL), CR (\r or \CR) and Tab (\t or \TAB) are resolved.

The methods exist, destroy, and hasNext are not dependent on the mode of the splitter.

All methods that can have an optional context name in parameter b are related to the current context if b leaves blank. If parameter b contains the name of another context (that means another node), the method is executed within this foreign context. If the specified context name is not the name of an existing destination node, the methods behave as if they are called in a context where no splitter object was created. The wildcards #parent (context of the parent node) and #self (own context) are also allowed. The placeholder #self is only relevant for the extended method link as the target context (see below).

Hint: Accessing the splitter within a foreign context is supported for all methods except init and add. These methods can only relate to the current context.

After initializing a splitter, the behaviour and the number of supported methods is different for the modes fixed and csv.

Methods destroy or bomb with flag first are only processed within the first iteration.

Important hint: The function clear all maps() will also destroy all value splitters.

More Basic Methods for Mode fix

Mode	Method a	Parameter b	Parameter c	Result	Short Description
fix	type	Optional: The context.		String: fix	The key for mode fix.
fix	count	Optional: The context.		Integer: Number of characters in splitter.	Returns the current character count.
fix	next	Optional: The context.	Optional: Flags.	String: Next field value.	Returns the next field and removes it from the splitter.
fix	value	Optional: The context.		String: Rest in splitter.	The remaining values of the splitter.

If parameter b remains empty, the method relates to the current context. Calling with an explicit context b the method will query the splitter within this foreign target context if any. The full name of a Node is expected. Placeholder #parent can be used to address the context of the parent node.

Method next in mode fix is usable only for fields because a node has no field length. As many characters are returned and removed from the splitter, as the size of this field specifies. If the field has a length of 0, no characters are removed from the splitter and the call will return an empty string (a valid string with 0 chars). If the splitter currently contains no value (if hasNext is false), an empty string is also returned by next.

Parameter c can contain the flags for method next:

trim will trim the value.
destroy destroys the splitter after the last value is returned.

A flag is considered to be set if the corresponding text is set in parameter c (ignore-case). Combining multiple flags is allowed.

More Basic Methods for Mode csv

Mode	Method a	Parameter b	Parameter c	Result	Short Description
csv	type	Optional: The context.	Optional: Flags.	String: csvdelim	Returns mode csv and delimiter \uxxxx. Flag: u oder c.
csv	count	Optional: The context.		Integer: Count of values.	Current count of field values.
csv	next	Optional: The context.	Optional: Flags.	String: Next value.	Returns the next field value and removes it from the splitter.
csv	value	Optional: The context.	Optional: CSV delimiter.	String: Remaining values in splitter.	The remaining values in the splitter as token list.

Usage of the parameter b, as in the fix mode, in order to address a foreign context.

In method type, the format of the returned value is controlled by an optional flag in parameter c.

With the flag u, only the delimiter is returned as a Unicode transcription \uxxxx
With the flag c, only the delimiter character itself is returned without a transcription.
Without a flag returning: csv\uxxxx

In method next, the optional parameter c can contain the flags trim, destroy, and trunc (TruncationError). With the flag trunc, an error will occur if the next field value is longer than the field size. The flag trunc can only be used if the function is assigned to a field. A node has no size for comparison.

If the splitter contains no value, the method next will return an empty string.

Method value returns all field values contained currently within the splitter as a token list. If parameter c was empty, the initial delimiter is used as assigned during initialization of the splitter object. Otherwise, the value of c is used as a separator for the token list. Here, as an exception, multiple characters can be used as a separator. Within the token list there is no Unicode transcription, but if parameter c contains a single character as delimiter, this character can be specified by Unicode transcription \uXXXX instead.

Important hint: If the method value detects that the delimiter in parameter c already is contained in one of the field values of the splitter, it terminates with an error.

Base Methods Within a Context That Has No Valid Splitter Object Assigned

Mode	Method a	Parameter b	Parameter c	Result	Short Description
csv	type	Optional: The context.		no value	No value.
csv	count	Optional: The context.		Integer: 0	The number 0.
csv	next	Optional: The context.		String: ""	An empty string (a string of length 0).
csv	value	Optional: The context.		no value	No value.

Usage of parameter b is similar to mode fix or csv. Parameter c is ignored if no splitter object exists.

Advanced Methods

Common Advanced Methods for Modes fix and csv

Assembling a Structure Value of Single Values by Method add

Method a	Parameter b	Parameter c	Result	Short Description
add	Optional: fix	String.	Number of chars contained in the splitter after method add.	Appends a character sequence at the end.
add	csvdelimiter	Field value.	Count of contained field values after method add.	Appends the field value at the and.

The method add appends the value as passed by parameter c onto an existing splitter. The mode of an existing splitter can not be modified by parameter b. Therefore, parameter b is ignored in this case. If the method is performed in a context where there is currently no splitter, a new splitter with the mode b is created, and the value c is added as the first value. This corresponds to the method init. The CSV separator can be specified, just as in method init, with prefix csv, or as a single character or as a Unicode transcription.

In contrast to the method init, the method add expects as parameter c not a structure value with several field values, but a single value.

In mode csv, the value to be added must not contain the CSV delimiter. Otherwise, the function will terminate with an error.

In mode fix, the formatting and alignment of the value is done in accordance with the field size and alignment of the field, where the function is assigned.

If the field length is 0, the value will be trimmed, and then inserted with the trimmed length.
If the field length > 0 and a fill value is defined, the value is trimmed and cut or filled to the defined field length.
Note: If no fill value is defined, the value remains unchanged. Then there is no guarantee that the field length is used.

When the function is attached to a node, this formatting is not possible. In this case, you should previously format the value accordingly.

Connecting Multiple Nodes to a Common Context by Method link

Method a	Parameter b	Parameter c	Result	Short Description
link		The target context.	Number of chars/values within the target splitter.	Links the current context with the target context.
link	Optional: The context.	The target context.	Number of chars/values within the target splitter.	Links the context b with the target context.

The method link with an empty parameter b will associate the current context with the target context, as specified in parameter c. If in the target context a splitter exists, the following methods will relate to this splitter. If no splitter is in the target context, the current context will have thereafter also no splitter. If the current context before the method had its own splitter, it is destroyed. If the current context was previously linked to a different context, this link is terminated and replaced by the new link.

If the method link is called with a parameter b containing a valid context name, the method is called for this foreign context instead of the current context. It is allowed to link a foreign context b to the current context by using a placeholder #self as parameter c, since parameter c is mandatory and can therefore not be left blank.

The return value of method link depends on whether a splitter exists in the target context and what is its mode. The return is like calling the count method within the target context. It thus provides the number of characters or values in the target splitter, or 0 if in the target context no splitter exists.

If the target context of the link method is already a linked context, the link is followed to the final target.

Calling one of the methods destroy, init or link within a linked context will not influence the splitter object within the target context itself, but only will destroy the link.

Advanced Methods Only for csv Mode (operation on collections)

Conceptually, there is a difference between csv mode and fix mode. In a csv splitter, the individual values are split already at initialization time. The csv splitter, therefore, stores field values. In contrast, the FixRecord structure of a fix splitter is not divided into individual fields during initialization. The field boundaries occur only when removing a value by the next method, according to the size of the field to which the method is applied.

This is the reason why the operations on collections are not available for a fix splitter since they refer to a collection of values, which exists only within a csv mode splitter.

Method a	Parameter b	Parameter c	Result	Short Description
order	Optional: The context.	Optional: Flag descend.	Number of values in the splitter after method order.	Sort the field values lexically.
select	Optional: The context.	Regular expression.	Selected values as a token list.	Provides a subset of the values that match the expression.
x	Optional: The context.	Regular expression.	Index list of selected values.	Same as select but returns index list instead of values.
unique	Optional: The context.	Optional: flag sequence.	Number of values in the splitter after method unique.	Removes duplicates from the list of values.
+	Optional: The context.	Optional: flags.	Sum of numerical values.	Sums the values numerically.

The methods order and unique may change the stored value set. The select returns only a selection of the values as a token list but does not modify the values in the splitter object. The delimiter in the token list is the splitter's stored CSV delimiter as it was set during initialization. If you really want to set the selected values as the content of the splitter, you have to initialize the splitter again with the token list.

Ordering is done lexically ascending. The flag descending within parameter c indicates a lexically descending order sequence.

If removing duplicate values by method unique, the first occurrence is retained and removed subsequent duplicates will be removed. The flag sequence in parameter c overrides this behaviour so that the last occurrence will be retained and previous duplicates are removed. This means that the insertion order remains within the unique result.

The method + adds all values in the splitter numerically and returns the sum as a result. The splitter content itself remains unchanged. The summation is based on a BigDecimal addition with 34 digits and rounding mode half_even. The optional flags, if any, control the behaviour at fault. Default: Empty values (see notes on Empty Flag) are ignored but non-numerical values will raise an error.

strict = All errors result in termination: Non-numeric values and blank values.
lazy = All errors are skipped. The sum is formed only on the values that are numeric.

The flags must be spelt in lowercase letters, abbreviations are not recognised. A decimal value is assumed to have only digits and not more than one decimal point. A sign as prefix is allowed. A comma as the decimal delimiter is not accepted.

Advanced Methods for Mode Ccsv (link to Named List and Named Map)

Method a	Parameter b	Parameter c	Result	Short Description
read	Optional: The context.	Name of the list.	Initalize the splitter by values of the named list.	Copy all values of the named list.
read	Optional: The context.	Map:<name of the map>	Initalize the splitter by keys of the named map.	Copy all keys of the named map.

The method read will initialize the splitter in CSV mode by the values of the named list whose name is passed as the parameter c. The previous content of the splitter is lost. The order of the values in the splitter is the same as in the Named List. The named list itself remains unchanged.

The CSV delimiter is set automatically. The default is the pipe char: |. If one of the values already contains this character, then \u009c is used as a separator.

In the same way, you can read the key values of a named map as a list when in parameter c the name of a map preceded by the prefix Map: is specified. Since the keys of a map are not in a defined sequence, the order in the splitter is also indeterminate. Subsequent sorting method order can establish an ascending or descending order.

Advanced Methods for 'fix' Mode (line wrap)

Method a	Parameter b	Parameter c	Result	Short Description
wrap	Optional: The context.	Line length.	Multiple lines.	Line break of text to maximum line length.

The wrap method can only be used on a value splitter in fix mode, otherwise, an error occurs. If the text contained in the splitter is longer than the maximum line length (parameter c), it will wrap to multiple lines.

The result of the method is a splitter in csv mode that contains the wrapped lines.

Line breaks are accomplished, if possible, on word boundaries. The spaces and tabs remain contained in the wrapped lines. If no word boundary is contained in a subline, a hard break is done at the maximum line length c possibly even within a word. Lines that are shorter than 1/4 of the maximum line length will not occur in the result. This means that word boundaries at a position less than 1/4 of the value c, are not used for wrapping.

The CSV separator character is set automatically. The default is the NewLine control \n. If a \n was already included in the original text, \u009c is used as a CSV delimiter. Access to the individual lines should take place later with the next method, then the CSV delimiter is irrelevant.

The method wrap is the only method that changes the mode of an existing splitter (fix -> csv).

value-splitter( cmd a, [mode/delim b], [value c] )