dot Operators

This is Tinderbox Cookbook version 2.0.0, created in conjunction with Tinderbox 5.11.2.

The locale settings used to export this document: en-GB. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.

This page explores use of the newer 'dot' operators so-termed as they are written appended to attribute or literal data values by a dot: $MyString.size().

Deprecation. Some codes are now marked 'deprecated'. This means that while they may still work, such syntax should be avoided. New documents should not use such syntax and existing documents in regular use should be have their code reviewed to avoid retaining deprecated usage.

Color.blue

Property to get/set the blue RGB channel of a Color attribute. Set by number (0-255) or hex (#00-#ff). Get always returns a number sic.

description try expect result ok

Fetches the value of the blue RGB channel. always returns a number (0-255)

$MyColor.blue 255 255 not yet

$MyColor is set to #0000cc

$MyColor.blue 204 204 not yet

This note's $Rule is:

$MyColor="black";$MyColor.blue=#cc;$MyNumber=$MyColor.blue$MyString=$MyColor;

Hex 'cc' is the equivalent of 204 decimal. The .blue operator always returns a number value. If a color has been (partially) set with a colour operator, like .blue, it's overall value is a hex value when passed to a string - regardless of whether originally set as a string name or a hex value. Thus, here $MyString is "#0000cc" and not "black".

$MyNumber 204 204 not yet

Color.brightness

Property to get/set the the brightness of a Color attribute. The brightness value is always a number (0-100) representing a percentage brightness.

description try expect result ok

$MyColor set to 0-0-50. Note that brightness conversions are approximate

round($MyColor.brightness) 50 50 not yet

$MyColor HSB value 180-0-100

Rule: $MyColor2.brightness = ($MyColor.brightness / 2)

$MyColor is white (#ffffff) so we expect a brightness of 50%

round($MyColor2.brightness) 50 50 not yet

Color.format

Returns a hex-based string regardless of whether the referenced color value is hex-based or a named color.

description try expect result ok

$MyColor = "bright red". Note how use of formatting returns hex value.

$MyColor.format #ff0000 #ff0000 not yet

$MyColor = "#009999".

$MyColor.format #009999 #009999 not yet

Color.green

Property to get/set the green RGB channel of a Color attribute. Set by number (0-255) or hex (#00-#ff). Get always returns a number sic.

description try expect result ok

Fetches the value of the green RGB channel. always returns a number (0-255)

$MyColor.green 255 255 not yet

$MyColor is set to #00cc00

$MyColor.green 204 204 not yet

This note's $Rule is:

$MyColor="black";$MyColor.green=#cc;$MyNumber=$MyColor.green$MyString=$MyColor;

Hex 'cc' is the equivalent of 204 decimal. The .green operator always returns a number value. If a color has been (partially) set with a colour operator, like .green, it's overall value is a hex value when passed to a string - regardless of whether originally set as a string name or a hex value. Thus, here $MyString is "#00cc00" and not "black".

$MyNumber 204 204 not yet

Color.hue

Property to get/set the hue of a Color attribute. The hue value is always a bumber 0-360 representing a circular offset value in degrees for the hue.

description try expect result ok

$MyColor set to #00ff00.

$MyColor.hue 120 120 not yet

$MyColor #00ff00

Rule: $MyColor2.hue = ($MyColor.hue + 120)

$MyColor2.hue should be 240 (120 + 120)

$MyColor2.hue 240 240 not yet

Color.red

Property to get/set the red RGB channel of a Color attribute. Set by number (0-255) or hex (#00-#ff). Get always returns a number sic.

description try expect result ok

Fetches the value of the red RGB channel. always returns a number (0-255)

$MyColor.red 255 255 not yet

$MyColor is set to #cc0000

$MyColor.red 204 204 not yet

This note's $Rule is:

$MyColor="black";$MyColor.red=#cc;$MyNumber=$MyColor.red$MyString=$MyColor;

Hex 'cc' is the equivalent of 204 decimal. The .red operator always returns a number value. If a color has been (partially) set with a colour operator, like .red, it's overall value is a hex value when passed to a string - regardless of whether originally set as a string name or a hex value. Thus, here $MyString is "#0000cc" and not "black".

$MyNumber 204 204 not yet

Color.saturation

Property to get/set the saturation of a Color attribute. The saturation value is always a number (0-100) representing a percentage saturation.

description try expect result ok

$MyColor set to 17-36-47.

round($MyColor.saturation) 36 36 not yet

$MyColor HSB value 200-40-47

Rule: $MyColor2.saturation = ($MyColor.saturation / 2)

$MyColor is white (#ffffff) so we expect a brightness of 50%

round($MyColor2.saturation) 20 20 not yet

Date.day

Gets or sets the 1 or 2 digit day for the Date-type attribute specified. Valid range 1-31.

description try expect result ok

$Date = 1 Oct 2010

$Date.day 1 1 not yet

Rule: $Date2 = $Date; $Date2.year = 24;

$Date2.day 24 24 not yet

$Date is "never"

$Date.day 0 0 not yet

Date.format("formatString")

Formats the date according to the format string.

description try expect result ok

$TestDate = 12/02/2011 17:51

The test's "Expected" string assumes a day/month order locale. Adjust as required.

$TestDate.format("l") 12/02/2011 12/02/2011 not yet

Date.hour

Gets or sets the 1 or 2 digit hour for the Date-type attribute specified. Valid range 0-23.

description try expect result ok

$Date = 1 Oct 2010 20:22

$Date.hour 20 20 not yet

Rule: $Date2 = $Date; $Date2.year = 14;

$Date2.hour 14 14 not yet

$Date is "never"

$Date.hour 0 0 not yet

Date.minute

Gets or sets the 1 or 2 digit minute for the Date-type attribute specified. Valid range 0-59.

description try expect result ok

$Date = 1 Oct 2010 20:22

$Date.minute 22 22 not yet

Rule: $Date2 = $Date; $Date2.year = 9;

$Date2.minute 9 9 not yet

$Date is "never"

$Date.minute 0 0 not yet

Date.month

Gets or sets the 1 or 2 digit month for the Date-type attribute specified. Valid range 1-12.

description try expect result ok

$Date = 1 Oct 2010

$Date.month 10 10 not yet

Rule: $Date2 = $Date; $Date2.month = 12;

$Date2.month 12 12 not yet

$Date is "never"

$Date.month 0 0 not yet

Date.weekday

Gets read-only day number for the Date-type attribute specified. Value range is 1-7. Days number from 1 (Monday) to 7 (Sunday). This numbering allows easy testing for weekday (#1-5) vs. weekend (#6-7).

description try expect result ok

$Date is Friday 1 October 2010 which equates to weekday #5.

$Date.weekday 5 5 not yet

$Date is "never"

$Date.weekday 0 0 not yet

Date.year

Gets or sets the 1 to 4 digit year for the Date-type attribute specified.

description try expect result ok

$Date = 1 Oct 2010

$Date.year 2010 2010 not yet

$Date: "01/10/2010". $Rule: $Date2 = $Date; $Date2.year = 2005;

$Date2.year 2005 2005 not yet

$Date is "never"

$Date.year 0 0 not yet

List.at(N)

Returns the Nth value of the List as a string. List can be either Set or List type attributes (or string literal, regex, or expression equivalents thereof).

The operator is zero-based, i.e. an N value of 0 returns the first list item, an N of 1 returns value #2, etc. If the value of N exceeds the number of items in the list an empty string (blank value) is returned.

Negatives are allowed, though they work off a 1-based series with -1 being the last item, -2 being the penultimate item, etc.

description try expect result ok

$TestList = "ant;bee;cow;dog"

$TestList.at(2) cow cow not yet

$TestList = "ant;bee;cow;dog". No item #11 so we expect an empty string

$TestList.at(10) not yet

$TestList = "ant;bee;cow;dog"

$TestList.at(-2) cow cow not yet

List.contains("patttern")

This operator tests whether pattern matches the target string attribute or matches a whole discrete value string within a the target list/set attribute value. The match gives a Boolean result. The match is case-sensitive.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= 1, coerce to Boolean 'true' as is needed in a query context.

description try expect result ok

$TestList: "ant;bee;cow"

$TestList.contains("bee") 2 2 not yet

$TestList: "ant;bee;cow"

contains() used with List/Set values is case-sensitive.

$TestList.contains("Bee") 0 not yet

List.empty()

Returns a Boolean depending on whether the string/list is empty. If empty, the return value is true, if the attribute has content then false is returned.

description try expect result ok

$TestList = "ant;bee;cow"

TestList.empty() false not yet

The count of $TestList values is: 0

$TestList.empty() true true not yet

List.format("delimiterString")

Allows a list/set to be output as a single concatenated string. A longer 4-parameter version is allowed for creating HTML lists.

description try expect result ok

$TextList = ant;bee;cow

$TestList.format(", ") ant, bee, cow ant, bee, cow not yet

$TextList = ant;bee;cow

$TestList.format("
    ","
  • ","
  • ","
")
  • ant
  • bee
  • cow
  • ant
  • bee
  • cow
not yet

List.icontains("patttern")

This operator tests whether pattern matches the target string attribute or matches a whole discrete value string within a the target list/set attribute value. The match gives a Boolean result. The match is case-insensitive.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= 1, coerce to Boolean 'true' as is needed in a query context.

description try expect result ok

$TestList: "ant;bee;cow"

$TestList.icontains("bee") 2 2 not yet

$TestList: "ant;bee;cow"

The icontains() test is case-insensitive.

$TestList.icontains("Bee") 2 2 not yet

List: .intersect(list)

This returns a list (a Set) of all values in both Lists. It makes no difference to the resulting data which way the two source lists are ordered.

description try expect result ok

$TestSet: "ant;bee;cow;bee", $UserSet: "bee;cow;dog;cow"

$TestList.intersect($ValueList) bee;cow bee;cow not yet
"ant;bee;cow;dog".intersect("ant;dog;eel") ant;dog ant;dog not yet

List.isort($AttributeName)

Re-sorts a list or set in case-insensitive lexical order (including string literal lists).

description try expect result ok

$TestList: "cow;eel;bee;dog"

$TestList.isort() bee;cow;dog;eel bee;cow;dog;eel not yet

$TestList: "cow;eel;bee;dog"

$TestList.isort().reverse eel;dog;cow;bee eel;dog;cow;bee not yet

$TestList: "cow;Eel;Bee;dog"

$TestList.isort() Bee;cow;dog;Eel Bee;cow;dog;Eel not yet

$TestList: "cow;Eel;Bee;dog"

$TestList.isort().reverse() Eel;dog;cow;Bee Eel;dog;cow;Bee not yet

$TestList: "ant;bee;Ant;Cow;Bee;cow"

$TestList.isort() ant;Ant;bee;Bee;Cow;cow ant;Ant;bee;Bee;Cow;cow not yet

$TestList: "ant;bee;Ant;Cow;Bee;cow"

$TestList.isort().reverse() cow;Cow;Bee;bee;Ant;ant cow;Cow;Bee;bee;Ant;ant not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

This test sorts the referenced items in terms of their $MyString attribute, case-insensitive: Carol (peach), Ted (pear), Alice (Plum), Bob (pomegranate).

$TestList.isort($MyString) Carol;Ted;Alice;Bob Carol;Ted;Alice;Bob not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

This test sorts the referenced items in terms of their $MyString attribute, case-insensitive, reversed: Bob (pomegranate), Alice (Plum), Ted (pear), Carol (peach).

$TestList.isort($MyString).reverse() Bob;Alice;Ted;Carol Bob;Alice;Ted;Carol not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

EXPECTED FAIL.

This test fails because the attribute-based sort is on lexical value (2,25,4,5) not numeric (2,4,5,25) even though the target attribute is numeric.

Instead, use .sort() if target attribute is known to be Number-type, or .nsort() if the source is a string literal list needing numeric sort.

$TestList.isort($UserNum) Bob;Carol;Ted;Alice Bob;Alice;Carol;Ted not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

The dates are in ascending order, noting that 'never' sorts last as 'never' always sorts after any actual date.

Use .sort() if sorting on a Date-type attribute.

$TestList.isort($Date) Carol;Ted;Alice;Bob Carol;Ted;Alice;Bob not yet

List.nsort($AttributeName)

Re-sorts a list or set in numerical order (including string literal lists).

description try expect result ok

Note that lists of any kind are stored as strings.

A lexical sort would give: 1,2,22,3,6,9.

"9;6;1;2;22;3".nsort() 1;2;3;6;9;22 1;2;3;6;9;22 not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

A number sort is used (i.e. 2,4,5,25) as opposed to the more general lexical sort (2,25,4,5) used in other sorts.

$TestList.nsort($UserNum) Bob;Carol;Ted;Alice Bob;Carol;Ted;Alice not yet

List.replace()

Note that for lists/set the replace only targets whole values for replacement

description try expect result ok

$TestList value: "ant;bee;cow"

$TestList.replace("cow","cat") ant;bee;cat ant;bee;cat not yet

$TestList value: "bit;mit;sit"

$TestList.replace("it","at") bat;mat;sat bat;mat;sat not yet

List.reverse()

Reverses the current sort of a list or set.

description try expect result ok

$TestList = "ant;bee;cow"

$TestList.reverse() cow;bee;ant cow;bee;ant not yet

List.size()

Returns the number of items in the list.

description try expect result ok

$TestList value: "ant;bee;cow"

$TestList.size() 3 3 not yet

$TestList value: "ant;bee;cow"

Test without trailing parentheses.

$TestList.size 3 3 not yet

$TestList: ""

$TestList.size() 0 0 not yet

List.sort($AttributeName)

Re-sorts a list or set in case-sensitive lexical order (including string literal lists). If Number or Date type attributes are used as optional attribute sort, the sort order is appropriate to data type; numbers sort numerically, ascending and dates in ascending order with 'never' preceding all dates.

description try expect result ok

$TestList: "cow;eel;bee;dog"

$TestList.sort() bee;cow;dog;eel bee;cow;dog;eel not yet

$TestList: "cow;eel;bee;dog"

$TestList.sort().reverse eel;dog;cow;bee eel;dog;cow;bee not yet

$TestList: "cow;Eel;Bee;dog"

$TestList.sort() Bee;Eel;cow;dog Bee;Eel;cow;dog not yet

$TestList: "cow;Eel;Bee;dog"

$TestList.sort().reverse dog;cow;Eel;Bee dog;cow;Eel;Bee not yet

$TestList: "ant;bee;Ant;Cow;Bee;cow"

$TestList.sort() Ant;Bee;Cow;ant;bee;cow Ant;Bee;Cow;ant;bee;cow not yet

$TestList: "ant;bee;Ant;Cow;Bee;cow"

$TestList.sort().reverse() cow;bee;ant;Cow;Bee;Ant cow;bee;ant;Cow;Bee;Ant not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

This test sorts the referenced items in terms of their $MyString attribute, case-sensitive: Alice (Plum),Carol (peach), Ted (pear), Bob (pomegranate).

$TestList.sort($MyString) Alice;Carol;Ted;Bob Alice;Carol;Ted;Bob not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

This test sorts the referenced items in terms of their $MyString attribute, case-sensitive, reversed: Bob (pomegranate), Alice (Plum), Ted (pear), Carol (peach).

$TestList.sort($MyString).reverse() Bob;Ted;Carol;Alice Bob;Ted;Carol;Alice not yet

$Rule: $TestSet = collect(children(/data/sorts,$Name);$TextList=$TextSet

TestList: "Ted;Bob;Alice;Carol"

Because $UserNum is Number-type data, a number sort is used (i.e. 2,4,5,25 and not the lexical sort (2,25,4,5) used otherwise).

$TestList.sort($UserNum) Bob;Carol;Ted;Alice Bob;Carol;Ted;Alice not yet

$Rule: $TestSet = collect(children(/data/sorts),$Name);$TestList=$TestSet

TestList: "Ted;Bob;Alice;Carol"

Whose dates are 2 Feb, [never], 11 Feb, 1 Feb

Because $Date is Date-type data, a date order sort is used; never, 1 Feb, 2 Feb, 11 Feb, never.

Important: via a List.sort(), 'never' (no date) always sorts first, i.e. no date is less that any date. This is the reverse of a container sort (using $Sort) based on a Date-type Attribute.

collect(children(/data/sorts),$Name).sort($Date) Bob;Carol;Ted;Alice Bob;Carol;Ted;Alice not yet

List.substr()

Although .substr() can work on lists & sets, it does so upon the stored semi-colon delimited string and is generally thus of less value. Use is thus deprecated in this context.

List.tr()

Simulates the command line tr function allowing all instances of a single [sic] character to be replaced with another. More useful for changing adding invisible control characters (new line, tab, etc.) than for normal characters where .replace works just as well.

description try expect result ok
"ant;apple;ant;aardvark".tr("a","A") Ant;Apple;Ant;AArdvArk Ant;Apple;Ant;AArdvArk not yet

$TestList: "ant;apple;aardvark"

$TestList.tr("a","A") Ant;Apple;AArdvArk Ant;Apple;AArdvArk not yet

List.unique()

Returns the List unsorted but de-duped. akin to passing into a set-type attribute and back.

description try expect result ok

$TestList value: "ant;bee;cow;bee"

$TestList.unique() ant;bee;cow ant;bee;cow not yet

$TestList value: "ant;bee;cow"

$TestList.unique() ant;bee;cow ant;bee;cow not yet

$TestList value: "ant;bee;cow;bee"

$TestList.unique.sort.reverse cow;bee;ant cow;bee;ant not yet

Number.format(decimalsN,widthN)

Formats a decimal number to a string with decimalsN decimal paces. To aid right-aligning numbers, optionally, widthN left-pads the number with spaces so that widthN = spaces+number; number idoes not count the decimal point character.

description try expect result ok

$TestNumber = 3.14159

$TestNumber.format(2) 3.14 3.14 not yet

$TestNumber = 3.14159

$TestNumber.format(2,7) 3.14 3.14 not yet

Number.precision()

Sets the number of decimal places to show for a non-integer.

description try expect result ok

$UserNum: "23.4567"

Last decimal place rounds up as pertinent.

$UserNum.precision(2) 23.46 23.46 not yet

$UserNum: "214.4"

Trailing zeroes can be added - useful for things like currency values (e.g. $ItemPrice).

$UserNum.precision(2) 214.40 214.40 not yet

Set.at(N)

Returns the Nth value of the List as a string. List can be either Set or List type attributes (or string literal, regex, or expression equivalents thereof).

The operator is zero-based, i.e. an N value of 0 returns the first list item, an N of 1 returns value #2, etc. If the value of N exceeds the number of items in the list an empty string (blank value) is returned.

description try expect result ok

$TestSet = "ant;bee;cow;dog"

$TestSet.at(1) bee bee not yet

Set.contains("patttern")

This operator tests whether pattern matches the target string attribute or matches a whole discrete value string within a the target list/set attribute value. The match gives a Boolean result. The match is case-sensitive.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= 1, coerce to Boolean 'true' as is needed in a query context.

description try expect result ok

$TestSet: "ant;bee;cow"

$TestSet.contains("bee") 2 2 not yet

$TestSet: "ant;bee;cow"

Note that .contains is case sensitive

$TestSet.contains("Bee") 0 not yet

Set.empty()

Returns a Boolean depending on whether the string/list is empty. If empty, the return value is true, if the attribute has content then false is returned.

description try expect result ok

$TestSet = "ant;bee;cow"

$TestSet.empty() false not yet

$TestSet has no value.

$TestSet.empty() true true not yet

Set.icontains("patttern")

This operator tests whether pattern matches the target string attribute or matches a whole discrete value string within a the target list/set attribute value. The match gives a Boolean result. The match is case-insensitive.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= 1, coerce to Boolean 'true' as is needed in a query context.

description try expect result ok

$TestSet: "ant;bee;cow"

$TestSet.icontains("Bee") 2 2 not yet

Set: .intersect(list)

This returns a list (a Set) of all values in both Sets. It makes no difference to the resulting data which way the two source sets are ordered.

description try expect result ok

$TestSet: "ant;bee;cow", $UserSet: "bee;cow;dog"

$TestSet.intersect($UserSet) bee;cow bee;cow not yet
"ant;bee;cow;dog".intersect("ant;dog;eel") ant;dog ant;dog not yet

List.replace() / Set.replace()

Note that for lists/set the replace only targets whole values for replacement

description try expect result ok

$TestSet value: "ant;bee;cow"

$TestSet.replace("cow","cat") ant;bee;cat ant;bee;cat not yet

$TestSet value: "bit;mit;sit"

$TestSet.replace("it","at") bat;mat;sat bat;mat;sat not yet

Set.reverse()

Reverses the current sort of a list or set.

description try expect result ok

$TestSet = "ant;bee;cow"

$TestSet.reverse() cow;bee;ant cow;bee;ant not yet

Set.size()

Returns the number of items in the list.

description try expect result ok

$TestSet: "ant;bee;cow"

$TestSet.size() 3 3 not yet

$TestSet: "ant;bee;cow"

Test without trailing parentheses.

$TestSet.size 3 3 not yet

$TestSet: ""

$TestSet.size() 0 0 not yet

Set.substr()

Although .substr() can work on lists & sets, it does so upon the stored semi-colon delimited string and is generally thus of less value. Use is thus deprecated in this context.

Set.tr()

Simulates the command line tr function allowing all instances of a single [sic] character to be replaced with another. More useful for changing adding invisible control characters (new line, tab, etc.) than for normal characters where .replace works just as well.

description try expect result ok
"ant;apple;aardvark".tr("a","A") Ant;Apple;AArdvArk Ant;Apple;AArdvArk not yet

$TestSet: "ant;apple;aardvark"

$TestSet.tr("a","A") Ant;Apple;AArdvArk Ant;Apple;AArdvArk not yet

Returns the target string, transforming the initial letter of each word to a capital letter and leaving all other characters unchanged. To achieve title case from a mixed case string chain two commands: String.lowercase.capitalize

Trailing parentheses are optional.

Functionally equivalent to capitalize()

description try expect result ok
"frosty friday".capitalize Frosty Friday Frosty Friday not yet

The function only capitalises the first character of each word.

"frosTy friDay".capitalize FrosTy FriDay FrosTy FriDay not yet
$MyString.capitalize Frosty Friday Frosty Friday not yet

The operatro acts on the string literal created by the expression in the parentheses.

("frosty "+$MyString).capitalize Frosty Friday Frosty Friday not yet

String.contains(pattern)

Tests whether a string literal or string-type attribute matches a string literal or regular expression on a case-sensitive basis.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= coerce to Boolean 'true' as is needed in a query context.

description try expect result ok
"Where is Lincoln".contains("Lincoln") 10 10 not yet

Tests whether this note's text contains the name, "Lincoln"

$Text.contains("Lincoln") 52 52 not yet

Tests whether the text of this note contains a "B" followed by a vowel, as in "Bee".

$Text.contains("B[aeiou]") 80 80 not yet

Tests whether the text of this note contains a capital "b" followed by a vowel, as in "bee" (here all lowercase for test purposes).

The .contains() test is case sensitive.

$Text.contains("B[aeiou]") false not yet

String.empty()

Returns a Boolean depending on whether the string/list is empty. If empty, the return value is true, if the attribute has content then false is returned.

This is the same as short-from test !$StringAttribute for an unpopulated string.

description try expect result ok

$MyString = "This is some text"

$MyString.empty() false not yet

$MySring has no vlaue

$MyString.empty() true true not yet

String.icontains(pattern)

Tests whether a string literal or string-type attribute matches a string literal or regular expression on a case-insensitive basis.

The first match, if any, is returned as a 1-based offset. The 1-base ensures all matches, being >= coerce to Boolean 'true' as is needed in a query context.

description try expect result ok
"Where is Lincoln".icontains("lincoln") 10 10 not yet

Tests whether this note's text contains the name, "Lincoln", in a case-insensitive manner

$Text.icontains("lincoln") 52 52 not yet

Tests whether the text of this note contains a "B" followed by a vowel, as in "Bee", case-insensitively

$Text.icontains("b[aeiou]") 80 80 not yet

String.json()

This operator (added in v5.7.0) returns a JSON-encoded UTF-8 version of a string attribute's value. The straight double quote, solidus (forward slash) and backslash characters are all escaped by a preceding backslash character.

Prior to v5.11.2 the apostrophe (straight single quote) was escaped but this was dropped as it interferes with some AJAX functions in browsers (and is not required by the JSON spec).

description try expect result ok
$MyString.json() Should escape \/solidus, \"double-quote and \\backslash Should escape \/solidus, \"double-quote and \\backslash not yet

String.lowercase()

Returns the string is all lowercase characters.

Trailing parentheses are optional.

Functionally equivalent to lowercase()

description try expect result ok
"FROSTY FRIDAY".lowercase frosty friday frosty friday not yet
$MyString.lowercase frosty friday frosty friday not yet

String.replace(pattern, replacment)

Replace all instances of pattern with replacement in string literal or string-type attribute.

description try expect result ok
"I do not like green eggs".replace("green","blue") I do not like blue eggs I do not like blue eggs not yet
"I do not like green eggs".replace("gre+n","blue") I do not like blue eggs I do not like blue eggs not yet

$MyString: "I do not like green eggs"

$MyString.replace("green","blue") I do not like blue eggs I do not like blue eggs not yet

$MyString: "I do not like green eggs"

$MyString.replace("(green) (eggs)","$2 $1") I do not like eggs green I do not like eggs green not yet

$MyString: "Green eggs and green ham"

$MyString.replace("green","blue") Green eggs and blue ham Green eggs and blue ham not yet

$MyString: "Great green eggs and green ham"

$MyString.replace("green","blue") Great blue eggs and blue ham Great blue eggs and blue ham not yet

$MyString: "Great green eggs and green ham"

$MyString.replace("gre+n","blue") Great blue eggs and blue ham Great blue eggs and blue ham not yet

String.size()

Returns the number of characters in the string - read-only.

description try expect result ok
"Winter is coming".size() 16 16 not yet

$MyString: "Winter is coming"

$MyString.size() 16 16 not yet

$MyString: "Winter is coming"

$MyString(prevSibling).size() 16 16 not yet

String.split()

Splits a string in to a list based on instances of 'patter' in the source string. 'pattern' may be quoted string literal or a regular expression.

description try expect result ok
$MyString.split(" ") ant;bee;cow;ant;cow; ant;bee;cow;ant;cow; not yet
$MyString.split("\W+ ") ant;bee;cow;ant;cow; ant;bee;cow;ant;cow; not yet
$MyString.split("\. ") That was then;This is now.; That was then;This is now.; not yet

String.substr(startN,lengthN)

Read-only. Can get lengthN characters from startN position. startN is zero-based and negative numbers (1-based) work back from the end of the string. If lengthN is omitted everything from startN to end of string is returned.

description try expect result ok

$MyString = "Brave New World"

$MyString.substr(6) New World New World not yet

$MyString = "Brave New World"

$MyString.substr(6,3) New New not yet

$MyString = "Brave New World"

$MyString.substr(-5) World World not yet

$MyString = "Brave New World"

$MyString.substr(-9,3) New New not yet

$MyString = "Brave New World"

lengthN must be positive.

$MyString.substr(-6,-3) New not yet

String.toNumber

Explicit coercion from a string containing numerals to a number. This is occasionally needed as in most cases tinderbox coerces a mix of string/number to a resulting string.

description try expect result ok

$MyString: "40"

$MyString.toNumber 40 40 not yet

String.tr()

Simulates the command line tr function allowing all instances of a single [sic] character to be replaced with another. More useful for changing adding invisible control characters (new line, tab, etc.) than for normal characters where .replace works just as well.

description try expect result ok
"ant, apple, aardvark".tr("a","A") Ant, Apple, AArdvArk Ant, Apple, AArdvArk not yet

$MyString: "ant, apple, aardvark"

$MyString.tr("a","A") Ant, Apple, AArdvArk Ant, Apple, AArdvArk not yet

String.uppercase()

Returns the string is all uppercase characters.

Trailing parentheses are optional.

Functionally equivalent to uppercase()

description try expect result ok
"frosty friday".uppercase FROSTY FRIDAY FROSTY FRIDAY not yet
$MyString.uppercase FROSTY FRIDAY FROSTY FRIDAY not yet