1[vset VERSION 0.8]
2[manpage_begin textutil::split n [vset VERSION]]
3[see_also regexp(n)]
4[see_also split(n)]
5[see_also string(n)]
6[keywords {regular expression}]
7[keywords split]
8[keywords string]
9[moddesc   {Text and string utilities, macro processing}]
10[titledesc {Procedures to split texts}]
11[category  {Text processing}]
12[require Tcl 8.2]
13[require textutil::split [opt [vset VERSION]]]
14[description]
15
16The package [package textutil::split] provides commands that split
17strings by size and arbitrary regular expressions.
18
19[para]
20
21The complete set of procedures is described below.
22
23[list_begin definitions]
24
25[call [cmd ::textutil::split::splitn] [arg string] [opt [arg len]]]
26
27This command splits the given [arg string] into chunks of [arg len]
28characters and returns a list containing these chunks. The argument
29[arg len] defaults to [const 1] if none is specified. A negative
30length is not allowed and will cause the command to throw an
31error. Providing an empty string as input is allowed, the command will
32then return an empty list. If the length of the [arg string] is not an
33entire multiple of the chunk length, then the last chunk in the
34generated list will be shorter than [arg len].
35
36[call [cmd ::textutil::split::splitx] [arg string] [opt [arg regexp]]]
37
38This command splits the [arg string] and return a list. The string is
39split according to the regular expression [arg regexp] instead of a
40simple list of chars.
41
42[emph Note]: When parentheses are used in the [arg regexp], i.e. regex
43capture groups, then these groups will be added into the result list
44as additional elements. If the [arg string] is empty the result is the
45empty list, like for [cmd split].
46
47If [arg regexp] is empty the [arg string] is split at every character,
48like [cmd split] does.
49
50The regular expression [arg regexp] defaults to "[lb]\\t \\r\\n[rb]+".
51
52[list_end]
53
54[vset CATEGORY textutil]
55[include ../common-text/feedback.inc]
56[manpage_end]
57