"use strict";
/***************************************************
* Licensed Materials - Property of HCL.
* (c)Copyright HCL America, Inc. 2023-2024
****************************************************/
Object.defineProperty(exports, "__esModule", { value: true });
exports.unique = exports.transform = exports.subset = exports.sort = exports.select = exports.replaceList = exports.nothing = exports.member = exports.keywords = exports.isNotMember = exports.isMember = exports.implode = exports.explode = exports.elements = exports._notes = void 0;
const tslib_1 = require("tslib");
/**
* @file Lists
* @module lists
* @category Lists
*/
const common_1 = require("../utils/common");
const notesf = tslib_1.__importStar(require("../notes/lists"));
exports._notes = notesf;
const openf_lr = tslib_1.__importStar(require("../openformula/lookup-reference"));
const API = tslib_1.__importStar(require("../rosetta/API"));
//-----------------------------
// Open Formula lists
//-----------------------------
// Notes @functions lists
/**
* 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.
* @param {string[]|number[]|Date[]} items Text list, number list, or time-date list
* @returns The number of items in the list.
* @example rosetta.elements(["item1", "item2"]); // Returns 2
*/
function elements(items) {
return notesf.Elements(items);
}
exports.elements = elements;
/**
* 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.
* @param {TextOrTextList|DateRangeOrDateRangeList} stringOrDateRange 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"} ).
* @param {string} [separators] 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.
* @param {boolean} [includeEmpties] 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.
* @param {boolean} [newlineAsSeparator] Specify True (1) to treat the newline as a separator. Specify False (0) to not
* treat the newline as a separator. Defaults to True.
* @returns {string[]} A list containing each element found in string, or each date found in dateRange.
* @example
* rosetta.explode("a,b,c"); // Returns ["a","b","c"]
* @example
* 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"]
*/
function explode(stringOrDateRange, separators = " ,;", includeEmpties = false, newlineAsSeparator = true) {
return notesf.Explode(stringOrDateRange, separators, includeEmpties, newlineAsSeparator);
}
exports.explode = explode;
/**
* Concatenates all members of a text list and returns a text string.
* @param {TextOrTextList} textlistValue 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.
* @param {string} separator Used to separate the values in the concatenated string. If you don't specify a _separator_,
* a space is used.
* @returns {string} String containing each member of textListValue, separated by separator.
* @example
* rosetta.implode("Minneapolis":"Detroit":"Chicago"); // Returns "Minneapolis Detroit Chicago"
* @example
* rosetta.implode("Minneapolis":"Detroit":"Chicago";","); // Returns "Minneapolis,Detroit,Chicago"
*/
function implode(textlistValue, separator = " ") {
return notesf.Implode(textlistValue, separator);
}
exports.implode = implode;
/**
* Indicates if a piece of text (or a text list) is contained within another text list. The function is case-sensitive.
* @param {TextOrTextList} textValue The text or text list used to check if it is contained in another text list.
* @param {string} textListValue The text list to check if it contains the text or text list.
* @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_.
* @example
* rosetta.isMember("computer", ["printer", "computer", "monitor"]); // This example returns true
* @example
* rosetta.isMember(["computer", "Notes"], ["Notes", "printer", "monitor"]); // This example returns false
*/
function isMember(textValue, textListValue) {
return notesf.IsMember(textValue, textListValue);
}
exports.isMember = isMember;
/**
* Indicates if a text string (or a text list) is not contained within another text list. The function is case-sensitive.
* @param {TextOrTextList} textValue The text or text list used to check if it is not contained in another text list.
* @param {string} textListValue The text list to check if it does not contain the text or text list.
* @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_.
* @example
* rosetta.isNotMember("keyboard", ["printer", "computer", "monitor"]); // This example returns 1
* @example
* rosetta.isNotMember("computer", ["printer", "computer", "monitor"]); // This example returns 0
*/
function isNotMember(textValue, textListValue) {
return notesf.IsNotMember(textValue, textListValue);
}
exports.isNotMember = isNotMember;
/**
* 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).
*
* @param {string[]} textList1 A list of items.
* @param {string[]} textList2 A list of items that you want to compare to _textList1_.
* @param {string} separator 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.
* @returns {string[]} 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_.
* @example
* // 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");
* @example
* // 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");
* @example
* // 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";", ");
*/
function keywords(textList1, textList2, separator = "?. ,!;:[](){}\"<>") {
return notesf.Keywords(textList1, textList2, separator);
}
exports.keywords = keywords;
/**
* Given a value, finds its position in a text list.
* @param {string} value The value you want to find in _stringlist_.
* @param {string[]} stringlist The text list to search.
* @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.
* @example
* rosetta.member("Sales", ["Finance", "Sales", "Service", "Legal"]); // This example returns 2
* @example
* rosetta.member("Sales", ["Finance":"Service":"Legal"]); // This example returns 0
*/
function member(value, stringlist) {
return notesf.Member(value, stringlist);
}
exports.member = member;
/**
* Use with a transform function. Returns no list element (reducing the return list by one element). Not valid in any other context.
* @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(); });
*/
function nothing() {
return notesf.Nothing();
}
exports.nothing = nothing;
/**
* Performs a find-and-replace operation on a text list.
*
* @param {string[]} sourcelist The list whose values you want to scan.
* @param {string[]} fromlist A list containing the values that you want to replace.
* @param {string[]} tolist A list containing the replacement values.
* @returns {string[]} 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.
* @example
* rosetta.replaceList(["Red","Orange","Yellow","Green"], ["Orange","Blue"], ["Black","Brown"]); // Returns ["Red","Black","Yellow","Green"]
*/
function replaceList(sourcelist, fromlist, tolist) {
// Note: function has a different name than Notes formula implementation because Open Formula also contains a replace formula.
return notesf.Replace(sourcelist, fromlist, tolist);
}
exports.replaceList = replaceList;
/**
* 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.
* @param {number} position The position of the value you want to retrieve.
* @param {NumberOrNumberList|TextOrTextList|DateOrDateList} values 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.
* @returns The value that appears in the number position.
* @example
* rosetta.select(2,1,2,3); // Returns 2
* @example
* // Returns [Apr,May,Jun]
* rosetta.select(2, ["Jan","Feb","Mar"], ["Apr","May","Jun"], ["Jul","August","Sep"], ["Oct","Nov","Dec"]);
*/
function select(position, ...values) {
return notesf.Select(position, ...values);
}
exports.select = select;
/**
* 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.
*
*
* @param {string[]|number[]|Date[]} list The values to be sorted. Any alternate data types are returned unchanged.
* @param {string|string[]} [order] 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:
* <pre>["ASCENDING", "CASESENSITIVE", "ACCENTSENSITIVE", "PITCHSENSITIVE"]</pre>
* 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.
* @param {any} [customSortExpression] 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.
* @returns Text, number, or time-date list. The sorted values.
* @example
* // Returns ["Albany", "New Boston", "new york", "San Francisco"]
* rosetta.sort(["New Boston", "San Francisco", "Albany", "new york"]);
* @example
* // Returns ["San Francisco", "New Boston", "new york", "Albany"]
* rosetta.sort(["New Boston", "San Francisco", "Albany", "new york"], "DESCENDING");
* @example
* // 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;});
*/
function sort(list, order = [common_1.SortOptions.ASCENDING, common_1.SortOptions.CASESENSITIVE, common_1.SortOptions.ACCENTSENSITIVE, common_1.SortOptions.PITCHSENSITIVE], customSortExpression) {
return notesf.Sort(list, order, customSortExpression);
}
exports.sort = sort;
/**
* 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.
* @param {string[]|number[]|Date[]} list Text list, number list, time-date list, or time-date range list. The list whose subset you want.
* @param {number} numReturned The number of values from list that you want. Specifying zero (0) returns the error, "The second argument to @Subset must not be zero."
* @returns Text list, number list, or time-date list.The list, containing the number of values you specified.
* @example
* rosetta.subset(["New Orleans","London","Frankfurt","Tokyo"], 2); // Returns [New Orleans, London]
* @example
* rosetta.subset(["New Orleans", "London", "Frankfurt", "Tokyo"], -3); // Returns [London, Frankfurt, Tokyo]
*
*/
function subset(list, numReturned) {
return notesf.Subset(list, numReturned);
}
exports.subset = subset;
/**
* Function called for each item in an input list for the {@link module:lists~transform transform} function.
* @callback transformFunction
* @param {string|number|Date} s The item being processed.
* @returns {string|number|Date|null} The item to be added to the list. null indicates no item added.
*/
/**
* Applies a function to each element of a list and returns the results in a list.
* @param {TextOrTextList|NumberOrNumberList|DateOrDateList} list The list to be acted upon.
* @param {string} variableName The name of a variable passed to the function. This variable is not used.
* @param {transformFunction} aFunction 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.
* @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.
* @example
* // 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)); });
* @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 null; });
*/
function transform(list, variableName, aFunction) {
return notesf.Transform(list, variableName, aFunction);
}
exports.transform = transform;
/**
* 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.
* @param {string[]} values - list of values
* @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 {@link https://support.microsoft.com/en-us/office/unique-function-c5ab87fd-30a3-4ce9-9d1a-40204fb85e1e | microsoft.com}
* @example
* rosetta.unique(["red", "green", "blue", "green", "red"]); // Returns ["red", "green", "blue"]
* @example
* rosetta.unique("red", "green", "blue", "Green", "red"); // Returns ["red", "green", "blue", "Green"]
*/
function unique(...values) {
let input = values;
if (API.isCurrentAPINotes()) {
if (values.length === 1) {
if (Array.isArray(values[0])) {
input = values[0]; // Notes will pass in multiple values as an array
}
}
else if (values.length === 0) {
input = undefined; // not parameter specified (spread operator will turn this into array with empty string)
}
return notesf.Unique(input);
}
else {
if (values.length === 1 && Array.isArray(values[0]) && values[0].length > 0) {
input = values[0]; // Values passed in as array (Notes style), only use first value so spread operator works
}
return openf_lr.UNIQUE(...input);
}
}
exports.unique = unique;
//-----------------------------
// Notes @Commands lists
//# sourceMappingURL=lists.js.map