SPLIT(3)

NAME
split - split string into fields

SYNOPSIS
int split(string, fields, nfields, separators)
char *string;
char *fields[];
int nfields;
char *separators;

DESCRIPTION
Split splits the string into fields according to the separators, much in the manner of awk(1)'s field facilities. String has NUL s written into it to do the splitting, and pointers to the resulting strings are placed into the fields array, up to the number specified by nfields. If the number of fields found exceeds nfields, the writing of NUL s stops, so that the last entry in fields points to the remainder of the string.

The returned value is the number of fields present in string, which may exceed nfields. If the returned value is less than nfields, the contents of the remaining entries in fields (up to the limit set by nfields) are undefined. (Note, in particular, that split does not terminate the list of fields with a NULL pointer.)

If separators is a string of length 1, that character is the separator: each occurrence of it separates the current field from a new field, which may be of length 0 if another separator follows immediately.

If separators is a string of length >1, all the characters in it are separators: any sequence of characters composed entirely of separators separates the current field from a new field, which is of length 0 only if it is at the beginning or end of the string. Characters may be duplicated in separators; in particular, a separators string consisting of the same character twice gives fields separated by sequences of that character.

As a special case, if separators is a string of length 0, sequences of white-space characters (here defined as blanks and tabs) are the separators, and sequences of separators at the beginning or end of the string are ignored, so there can be no fields of length 0.

In all cases, an empty string (or, in the case of a separators of length 0, a string consisting only of white space) has 0 fields.

SEE ALSO
awk(1), regexp(3), strtok(3)

HISTORY
Written at University of Toronto by Henry Spencer, with contributions from Geoff Collyer and Mark Moraes.

BUGS
Too many different decisions are bundled into the single separators argument. Arguably it should be a regular expression instead.

Specifying several characters as separators is rather inefficient; if speed is a priority in such a case, it is better to custom-build code that knows about the particular separators desired.