This version is out of date, covering development from v6.0.0 to v6.6.5. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

TinderboxSix Icon


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Altered: 

 Function   [other Function type actions]

 Item   [operators of similar scope]

 Data manipulation   [other Data manipulation operators]




This operator splits a string into a list, as divided by instances of pattern in the original string. Source characters forming part of pattern are not passed to the list. The source string itself is not affected.

pattern is one of:

Useful pattern values are:

The result of the operator is a List-type attribute value, i.e. the data should be passed to a list. Passing the output to a Set-type attribute will de-dupe any list values in the output with the first instance of any duplicates forming its set entry.

For example:

$MyList = "ant bee ant cow".split(" ") gives "ant;bee;ant;cow"

$MySet = "ant bee ant cow".split(" ") gives "ant;bee;cow"

$MyList = "ant, bee, cow".split("\W+ ") gives "ant;bee;cow"

$MyList = "ant, bee, cow".split(" ") gives "ant,;bee,;cow"

$MyList = $MyString.split($MyString(agent)) 

$MyList = $MyString(parent).split("and") 

If the string, stored in $MyString, is multi-line:



$MyList = $MyString.split("\n") gives "ant;bee;cow".

This approach can be useful if trying to retrieve a specific paragraph of $Text, perhaps from notes exploded from a larger consistently formatted text source. To get a string holding just paragraph #3 of the source $Text (or other multi-line string data):

$MyString = $Text.split("\n").at(2) 

Don't overlook the fact that that is zero-based. That means the first list item is .at(0) and so the third list item is '2' and not '3' as might otherwise be assumed. the last item is '-1':

$MyString = $Text.split("\n").at(-1) 

There is one one limitation of this approach to working with $Text or multi-line strings. The issue is that blank lines or lines with only spaces, are ignored - lists don't hold 'empty' items. So if the string $MyString is multi-line and contains blank lines, like so:



$MyList = $MyString.split("\n") still gives "ant;bee;cow".

It does not matter if the blank is just two successive line returns or actually contains some white space - no list item is created for it.

Luckily there is a simple workaround is to seed empty lines with a single hyphen (or whatever placeholder you prefer, e.g. "N/A" or such). Thus:

$MyList = $Text.replace("\n\n","\n-\n").split("\n"); 

…now gives $MyList "ant;-;bee;cow" such that "bee" is still paragraph #3 of the new list, as in the original text. If you wanted to make a deliberate review of such data you might use a more distinctive marker string:

$MyList = $Text.replace("\n\n","\n#####\n").split("\n"); 

You could then query for $MyList.contains(""#####).

Dealing with inline quote characters

Because pattern is parsed for regular expressions, it may be possible to use the '\dnn' form described here to work around the lack of escaping from single double quotes within strings.

Dealing with inline semi-colons

As this function outputs a list, where values are semi-colon delimited, if the source string - such as $Text - has semicolons in it they act as extra (unexpected!) splits when viewing the outcome. To get around this, escape the semicolons on the fly:

$MySet = $Text.replace(";","\\;").split("\n") 

A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : String.split("pattern")