Lists

Source

Methods

(inner) elements(items)

Calculates the number of text, number, or time-date values in a list. This function always returns a number to indicate the number of entries in the list.

Parameters:
NameTypeDescription
itemsArray.<string> | Array.<number> | Array.<Date>

Text list, number list, or time-date list

Source
See
Returns:

The number of items in the list.

Example
rosetta.elements(["item1", "item2"]); // Returns 2

(inner) explode(stringOrDateRange, separatorsopt, includeEmptiesopt, newlineAsSeparatoropt) → {Array.<string>}

Returns a text list composed of the elements of a text string or date range.

  • If you specify a text string, elements are defined as sequences of characters separated by separator characters and newlines.
  • If you specify a time-date range, elements are defined as individual days within the range.
Parameters:
NameTypeAttributesDefaultDescription
stringOrDateRangeTextOrTextList | DateRangeOrDateRangeList

Can be one of the following:

  • The string that you want to make into a text list.
  • The range of dates that you want to make into a text list. Specify a valid date-time range, not a string representation of one. For example, rosetta.explode( "05/01/96 - 05/02/96" ) is invalid because the parameter is a string. Use rosetta.explode( {start: "05/01/96", end: "05/02/96"} ).
separatorsstring<optional>
,;

One or more characters that define the end of an element in string. The default separators are " ,;" (space, comma, semicolon), which means that Domino® adds a new element to the text list each time a space, comma, or semicolon occurs in the original string. When you use more than one character to specify separators, each character defines one separator. For example, the specification "and" breaks the string at each occurrence of "a," "n," and "d"; it does not break the string at each occurrence of the word "and." The newline is a separator, regardless of the specification of this parameter, unless newlineAsSeparator is specified as False.

includeEmptiesboolean<optional>
false

Specify True (1) to place an empty string ("") in the returned list when a separatorappears at the beginning or end of the string, or two separators appear consecutively in the string. Specify False (0) to not include empty list elements for leading, trailing, and consecutive separators. Defaults to False.

newlineAsSeparatorboolean<optional>
true

Specify True (1) to treat the newline as a separator. Specify False (0) to not treat the newline as a separator. Defaults to True.

Source
See
Returns:

A list containing each element found in string, or each date found in dateRange.

Type: 
Array.<string>
Examples
rosetta.explode("a,b,c"); // Returns ["a","b","c"]
const dateRange = {start:"07/02/2023", end:"07/05/2023"};
rosetta.explode(dateRange); // Returns ["07/02/2023", "07/03/2023", "07/04/2023", "07/05/2023"]

(inner) implode(textlistValue, separator) → {string}

Concatenates all members of a text list and returns a text string.

Parameters:
NameTypeDefaultDescription
textlistValueTextOrTextList

List containing the items you want to concatenate into a single string. If you send a single piece of text instead of a list, implode returns the text unaltered.

separatorstring

Used to separate the values in the concatenated string. If you don't specify a separator, a space is used.

Source
See
Returns:

String containing each member of textListValue, separated by separator.

Type: 
string
Examples
rosetta.implode("Minneapolis":"Detroit":"Chicago"); // Returns "Minneapolis Detroit Chicago"
rosetta.implode("Minneapolis":"Detroit":"Chicago";","); // Returns "Minneapolis,Detroit,Chicago"

(inner) isMember(textValue, textListValue)

Indicates if a piece of text (or a text list) is contained within another text list. The function is case-sensitive.

Parameters:
NameTypeDescription
textValueTextOrTextList

The text or text list used to check if it is contained in another text list.

textListValuestring

The text list to check if it contains the text or text list.

Source
See
Returns:

True if the textValue is contained in textListValue or false if not. If both parameters are lists, returns true if all elements of textValue are contained in textListValue.

Examples
rosetta.isMember("computer", ["printer", "computer", "monitor"]); // This example returns true
rosetta.isMember(["computer", "Notes"], ["Notes", "printer", "monitor"]); // This example returns false

(inner) isNotMember(textValue, textListValue)

Indicates if a text string (or a text list) is not contained within another text list. The function is case-sensitive.

Parameters:
NameTypeDescription
textValueTextOrTextList

The text or text list used to check if it is not contained in another text list.

textListValuestring

The text list to check if it does not contain the text or text list.

Source
See
Returns:

True if the textValue is not contained in textListValue or false if it is. If both parameters are lists, returns true if all elements of textValue are not contained in textListValue.

Examples
rosetta.isNotMember("keyboard", ["printer", "computer", "monitor"]); // This example returns 1
rosetta.isNotMember("computer", ["printer", "computer", "monitor"]); // This example returns 0

(inner) keywords(textList1, textList2, separator) → {Array.<string>}

Given two text lists, returns only those items from the second list that are found in the first list.

This function is case-sensitive; you must standardize the case of textList1 and textList2 if you want case to be ignored (use rosetta.lowerCase, rosetta.properCase or rosetta.upperCase).

Parameters:
NameTypeDefaultDescription
textList1Array.<string>

A list of items.

textList2Array.<string>

A list of items that you want to compare to textList1.

separatorstring?. ,!;:[](){}"<>

One or more characters to be used as delimiters between words. rosetta.keywords considers each character (not the combination of multiple characters) to be a delimiter. For example, defining separator as ". ," (period, space, comma) tells the function to separate the text at each period, space, and comma into separate words.

When you do not specify a separator, the following word delimiters are used by default: ?. ,!;:{}"<> (question mark, period, space, comma, exclamation point, semicolon, colon, (brackets, parentheses, braces, quotation mark, and angle brackets)

A null separator, represented by an empty string (""), tells the function to use no delimiters.

Source
See
Returns:

When a separator is in effect, either by default or specification, @Keywords parses textList1 into words delimited by the separator and returns any word that exactly matches a keyword in textList2. When no separator is in effect (when you specify a null separator), @Keywords returns any sequence of characters in textList1 that matches a keyword specified in textList2.

Type: 
Array.<string>
Examples
// This returns Harvard;Yale
rosetta.keywords(@ProperCase("EPA Head speaks at Harvard and yale":"The UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities");"Harvard":"Brown":"Stanford":"Yale":"Vassar":"UCLA");
// This formula returns "", a null string
rosetta.keywords("EPA Head speaks at Harvard,Yale":"UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities";"harvard":"brown":"stanford":"vassar":"ucla");
// This formula returns Harvard;Yale. It searches textList1 for the textList2 keywords that follow either a comma or a space
rosetta.keywords("EPA Head speaks at Harvard, Yale hosts her next month":"UCLA Chancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research facilities";"Harvard":"Brown":"Stanford":"Yale":"UCLA";", ");

(inner) member(value, stringlist)

Given a value, finds its position in a text list.

Parameters:
NameTypeDescription
valuestring

The value you want to find in stringlist.

stringlistArray.<string>

The text list to search.

Source
See
Returns:

Returns 0 if the value is not contained in stringlist. Returns 1 to n if the value is contained in stringlist, where 1 to n is the position of the value in the stringlist.

Examples
rosetta.member("Sales", ["Finance", "Sales", "Service", "Legal"]); // This example returns 2
rosetta.member("Sales", ["Finance":"Service":"Legal"]); // This example returns 0

(inner) nothing()

Use with a transform function. Returns no list element (reducing the return list by one element). Not valid in any other context.

Source
See
Returns:

Returns null in an transform function.

Example
// Returns a 2-element list whose values are 2 and 4;
rosetta.transform([4, -4, 16], "x", x => { if (x >= 0) return Math.sqrt(x); else return rosetta.nothing(); });

(inner) replaceList(sourcelist, fromlist, tolist) → {Array.<string>}

Performs a find-and-replace operation on a text list.

Parameters:
NameTypeDescription
sourcelistArray.<string>

The list whose values you want to scan.

fromlistArray.<string>

A list containing the values that you want to replace.

tolistArray.<string>

A list containing the replacement values.

Source
Returns:

The sourcelist, with any values from fromlist replaced by the corresponding value in tolist. If none of the values in fromlist matched the values in sourcelist, then sourcelist is returned unaltered.

Type: 
Array.<string>
Example
rosetta.replaceList(["Red","Orange","Yellow","Green"], ["Orange","Blue"], ["Black","Brown"]); // Returns ["Red","Black","Yellow","Green"]

(inner) select(position, …values)

Returns the value that appears in the number position. If the number is greater than the number of values, @Select returns the last value in the list. If the value in the number position is a list, returns the entire list contained within the value.

Parameters:
NameTypeAttributesDescription
positionnumber

The position of the value you want to retrieve.

valuesNumberOrNumberList | TextOrTextList | DateOrDateList<repeatable>

Any number of values, separated by semicolons. A value may be a number, text, time-date, or a number list, text list, or time-date list.

Source
See
Returns:

The value that appears in the number position.

Examples
rosetta.select(2,1,2,3); // Returns 2
// Returns [Apr,May,Jun]
rosetta.select(2, ["Jan","Feb","Mar"], ["Apr","May","Jun"], ["Jul","August","Sep"], ["Oct","Nov","Dec"]);

(inner) sort(list, orderopt, customSortExpressionopt)

Sorts a list.

The ascending, case-, and accent-sensitive sort sequence for the English character set is as follows: the numbers 0-9, the alphabetic characters aA-zZ, the apostrophe, the dash, and the remaining special characters. Pitch-sensitivity affects double-byte languages.

Parameters:
NameTypeAttributesDescription
listArray.<string> | Array.<number> | Array.<Date>

The values to be sorted. Any alternate data types are returned unchanged.

orderstring | Array.<string><optional>

You can use the following keywords to specify the order of the sort:

  • "ACCENTSENSITIVE"
  • "ACCENTINSENSITIVE"
  • "ASCENDING"
  • "CASESENSITIVE"
  • "CASEINSENSITIVE"
  • "CUSTOMSORT"
  • "DESCENDING"
  • "PITCHSENSITIVE"
  • "PITCHINSENSITIVE"

By default, the following keywords automatically format the sort order:

["ASCENDING", "CASESENSITIVE", "ACCENTSENSITIVE", "PITCHSENSITIVE"]

You can override a default sort order keyword by specifying its opposite keyword. For example, to override "ASCENDING", specify "DESCENDING" in the sort function. If conflicting keywords are passed, the last one in the list affects the sort order.

customSortExpressionany<optional>

Required when the "CUSTOMSORT" keyword is specified. A formula accepts two parameters, $A and $B, to compare the values of elements in the list two at a time. Return true or a number greater than 0 to specify that $A is greater than $B. Return false or a number less than or equal to 0 to specify that $B is greater than $A. An error is produced if the return value is a data type other than a number or boolean.

Source
See
Returns:

Text, number, or time-date list. The sorted values.

Examples
// Returns ["Albany", "New Boston", "new york", "San Francisco"]
rosetta.sort(["New Boston", "San Francisco", "Albany", "new york"]);
// Returns ["San Francisco", "New Boston", "new york", "Albany"]
rosetta.sort(["New Boston", "San Francisco", "Albany", "new york"], "DESCENDING");
// Returns the movies list in order from the shortest title to the longest; it returns ["ET", "casablanca", "The Great Escape"]
rosetta.sort(["casablanca", "The Great Escape", "ET"], ["CASESENSITIVE", "CUSTOMSORT"], ()=> {if(globalThis.$A.length <= globalThis.$B.length) return false; return true;});

(inner) subset(list, numReturned)

Searches a list from beginning to end and returns the number values you specify. If you specify a negative number, @Subset searches the list from end to beginning, but the result is ordered as from the beginning of the list.

Parameters:
NameTypeDescription
listArray.<string> | Array.<number> | Array.<Date>

Text list, number list, time-date list, or time-date range list. The list whose subset you want.

numReturnednumber

The number of values from list that you want. Specifying zero (0) returns the error, "The second argument to @Subset must not be zero."

Source
See
Returns:

Text list, number list, or time-date list.The list, containing the number of values you specified.

Examples
rosetta.subset(["New Orleans","London","Frankfurt","Tokyo"], 2); // Returns [New Orleans, London]
rosetta.subset(["New Orleans", "London", "Frankfurt", "Tokyo"], -3); // Returns [London, Frankfurt, Tokyo]

(inner) transform(list, variableName, aFunction)

Applies a function to each element of a list and returns the results in a list.

Parameters:
NameTypeDescription
listTextOrTextList | NumberOrNumberList | DateOrDateList

The list to be acted upon.

variableNamestring

The name of a variable passed to the function. This variable is not used.

aFunctiontransformFunction

Valid function that evaluates to a result. The function must return a value or null to indicate no element is added to the return list.

Source
See
Returns:

The result of the transformation on the input list. The first value returned by the formula determines the data type of the list. Subsequent return values must be of the same type.

Examples
// Returns a 3-element array whose values are 2, -2, and 4;
rosetta.transform([4, -4, 16], "x", x => { if (x >= 0) return Math.sqrt(x); else return -Math.sqrt(Math.abs(x)); });
// Returns a 2-element list whose values are 2 and 4;
rosetta.transform([4, -4, 16], "x", x => { if (x >= 0) return Math.sqrt(x); else return null; });

(inner) unique(…values)

Without a parameter, returns a random, unique text value. With a parameter, removes duplicate values from a text list by returning only the first occurrence of each member of the list. rosetta.unique is case-sensitive.

Parameters:
NameTypeAttributesDescription
valuesArray.<string><repeatable>

list of values

Source
See
Returns:

If no parameter is specified and using the Notes Formula implementation, returns a random, unique text value. If no parameter is specified and using the Open Formula implementation, and empty array is returned. If one or more parameter values are present, the values list, with duplicate values removed. or when using the Open Formula implementation see  microsoft.com

Examples
rosetta.unique(["red", "green", "blue", "green", "red"]); // Returns ["red", "green", "blue"]
rosetta.unique("red", "green", "blue", "Green", "red"); // Returns ["red", "green", "blue", "Green"]

Type Definitions

transformFunction(s) → {string|number|Date|null}

Function called for each item in an input list for the transform function.

Parameters:
NameTypeDescription
sstring | number | Date

The item being processed.

Source
Returns:

The item to be added to the list. null indicates no item added.

Type: 
string | number | Date | null