## `text2list, text2tbl` -- split a character string into substrings

#### Introduction

`text2list` splits a character string into a list of substrings.

`text2tbl` splits a character string into a table of substrings.

#### Call(s)

`text2list(text, separators <, Cyclic>)`
`text2tbl(text, separators <, Cyclic>)`

#### Parameters

`text` | - | the text to be analyzed: a character string
`separators` | - | delimiters: a list of character strings. The empty string is not accepted as a delimiter.

#### Options

`Cyclic` | - | the delimiter list is used cyclicly

#### Returns

a list, respectively a table, of character strings.

#### Related Functions

`coerce`, `expr2text`, `int2text`, `tbl2text`, `text2expr`, `text2int`

#### Details

- Both functions split a string into substrings, using the strings in the list `separators` as delimiters. `text2list` returns a list containing the substrings; `text2tbl` returns a table, using the indices `1`, `2`, `3` etc.
- Without the option Cyclic, the text is split as follows. The first occurrence of one of the delimiters in `separators` is located in `text`. If no delimiter is found, the full text is returned as the only substring. Otherwise, the substring up to the delimiter defines the first substring. The delimiter is the second substring. The remaining text is processed as above until there are no more characters left.

  Without Cyclic, the result does not depend on the order of the delimiters.

- With the option Cyclic, the first delimiter in `separators` is used to identify the first substring. The delimiter itself is the second substring. Then the second delimiter in `separators` is used to identify the third substring etc.

  After using the last delimiter of the list, the first one is used again, until the whole text is processed or until the current delimiter is not found in the remaining text.

  With Cyclic, the result depends on the order of the delimiters.

- `tbl2text` restores strings split by `text2tbl`.
- `text2list, text2tbl` are functions of the system kernel.

#### Example 1

The following example demonstrates the difference in calling `text2list` with and without the option Cyclic:

    >> text2list("This is a simple example!", ["is", "mp"])

           ["Th", "is", " ", "is", " a si", "mp", "le exa", "mp", "le!"]

    >> text2list("This is a simple example!", ["is", "mp"], Cyclic)

                   ["Th", "is", " is a si", "mp", "le example!"]

#### Example 2

The following example demonstrates the difference in calling `text2tbl` with and without the option Cyclic:

    >> text2tbl("This is a simple example!", ["is", "mp"])

                                  table(
                                    9 = "le!",
                                    8 = "mp",
                                    7 = "le exa",
                                    6 = "mp",
                                    5 = " a si",
                                    4 = "is",
                                    3 = " ",
                                    2 = "is",
                                    1 = "Th"
                                  )

    >> text2tbl("This is a simple example!", ["is", "mp"], Cyclic)

                               table(
                                 5 = "le example!",
                                 4 = "mp",
                                 3 = " is a si",
                                 2 = "is",
                                 1 = "Th"
                               )

#### Changes

- no changes

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000