From f45518d36fdef41dd155f06f97b9fa10259a193f Mon Sep 17 00:00:00 2001 From: Nick McIntyre Date: Mon, 13 May 2024 08:09:18 -0500 Subject: [PATCH] Update string references --- src/utilities/string_functions.js | 888 ++++++++++++++++++++++-------- 1 file changed, 668 insertions(+), 220 deletions(-) diff --git a/src/utilities/string_functions.js b/src/utilities/string_functions.js index 97285c88e6..5687d4b96b 100644 --- a/src/utilities/string_functions.js +++ b/src/utilities/string_functions.js @@ -13,23 +13,42 @@ import '../core/friendly_errors/fes_core'; //return p5; //LM is this a mistake? /** - * Combines an array of Strings into one String, each separated by the - * character(s) used for the separator parameter. To join arrays of ints or - * floats, it's necessary to first convert them to Strings using nf() or - * nfs(). + * Combines an array of strings into one string. + * + * The first parameter, `list`, is the array of strings to join. + * + * The second parameter, `separator`, is the character(s) that should be used + * to separate the combined strings. For example, calling + * `join(myWords, ' : ')` would return a string of words each separated by a + * colon and spaces. * * @method join - * @param {Array} list array of Strings to be joined - * @param {String} separator String to be placed between each item - * @return {String} joined String + * @param {Array} list array of strings to combine. + * @param {String} separator character(s) to place between strings when they're combined. + * @return {String} combined string. + * * @example *
* - * let array = ['Hello', 'world!']; - * let separator = ' '; - * let message = join(array, separator); - * text(message, 5, 50); - * describe('“Hello world!” displayed middle left of canvas.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create an array of strings. + * let myWords = ['one', 'two', 'three']; + * + * // Create a combined string + * let combined = join(myWords, ' : '); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * + * // Display the combined string. + * text(combined, 50, 50); + * + * describe('The text "one : two : three" written in black on a gray canvas.'); + * } * *
*/ @@ -39,35 +58,56 @@ p5.prototype.join = function(list, separator) { }; /** - * This function is used to apply a regular expression to a piece of text, - * and return matching groups (elements found inside parentheses) as a - * String array. If there are no matches, a null value will be returned. - * If no groups are specified in the regular expression, but the sequence - * matches, an array of length 1 (with the matched text as the first element - * of the array) will be returned. - * - * To use the function, first check to see if the result is null. If the - * result is null, then the sequence did not match at all. If the sequence - * did match, an array is returned. - * - * If there are groups (specified by sets of parentheses) in the regular - * expression, then the contents of each will be returned in the array. - * Element [0] of a regular expression match returns the entire matching - * string, and the match groups start at element [1] (the first group is [1], - * the second [2], and so on). + * Applies a regular expression to a string and returns an array with the + * first match. + * + * `match()` uses regular expressions (regex) to match patterns in text. For + * example, the regex `abc` can be used to search a string for the exact + * sequence of characters `abc`. See + * MDN. + * for more information about regexes. + * + * The first parameter, `str`, is the string to search. + * + * The second parameter, `regex`, is a string with the regular expression to + * apply. For example, calling `match('Hello, p5*js!', '[a-z][0-9]')` would + * return the array `['p5']`. + * + * Note: If no matches are found, `null` is returned. * * @method match - * @param {String} str the String to be searched - * @param {String} regexp the regexp to be used for matching - * @return {String[]} Array of Strings found + * @param {String} str string to search. + * @param {String} regexp regular expression to match. + * @return {String[]} match if found. + * * @example *
* - * let string = 'Hello p5js*!'; - * let regexp = 'p5js\\*'; - * let m = match(string, regexp); - * text(m, 5, 50); - * describe('“p5js*” displayed middle left of canvas.'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'Hello, p5*js!'; + * + * // Match the characters that are lowercase + * // letters followed by digits. + * let matches = match(string, '[a-z][0-9]'); + * + * // Print the matches array to the console: + * // ['p5'] + * print(matches); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(16); + * + * // Display the matches. + * text(matches, 50, 50); + * + * describe('The text "p5" written in black on a gray canvas.'); + * } * *
*/ @@ -77,34 +117,67 @@ p5.prototype.match = function(str, reg) { }; /** - * This function is used to apply a regular expression to a piece of text, - * and return a list of matching groups (elements found inside parentheses) - * as a two-dimensional String array. If there are no matches, a null value - * will be returned. If no groups are specified in the regular expression, - * but the sequence matches, a two dimensional array is still returned, but - * the second dimension is only of length one. - * - * To use the function, first check to see if the result is null. If the - * result is null, then the sequence did not match at all. If the sequence - * did match, a 2D array is returned. - * - * If there are groups (specified by sets of parentheses) in the regular - * expression, then the contents of each will be returned in the array. - * Assuming a loop with counter variable i, element [i][0] of a regular - * expression match returns the entire matching string, and the match groups - * start at element [i][1] (the first group is [i][1], the second [i][2], - * and so on). + * Applies a regular expression to a string and returns an array of matches. + * + * `match()` uses regular expressions (regex) to match patterns in text. For + * example, the regex `abc` can be used to search a string for the exact + * sequence of characters `abc`. See + * MDN. + * for more information about regexes. `matchAll()` is different from + * match() because it returns every match, not just + * the first. + * + * The first parameter, `str`, is the string to search. + * + * The second parameter, `regex`, is a string with the regular expression to + * apply. For example, calling + * `matchAll('p5*js is easier than abc123', '[a-z][0-9]')` would return the + * 2D array `[['p5'], ['c1']]`. + * + * Note: If no matches are found, an empty array `[]` is returned. * * @method matchAll - * @param {String} str the String to be searched - * @param {String} regexp the regexp to be used for matching - * @return {String[]} 2d Array of Strings found + * @param {String} str string to search. + * @param {String} regexp regular expression to match. + * @return {String[]} matches found. + * * @example - *
+ *
* - * let string = 'Hello p5js*! Hello world!'; - * let regexp = 'Hello'; - * matchAll(string, regexp); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'p5*js is easier than abc123'; + * + * // Match the character sequences that are + * // lowercase letters followed by digits. + * let matches = matchAll(string, '[a-z][0-9]'); + * + * // Print the matches array to the console: + * // [['p5'], ['c1']] + * print(matches); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(16); + * + * // Iterate over the matches array. + * for (let i = 0; i < matches.length; i += 1) { + * + * // Calculate the y-coordainate. + * let y = (i + 1) * 33; + * + * // Display the match. + * text(matches[i], 50, y); + * } + * + * describe( + * 'The text "p5" and "c1" written on separate lines. The text is black on a gray background.' + * ); + * } * *
*/ @@ -124,56 +197,82 @@ p5.prototype.matchAll = function(str, reg) { }; /** - * Utility function for formatting numbers into strings. There are two - * versions: one for formatting floats, and one for formatting ints. - * - * The values for the digits, left, and right parameters should always - * be positive integers. - * - * (NOTE): Be cautious when using left and right parameters as it prepends numbers of 0's if the parameter - * if greater than the current length of the number. - * - * For example if number is 123.2 and left parameter passed is 4 which is greater than length of 123 - * (integer part) i.e 3 than result will be 0123.2. Same case for right parameter i.e. if right is 3 than - * the result will be 123.200. + * Converts a `Number` into a `String` with a given number of digits. + * + * `nf()` converts numbers such as `123.45` into strings formatted with a set + * number of digits, as in `'123.4500'`. + * + * The first parameter, `num`, is the number to convert to a string. For + * example, calling `nf(123.45)` returns the string `'123.45'`. If an array of + * numbers is passed, as in `nf([123.45, 67.89])`, an array of formatted + * strings will be returned. + * + * The second parameter, `left`, is optional. If a number is passed, as in + * `nf(123.45, 4)`, it sets the minimum number of digits to include to the + * left of the decimal place. If `left` is larger than the number of digits in + * `num`, then unused digits will be set to 0. For example, calling + * `nf(123.45, 4)` returns the string `'0123.45'`. + * + * The third parameter, `right`, is also optional. If a number is passed, as + * in `nf(123.45, 4, 1)`, it sets the minimum number of digits to include to + * the right of the decimal place. If `right` is smaller than the number of + * decimal places in `num`, then `num` will be rounded to the given number of + * decimal places. For example, calling `nf(123.45, 4, 1)` returns the string + * `'0123.5'`. If right is larger than the number of decimal places in `num`, + * then unused decimal places will be set to 0. For example, calling + * `nf(123.45, 4, 3)` returns the string `'0123.450'`. * * @method nf - * @param {Number|String} num the Number to format - * @param {Integer|String} [left] number of digits to the left of the - * decimal point - * @param {Integer|String} [right] number of digits to the right of the - * decimal point - * @return {String} formatted String + * @param {Number|String} num number to format. + * @param {Integer|String} [left] number of digits to include to the left of + * the decimal point. + * @param {Integer|String} [right] number of digits to include to the right + * of the decimal point. + * @return {String} formatted string. * * @example *
* * function setup() { + * createCanvas(100, 100); + * * background(200); - * let num1 = 321; - * let num2 = -1321; * - * noStroke(); - * fill(0); + * // Style the text. + * textAlign(LEFT, CENTER); * textSize(16); * - * text(nf(num1, 4, 2), 10, 30); - * text(nf(num2, 4, 2), 10, 80); - * // Draw dividing line - * stroke(120); - * line(0, 50, width, 50); + * // Create a number variable. + * let number = 123.45; + * + * // Display the number as a string. + * let formatted = nf(number); + * text(formatted, 20, 25); * - * describe('“0321.00” middle top, “-1321.00” middle bottom canvas'); + * // Display the number with four digits + * // to the left of the decimal. + * let left = nf(number, 4); + * text(left, 20, 50); + * + * // Display the number with four digits + * // to the left of the decimal and one + * // to the right. + * let right = nf(number, 4, 1); + * text(right, 20, 75); + * + * describe( + * 'The numbers "123.45", "0123.45", and "0123.5" written on three separate lines. The text is in black on a gray background.' + * ); * } * *
*/ /** * @method nf - * @param {Array} nums the Numbers to format - * @param {Integer|String} [left] - * @param {Integer|String} [right] - * @return {String[]} formatted Strings + * @param {Number[]} nums numbers to format. + * @param {Integer|String} [left] + * @param {Integer|String} [right] + * @return {String[]} formatted strings. */ p5.prototype.nf = function(nums, left, right) { p5._validateParameters('nf', arguments); @@ -214,47 +313,99 @@ function doNf(num, left, right) { } /** - * Utility function for formatting numbers into strings and placing - * appropriate commas to mark units of 1000. There are two versions: one - * for formatting ints, and one for formatting an array of ints. The value - * for the right parameter should always be a positive integer. + * Converts a `Number` into a `String` with commas to mark units of 1,000. + * + * `nfc()` converts numbers such as 12345 into strings formatted with commas + * to mark the thousands place, as in `'12,345'`. + * + * The first parameter, `num`, is the number to convert to a string. For + * example, calling `nfc(12345)` returns the string `'12,345'`. + * + * The second parameter, `right`, is optional. If a number is passed, as in + * `nfc(12345, 1)`, it sets the minimum number of digits to include to the + * right of the decimal place. If `right` is smaller than the number of + * decimal places in `num`, then `num` will be rounded to the given number of + * decimal places. For example, calling `nfc(12345.67, 1)` returns the string + * `'12,345.7'`. If `right` is larger than the number of decimal places in + * `num`, then unused decimal places will be set to 0. For example, calling + * `nfc(12345.67, 3)` returns the string `'12,345.670'`. * * @method nfc - * @param {Number|String} num the Number to format - * @param {Integer|String} [right] number of digits to the right of the - * decimal point - * @return {String} formatted String + * @param {Number|String} num number to format. + * @param {Integer|String} [right] number of digits to include to the right + * of the decimal point. + * @return {String} formatted string. * * @example *
* * function setup() { + * createCanvas(100, 100); + * * background(200); - * let num = 11253106.115; - * let numArr = [1, 1, 2]; * - * noStroke(); - * fill(0); - * textSize(12); + * // Style the text. + * textAlign(LEFT, CENTER); + * textSize(16); + * + * // Create a number variable. + * let number = 12345; + * + * // Display the number as a string. + * let commas = nfc(number); + * text(commas, 15, 33); + * + * // Display the number with four digits + * // to the left of the decimal. + * let decimals = nfc(number, 2); + * text(decimals, 15, 67); + * + * describe( + * 'The numbers "12,345" and "12,345.00" written on separate lines. The text is in black on a gray background.' + * ); + * } + * + *
* - * // Draw formatted numbers - * text(nfc(num, 4), 10, 30); - * text(nfc(numArr, 2), 10, 80); + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); * - * // Draw dividing line - * stroke(120); - * line(0, 50, width, 50); + * // Create an array of numbers. + * let numbers = [12345, 6789]; * - * describe('“11,253,106.115” top middle and “1.00,1.00,2.00” displayed bottom mid'); + * // Convert the numbers to formatted strings. + * let formatted = nfc(numbers); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(14); + * + * // Iterate over the array. + * for (let i = 0; i < formatted.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 33; + * + * // Display the original and formatted numbers. + * text(`${numbers[i]} : ${formatted[i]}`, 50, y); + * } + * + * describe( + * 'The text "12345 : 12,345" and "6789 : 6,789" written on two separate lines. The text is in black on a gray background.' + * ); * } * *
*/ /** * @method nfc - * @param {Array} nums the Numbers to format - * @param {Integer|String} [right] - * @return {String[]} formatted Strings + * @param {Number[]} nums numbers to format. + * @param {Integer|String} [right] + * @return {String[]} formatted strings. */ p5.prototype.nfc = function(num, right) { p5._validateParameters('nfc', arguments); @@ -287,51 +438,116 @@ function doNfc(num, right) { } /** - * Utility function for formatting numbers into strings. Similar to nf() but - * puts a "+" in front of positive numbers and a "-" in front of negative - * numbers. There are two versions: one for formatting floats, and one for - * formatting ints. The values for left, and right parameters - * should always be positive integers. + * Converts a `Number` into a `String` with a plus or minus sign. + * + * `nfp()` converts numbers such as 123 into strings formatted with a `+` or + * `-` symbol to mark whether they're positive or negative, as in `'+123'`. + * + * The first parameter, `num`, is the number to convert to a string. For + * example, calling `nfp(123.45)` returns the string `'+123.45'`. If an array + * of numbers is passed, as in `nfp([123.45, -6.78])`, an array of formatted + * strings will be returned. + * + * The second parameter, `left`, is optional. If a number is passed, as in + * `nfp(123.45, 4)`, it sets the minimum number of digits to include to the + * left of the decimal place. If `left` is larger than the number of digits in + * `num`, then unused digits will be set to 0. For example, calling + * `nfp(123.45, 4)` returns the string `'+0123.45'`. + * + * The third parameter, `right`, is also optional. If a number is passed, as + * in `nfp(123.45, 4, 1)`, it sets the minimum number of digits to include to + * the right of the decimal place. If `right` is smaller than the number of + * decimal places in `num`, then `num` will be rounded to the given number of + * decimal places. For example, calling `nfp(123.45, 4, 1)` returns the + * string `'+0123.5'`. If `right` is larger than the number of decimal places + * in `num`, then unused decimal places will be set to 0. For example, + * calling `nfp(123.45, 4, 3)` returns the string `'+0123.450'`. * * @method nfp - * @param {Number} num the Number to format - * @param {Integer} [left] number of digits to the left of the decimal - * point - * @param {Integer} [right] number of digits to the right of the - * decimal point - * @return {String} formatted String + * @param {Number} num number to format. + * @param {Integer} [left] number of digits to include to the left of the + * decimal point. + * @param {Integer} [right] number of digits to include to the right of the + * decimal point. + * @return {String} formatted string. * * @example *
* * function setup() { + * createCanvas(100, 100); + * * background(200); - * let num1 = 11253106.115; - * let num2 = -11253106.115; * - * noStroke(); - * fill(0); - * textSize(12); + * // Create number variables. + * let positive = 123; + * let negative = -123; + * + * // Convert the positive number to a formatted string. + * let p = nfp(positive); * - * // Draw formatted numbers - * text(nfp(num1, 4, 2), 10, 30); - * text(nfp(num2, 4, 2), 10, 80); + * // Convert the negative number to a formatted string + * // with four digits to the left of the decimal + * // and two digits to the right of the decimal. + * let n = nfp(negative, 4, 2); * - * // Draw dividing line - * stroke(120); - * line(0, 50, width, 50); + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(14); * - * describe('“+11253106.11” top middle and “-11253106.11” displayed bottom middle'); + * // Display the original and formatted numbers. + * text(`${positive} : ${p}`, 50, 33); + * text(`${negative} : ${n}`, 50, 67); + * + * describe( + * 'The text "123 : +123" and "-123 : -123.00" written on separate lines. The text is in black on a gray background.' + * ); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create number variables. + * let numbers = [123, -4.56]; + * + * // Convert the numbers to formatted strings + * // with four digits to the left of the decimal + * // and one digit to the right of the decimal. + * let formatted = nfp(numbers, 4, 1); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(14); + * + * // Iterate over the array. + * for (let i = 0; i < formatted.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 33; + * + * // Display the original and formatted numbers. + * text(`${numbers[i]} : ${formatted[i]}`, 50, y); + * } + * + * describe( + * 'The text "123 : +0123.0" and "-4.56 : 00-4.6" written on separate lines. The text is in black on a gray background.' + * ); * } * *
*/ /** * @method nfp - * @param {Number[]} nums the Numbers to format - * @param {Integer} [left] - * @param {Integer} [right] - * @return {String[]} formatted Strings + * @param {Number[]} nums numbers to format. + * @param {Integer} [left] + * @param {Integer} [right] + * @return {String[]} formatted strings. */ p5.prototype.nfp = function(...args) { p5._validateParameters('nfp', args); @@ -348,67 +564,107 @@ function addNfp(num) { } /** - * Utility function for formatting numbers into strings. Similar to nf() but - * puts an additional "_" (space) in front of positive numbers just in case to align it with negative - * numbers which includes "-" (minus) sign. + * Converts a positive `Number` into a `String` with an extra space in front. + * + * `nfs()` converts positive numbers such as 123.45 into strings formatted + * with an extra space in front, as in ' 123.45'. Doing so can be helpful for + * aligning positive and negative numbers. + * + * The first parameter, `num`, is the number to convert to a string. For + * example, calling `nfs(123.45)` returns the string `' 123.45'`. + * + * The second parameter, `left`, is optional. If a number is passed, as in + * `nfs(123.45, 4)`, it sets the minimum number of digits to include to the + * left of the decimal place. If `left` is larger than the number of digits in + * `num`, then unused digits will be set to 0. For example, calling + * `nfs(123.45, 4)` returns the string `' 0123.45'`. + * + * The third parameter, `right`, is also optional. If a number is passed, as + * in `nfs(123.45, 4, 1)`, it sets the minimum number of digits to include to + * the right of the decimal place. If `right` is smaller than the number of + * decimal places in `num`, then `num` will be rounded to the given number of + * decimal places. For example, calling `nfs(123.45, 4, 1)` returns the + * string `' 0123.5'`. If `right` is larger than the number of decimal places + * in `num`, then unused decimal places will be set to 0. For example, + * calling `nfs(123.45, 4, 3)` returns the string `' 0123.450'`. * - * The main usecase of nfs() can be seen when one wants to align the digits (place values) of a non-negative - * number with some negative number (See the example to get a clear picture). - * There are two versions: one for formatting float, and one for formatting int. + * @method nfs + * @param {Number} num number to format. + * @param {Integer} [left] number of digits to include to the left of the + * decimal point. + * @param {Integer} [right] number of digits to include to the right of the + * decimal point. + * @return {String} formatted string. * - * The values for the digits, left, and right parameters should always be positive integers. + * @example + *
+ * + * function setup() { + * createCanvas(100, 100); * - * (IMP): The result on the canvas basically the expected alignment can vary based on the typeface you are using. + * background(200); * - * (NOTE): Be cautious when using left and right parameters as it prepends numbers of 0's if the parameter - * if greater than the current length of the number. + * // Create number variables. + * let positive = 123; + * let negative = -123; * - * For example if number is 123.2 and left parameter passed is 4 which is greater than length of 123 - * (integer part) i.e 3 than result will be 0123.2. Same case for right parameter i.e. if right is 3 than - * the result will be 123.200. + * // Convert the positive number to a formatted string. + * let formatted = nfs(positive); * - * @method nfs - * @param {Number} num the Number to format - * @param {Integer} [left] number of digits to the left of the decimal - * point - * @param {Integer} [right] number of digits to the right of the - * decimal point - * @return {String} formatted String + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(16); + * + * // Display the negative number and the formatted positive number. + * text(negative, 50, 33); + * text(formatted, 50, 67); + * + * describe( + * 'The numbers -123 and 123 written on separate lines. The numbers align vertically. The text is in black on a gray background.' + * ); + * } + * + *
* - * @example *
* * function setup() { + * createCanvas(100, 100); + * * background(200); - * let num1 = 321; - * let num2 = -1321; * - * noStroke(); - * fill(0); + * // Create a number variable. + * let number = 123.45; + * + * // Convert the positive number to a formatted string. + * // Use four digits to the left of the decimal and + * // one digit to the right. + * let formatted = nfs(number, 4, 1); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); * textSize(16); * - * // nfs() aligns num1 (positive number) with num2 (negative number) by - * // adding a blank space in front of the num1 (positive number) - * // [left = 4] in num1 add one 0 in front, to align the digits with num2 - * // [right = 2] in num1 and num2 adds two 0's after both numbers - * // To see the differences check the example of nf() too. - * text(nfs(num1, 4, 2), 10, 30); - * text(nfs(num2, 4, 2), 10, 80); - * // Draw dividing line - * stroke(120); - * line(0, 50, width, 50); - * - * describe('“0321.00” top middle and “-1321.00” displayed bottom middle'); + * // Display a negative version of the number and + * // the formatted positive version. + * text('-0123.5', 50, 33); + * text(formatted, 50, 67); + * + * describe( + * 'The numbers "-0123.5" and "0123.5" written on separate lines. The numbers align vertically. The text is in black on a gray background.' + * ); * } * *
*/ /** * @method nfs - * @param {Array} nums the Numbers to format - * @param {Integer} [left] - * @param {Integer} [right] - * @return {String[]} formatted Strings + * @param {Array} nums numbers to format. + * @param {Integer} [left] + * @param {Integer} [right] + * @return {String[]} formatted strings. */ p5.prototype.nfs = function(...args) { p5._validateParameters('nfs', args); @@ -425,28 +681,58 @@ function addNfs(num) { } /** - * The split() function maps to String.split(), it breaks a String into - * pieces using a character or string as the delimiter. The delim parameter - * specifies the character or characters that mark the boundaries between - * each piece. A String[] array is returned that contains each of the pieces. + * Splits a `String` into pieces and returns an array containing the pieces. + * + * The first parameter, `value`, is the string to split. * - * The splitTokens() function works in a similar fashion, except that it - * splits using a range of characters instead of a specific character or - * sequence. + * The second parameter, `delim`, is the character(s) that should be used to + * split the string. For example, calling + * `split('rock...paper...scissors', '...')` would return the array + * `['rock', 'paper', 'scissors']` because there are three periods `...` + * between each word. * * @method split * @param {String} value the String to be split * @param {String} delim the String used to separate the data * @return {String[]} Array of Strings + * * @example *
* - * let names = 'Pat,Xio,Alex'; - * let splitString = split(names, ','); - * text(splitString[0], 5, 30); - * text(splitString[1], 5, 50); - * text(splitString[2], 5, 70); - * describe('“Pat” top left, “Xio” mid left, and “Alex” displayed bottom left'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'rock...paper...scissors'; + * + * // Split the string at each ... + * let words = split(string, '...'); + * + * // Print the array to the console: + * // ["rock", "paper", "scissors"] + * print(words); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(16); + * + * // Iterate over the words array. + * for (let i = 0; i < words.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 25; + * + * // Display the word. + * text(words[i], 50, y); + * } + * + * describe( + * 'The words "rock", "paper", and "scissors" written on separate lines. The text is black on a gray background.' + * ); + * } * *
*/ @@ -456,27 +742,139 @@ p5.prototype.split = function(str, delim) { }; /** - * The splitTokens() function splits a String at one or many character - * delimiters or "tokens." The delim parameter specifies the character or - * characters to be used as a boundary. + * Splits a `String` into pieces and returns an array containing the pieces. + * + * `splitTokens()` is an enhanced version of + * split(). It can split a string when any characters + * from a list are detected. * - * If no delim characters are specified, any whitespace character is used to - * split. Whitespace characters include tab (\t), line feed (\n), carriage - * return (\r), form feed (\f), and space. + * The first parameter, `value`, is the string to split. + * + * The second parameter, `delim`, is optional. It sets the character(s) that + * should be used to split the string. `delim` can be a single string, as in + * `splitTokens('rock...paper...scissors...shoot', '...')`, or an array of + * strings, as in + * `splitTokens('rock;paper,scissors...shoot, [';', ',', '...'])`. By default, + * if no `delim` characters are specified, then any whitespace character is + * used to split. Whitespace characters include tab (`\t`), line feed (`\n`), + * carriage return (`\r`), form feed (`\f`), and space. * * @method splitTokens - * @param {String} value the String to be split - * @param {String} [delim] list of individual Strings that will be used as - * separators - * @return {String[]} Array of Strings + * @param {String} value string to split. + * @param {String} [delim] character(s) to use for splitting the string. + * @return {String[]} separated strings. + * * @example - *
+ *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'rock paper scissors shoot'; + * + * // Split the string at each space. + * let words = splitTokens(string); + * + * // Print the array to the console. + * print(words); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(12); + * + * // Iterate over the words array. + * for (let i = 0; i < words.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 20; + * + * // Display the word. + * text(words[i], 50, y); + * } + * + * describe( + * 'The words "rock", "paper", "scissors", and "shoot" written on separate lines. The text is black on a gray background.' + * ); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'rock...paper...scissors...shoot'; + * + * // Split the string at each ... + * let words = splitTokens(string, '...'); + * + * // Print the array to the console. + * print(words); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(12); + * + * // Iterate over the words array. + * for (let i = 0; i < words.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 20; + * + * // Display the word. + * text(words[i], 50, y); + * } + * + * describe( + * 'The words "rock", "paper", "scissors", and "shoot" written on separate lines. The text is black on a gray background.' + * ); + * } + * + *
+ * + *
* * function setup() { - * let myStr = 'Mango, Banana, Lime'; - * let myStrArr = splitTokens(myStr, ','); + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = 'rock;paper,scissors...shoot'; + * + * // Split the string at each semicolon, comma, or ... + * let words = splitTokens(string, [';', ',', '...']); + * + * // Print the array to the console. + * print(words); * - * print(myStrArr); // prints : ["Mango"," Banana"," Lime"] + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(12); + * + * // Iterate over the words array. + * for (let i = 0; i < words.length; i += 1) { + * + * // Calculate the y-coordinate. + * let y = (i + 1) * 20; + * + * // Display the word. + * text(words[i], 50, y); + * } + * + * describe( + * 'The words "rock", "paper", "scissors", and "shoot" written on separate lines. The text is black on a gray background.' + * ); * } * *
@@ -509,27 +907,77 @@ p5.prototype.splitTokens = function(value, delims) { }; /** - * Removes whitespace characters from the beginning and end of a String. In - * addition to standard whitespace characters such as space, carriage return, - * and tab, this function also removes the Unicode "nbsp" character. + * Removes whitespace from the start and end of a `String` without changing the middle. + * + * `trim()` trims + * whitespace characters + * such as spaces, carriage returns, tabs, Unicode "nbsp" character. + * + * The parameter, `str`, is the string to trim. If a single string is passed, + * as in `trim(' pad ')`, a single string is returned. If an array of + * strings is passed, as in `trim([' pad ', '\n space \n'])`, an array of + * strings is returned. * * @method trim - * @param {String} str a String to be trimmed - * @return {String} a trimmed String + * @param {String} str string to trim. + * @return {String} trimmed string. * * @example *
* - * let string = trim(' No new lines\n '); - * text(string + ' here', 2, 50); - * describe('“No new lines here” displayed center canvas'); + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create a string variable. + * let string = ' p5*js '; + * + * // Trim the whitespace. + * let trimmed = trim(string); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textSize(16); + * + * // Display the text. + * text(`Hello, ${trimmed}!`, 50, 50); + * + * describe('The text "Hello, p5*js!" written in black on a gray background.'); + * } + * + *
+ * + *
+ * + * function setup() { + * createCanvas(100, 100); + * + * background(200); + * + * // Create an array of strings. + * let strings = [' wide ', '\n open ', '\n spaces ']; + * + * // Trim the whitespace. + * let trimmed = trim(strings); + * + * // Style the text. + * textAlign(CENTER, CENTER); + * textFont('Courier New'); + * textSize(10); + * + * // Display the text. + * text(`${trimmed[0]} ${trimmed[1]} ${trimmed[2]}`, 50, 50); + * + * describe('The text "wide open spaces" written in black on a gray background.'); + * } * *
*/ /** * @method trim - * @param {Array} strs an Array of Strings to be trimmed - * @return {String[]} an Array of trimmed Strings + * @param {String[]} strs strings to trim. + * @return {String[]} trimmed strings. */ p5.prototype.trim = function(str) { p5._validateParameters('trim', arguments);