Skip to content
This repository was archived by the owner on Jan 16, 2025. It is now read-only.

Latest commit

 

History

History
1053 lines (740 loc) · 35.2 KB

ilibIString.md

File metadata and controls

1053 lines (740 loc) · 35.2 KB

IString

Create a new ilib string instance. This string inherits from and extends the Javascript String class. It can be used almost anywhere that a normal Javascript string is used, though in some instances you will need to call the #toString method when a built-in Javascript string is needed. The formatting methods are methods that are not in the intrinsic String class and are most useful when localizing strings in an app or web site in combination with the ResBundle class.

This class is named IString ("ilib string") so as not to conflict with the built-in Javascript String class.

Kind: global class

new IString(string, [options])

Create a new ilib string instance.

The options may contain the following properties:

  • locale - the locale of this string
Param Type Description
string string | IString initialize this instance with this string
[options] options options governing the construction of this instance

iString.format(params) ⇒

Format this string instance as a message, replacing the parameters with the given values.

The string can contain any text that a regular Javascript string can contain. Replacement parameters have the syntax:

{name}

Where "name" can be any string surrounded by curly brackets. The value of "name" is taken from the parameters argument.

Example:

const str = new IString("There are {num} objects.");
console.log(str.format({
  num: 12
});

Would give the output:

There are 12 objects.

If a property is missing from the parameter block, the replacement parameter substring is left untouched in the string, and a different set of parameters may be applied a second time. This way, different parts of the code may format different parts of the message that they happen to know about.

Example:

const str = new IString("There are {num} objects in the {container}.");
console.log(str.format({
  num: 12
});

Would give the output:

There are 12 objects in the {container}.

The result can then be formatted again with a different parameter block that specifies a value for the container property.

Kind: instance method of IString
Returns: a new IString instance with as many replacement parameters filled out as possible with real values.

Param Description
params a Javascript object containing values for the replacement parameters in the current string

iString.formatChoice(argIndex, params) ⇒ string

Format a string as one of a choice of strings dependent on the value of a particular argument index or array of indices.

The syntax of the choice string is as follows. The string contains a series of choices separated by a vertical bar character "|". Each choice has a value or range of values to match followed by a hash character "#" followed by the string to use if the variable matches the criteria.

Example string:

const num = 2;
const str = new IString("0#There are no objects.|1#There is one object.|2#There are {number} objects.");
console.log(str.formatChoice(num, {
  number: num
}));

Gives the output:

"There are 2 objects."

The strings to format may contain replacement variables that will be formatted using the format() method above and the params argument as a source of values to use while formatting those variables.

If the criterion for a particular choice is empty, that choice will be used as the default one for use when none of the other choice's criteria match.

Example string:

const num = 22;
const str = new IString("0#There are no objects.|1#There is one object.|#There are {number} objects.");
console.log(str.formatChoice(num, {
  number: num
}));

Gives the output:

"There are 22 objects."

If multiple choice patterns can match a given argument index, the first one encountered in the string will be used. If no choice patterns match the argument index, then the default choice will be used. If there is no default choice defined, then this method will return an empty string.

Special Syntax

For any choice format string, all of the patterns in the string should be of a single type: numeric, boolean, or string/regexp. The type of the patterns is determined by the type of the argument index parameter.

If the argument index is numeric, then some special syntax can be used in the patterns to match numeric ranges.

  • >x - match any number that is greater than x
  • >=x - match any number that is greater than or equal to x
  • <x - match any number that is less than x
  • <=x - match any number that is less than or equal to x
  • start-end - match any number in the range [start,end)
  • zero - match any number in the class "zero". (See below for a description of number classes.)
  • one - match any number in the class "one"
  • two - match any number in the class "two"
  • few - match any number in the class "few"
  • many - match any number in the class "many"
  • other - match any number in the other or default class

A number class defines a set of numbers that receive a particular syntax in the strings. For example, in Slovenian, integers ending in the digit "1" are in the "one" class, including 1, 21, 31, ... 101, 111, etc. Similarly, integers ending in the digit "2" are in the "two" class. Integers ending in the digits "3" or "4" are in the "few" class, and every other integer is handled by the default string.

The definition of what numbers are included in a class is locale-dependent. They are defined in the data file plurals.json. If your string is in a different locale than the default for ilib, you should call the setLocale() method of the string instance before calling this method.

Other Pattern Types

If the argument index is a boolean, the string values "true" and "false" may appear as the choice patterns.

If the argument index is of type string, then the choice patterns may contain regular expressions, or static strings as degenerate regexps.

Multiple Indexes

If you have 2 or more indexes to format into a string, you can pass them as an array. When you do that, the patterns to match should be a comma-separate list of patterns as per the rules above.

Example string:

const str = new IString("zero,zero#There are no objects on zero pages.|one,one#There is 1 object on 1 page.|other,one#There are {number} objects on 1 page.|#There are {number} objects on {pages} pages.");
const num = 4, pages = 1;
console.log(str.formatChoice([num, pages], {
  number: num,
  pages: pages
}));

Gives the output:

"There are 4 objects on 1 page."

Note that when there is a single index, you would typically leave the pattern blank to indicate the default choice. When there are multiple indices, sometimes one of the patterns has to be the default case when the other is not. Rather than leaving one or more of the patterns blank with commas that look out-of-place in the middle of it, you can use the word "other" to indicate a match with the default or other choice. The above example shows the use of the "other" pattern. That said, you are allowed to leave the pattern blank if you so choose. In the example above, the pattern for the third string could easily have been written as ",one" instead of "other,one" and the result will be the same.

Kind: instance method of IString
Returns: string - the formatted string
Throws:

  • "syntax error in choice format pattern: " if there is a syntax error
Param Type Description
argIndex * | Array.<*> The index into the choice array of the current parameter, or an array of indices
params Object The hash of parameter values that replace the replacement variables in the string

iString.at(offset) ⇒ IString

Same as String.at()

Kind: instance method of IString
Returns: IString - the single UTF-16 code point located at the specified offset

Param Type Description
offset number offset into the string

iString.charAt(index) ⇒ IString

Same as String.charAt()

Kind: instance method of IString
Returns: IString - the character at the given index

Param Type Description
index number the index of the character being sought

iString.charCodeAt(index) ⇒ number

Same as String.charCodeAt(). This only reports on 2-byte UCS-2 Unicode values, and does not take into account supplementary characters encoded in UTF-16. If you would like to take account of those characters, use codePointAt() instead.

Kind: instance method of IString
Returns: number - the character code of the character at the given index in the string

Param Type Description
index number the index of the character being sought

iString.codePointAt(index) ⇒ number

Return the code point at the given index when the string is viewed as an array of code points. If the index is beyond the end of the array of code points or if the index is negative, -1 is returned.

Kind: instance method of IString
Returns: number - code point of the character at the given index into the string

Param Type Description
index number index of the code point

iString.concat(strings) ⇒ IString

Same as String.concat()

Kind: instance method of IString
Returns: IString - a concatenation of the given strings

Param Type Description
strings string strings to concatenate to the current one

iString.endsWith() ⇒ boolean

Same as String.endsWith().

Kind: instance method of IString
Returns: boolean - true if the given characters are found at the end of the string, and false otherwise

iString.includes(searchValue, start) ⇒ boolean

Same as String.includes()

Kind: instance method of IString

Param Type Description
searchValue string string to search for
start number index into the string to start searching, or undefined to search the entire string

iString.indexOf(searchValue, start) ⇒ number

Same as String.indexOf()

Kind: instance method of IString
Returns: number - index into the string of the string being sought, or -1 if the string is not found

Param Type Description
searchValue string string to search for
start number index into the string to start searching, or undefined to search the entire string

iString.lastIndexOf(searchValue, start) ⇒ number

Same as String.lastIndexOf()

Kind: instance method of IString
Returns: number - index into the string of the string being sought, or -1 if the string is not found

Param Type Description
searchValue string string to search for
start number index into the string to start searching, or undefined to search the entire string

iString.localeCompare(compareString, [locales], [options])

Same as String.localeCompare()

Kind: instance method of IString

Param Type
compareString String
[locales] String
[options] Object

iString.match(regexp) ⇒ Array.<string>

Same as String.match()

Kind: instance method of IString
Returns: Array.<string> - an array of matches

Param Type Description
regexp string the regular expression to match

iString.matchAll(regexp) ⇒ iterator

Same as String.matchAll()

Kind: instance method of IString
Returns: iterator - an iterator of the matches

Param Type Description
regexp string the regular expression to match

iString.normalize(form) ⇒ IString

Same as String.normalize(). If this JS engine does not support this method, then you can use the NormString class of ilib to the same thing (albeit a little slower).

Kind: instance method of IString
Returns: IString - the normalize version of the string

Param Type Description
form String the name of the Unicode Normalization Form

iString.padEnd() ⇒ IString

Same as String.padEnd().

Kind: instance method of IString
Returns: IString - a string of the specified length with the pad string applied at the end of the current string

iString.padStart() ⇒ IString

Same as String.padStart().

Kind: instance method of IString
Returns: IString - a string of the specified length with the pad string applied at the end of the current string

iString.repeat() ⇒ IString

Same as String.repeat().

Kind: instance method of IString
Returns: IString - a new string containing the specified number of copies of the given string

iString.replace(searchValue, newValue) ⇒ IString

Same as String.replace()

Kind: instance method of IString
Returns: IString - a new string with all the matches replaced with the new value

Param Type Description
searchValue string a regular expression to search for
newValue string the string to replace the matches with

iString.replaceAll(searchValue, newValue) ⇒ IString

Same as String.replaceAll()

Kind: instance method of IString
Returns: IString - a new string with all the matches replaced with the new value

Param Type Description
searchValue string a regular expression to search for
newValue string the string to replace the matches with

iString.search(regexp) ⇒ number

Same as String.search()

Kind: instance method of IString
Returns: number - position of the match, or -1 for no match

Param Type Description
regexp string the regular expression to search for

iString.slice(start, end) ⇒ IString

Same as String.slice()

Kind: instance method of IString
Returns: IString - a slice of the current string

Param Type Description
start number first character to include in the string
end number include all characters up to, but not including the end character

iString.split(separator, limit) ⇒ Array.<string>

Same as String.split()

Kind: instance method of IString
Returns: Array.<string> - the parts of the current string split by the separator

Param Type Description
separator string regular expression to match to find separations between the parts of the text
limit number maximum number of items in the final output array. Any items beyond that limit will be ignored.

iString.startsWith() ⇒ boolean

Same as String.startsWith().

Kind: instance method of IString
Returns: boolean - true if the given characters are found at the beginning of the string, and false otherwise

iString.substr(start, length) ⇒ IString

Same as String.substr()

Kind: instance method of IString
Returns: IString - the requested substring

Param Type Description
start number the index of the character that should begin the returned substring
length number the number of characters to return after the start character.

iString.substring(from, to) ⇒ IString

Same as String.substring()

Kind: instance method of IString
Returns: IString - the requested substring

Param Type Description
from number the index of the character that should begin the returned substring
to number the index where to stop the extraction. If omitted, extracts the rest of the string

iString.toLocaleLowerCase() ⇒ IString

Same as String.toLocaleLowerCase(). If the JS engine does not support this method, you can use the ilib CaseMapper class instead.

Kind: instance method of IString
Returns: IString - a new string representing the calling string converted to lower case, according to any locale-sensitive case mappings

iString.toLocaleUpperCase() ⇒ IString

Same as String.toLocaleUpperCase(). If the JS engine does not support this method, you can use the ilib CaseMapper class instead.

Kind: instance method of IString
Returns: IString - a new string representing the calling string converted to upper case, according to any locale-sensitive case mappings

iString.toLowerCase() ⇒ IString

Same as String.toLowerCase(). Note that this method is not locale-sensitive.

Kind: instance method of IString
Returns: IString - a string with all the characters lower-cased

iString.toString() ⇒ string

Same as String.toString()

Kind: instance method of IString
Returns: string - this instance as regular Javascript string

iString.toUpperCase() ⇒ IString

Same as String.toUpperCase(). Note that this method is not locale-sensitive. Use toLocaleUpperCase() instead to get locale-sensitive behaviour.

Kind: instance method of IString
Returns: IString - a string with all the characters upper-cased

iString.trim() ⇒ IString

Same as String.trim().

Kind: instance method of IString
Returns: IString - a new string representing the calling string stripped of whitespace from both ends.

iString.trimEnd() ⇒ IString

Same as String.trimEnd().

Kind: instance method of IString
Returns: IString - a new string representing the calling string stripped of whitespace from its (right) end.

iString.trimStart() ⇒ IString

Same as String.trimStart().

Kind: instance method of IString
Returns: IString - A new string representing the calling string stripped of whitespace from its beginning (left end).

iString.valueOf() ⇒ string

Same as String.valueOf()

Kind: instance method of IString
Returns: string - this instance as a regular Javascript string

iString.trimRight() ⇒ IString

Same as String.trimRight().

Kind: instance method of IString
Returns: IString - a new string representing the calling string stripped of whitespace from its (right) end.

iString.trimLeft() ⇒ IString

Same as String.trimLeft().

Kind: instance method of IString
Returns: IString - A new string representing the calling string stripped of whitespace from its beginning (left end).

iString.forEach(callback)

Call the callback with each character in the string one at a time, taking care to step through the surrogate pairs in the UTF-16 encoding properly.

The standard Javascript String's charAt() method only returns a particular 16-bit character in the UTF-16 encoding scheme. If the index to charAt() is pointing to a low- or high-surrogate character, it will return the surrogate character rather than the the character in the supplementary planes that the two surrogates together encode. This function will call the callback with the full character, making sure to join two surrogates into one character in the supplementary planes where necessary.

Kind: instance method of IString

Param Type Description
callback function a callback function to call with each full character in the current string

iString.forEachCodePoint(callback)

Call the callback with each numeric code point in the string one at a time, taking care to step through the surrogate pairs in the UTF-16 encoding properly.

The standard Javascript String's charCodeAt() method only returns information about a particular 16-bit character in the UTF-16 encoding scheme. If the index to charCodeAt() is pointing to a low- or high-surrogate character, it will return the code point of the surrogate character rather than the code point of the character in the supplementary planes that the two surrogates together encode. This function will call the callback with the full code point of each character, making sure to join two surrogates into one code point in the supplementary planes.

Kind: instance method of IString

Param Type Description
callback function a callback function to call with each code point in the current string

iString.iterator() ⇒ Object

Return an iterator that will step through all of the characters in the string one at a time and return their code points, taking care to step through the surrogate pairs in UTF-16 encoding properly.

The standard Javascript String's charCodeAt() method only returns information about a particular 16-bit character in the UTF-16 encoding scheme. If the index is pointing to a low- or high-surrogate character, it will return a code point of the surrogate character rather than the code point of the character in the supplementary planes that the two surrogates together encode.

The iterator instance returned has two methods, hasNext() which returns true if the iterator has more code points to iterate through, and next() which returns the next code point as a number.

Kind: instance method of IString
Returns: Object - an iterator that iterates through all the code points in the string

iString.charIterator() ⇒ Object

Return an iterator that will step through all of the characters in the string one at a time, taking care to step through the surrogate pairs in UTF-16 encoding properly.

The standard Javascript String's charAt() method only returns information about a particular 16-bit character in the UTF-16 encoding scheme. If the index is pointing to a low- or high-surrogate character, it will return that surrogate character rather than the surrogate pair which represents a character in the supplementary planes.

The iterator instance returned has two methods, hasNext() which returns true if the iterator has more characters to iterate through, and next() which returns the next character.

Kind: instance method of IString
Returns: Object - an iterator that iterates through all the characters in the string

iString.getLocale() ⇒ string

Return the locale to use when processing choice formats. The locale affects how number classes are interpretted. In some cultures, the limit "few" maps to "any integer that ends in the digits 2 to 9" and in yet others, "few" maps to "any integer that ends in the digits 3 or 4".

Kind: instance method of IString
Returns: string - localespec to use when processing choice formats with this string

iString.codePointLength() ⇒ number

Return the number of code points in this string. This may be different than the number of characters, as the UTF-16 encoding that Javascript uses for its basis returns surrogate pairs separately. Two 2-byte surrogate characters together make up one character/code point in the supplementary character planes. If your string contains no characters in the supplementary planes, this method will return the same thing as the length() method.

Kind: instance method of IString
Returns: number - the number of code points in this string

IString.create(locale, options) ⇒ Promise

Factory method to create a new instance of IString asynchronously. The parameters are the same as for the constructor, but it returns a Promise instead of the instance directly.

Kind: static method of IString
Returns: Promise - a promise to load a LocaleInfo instance. The resolved value of the promise is the new instance of LocaleInfo,

Param Type Description
locale string the locale to get the info for
options Object the same objects you would send to a constructor

IString.isSurrogate(ch) ⇒ boolean

Return true if the given character is a Unicode surrogate character, either high or low.

Kind: static method of IString
Returns: boolean - true if the character is a surrogate

Param Type Description
ch string character to check

IString.fromCodePoint(codepoint) ⇒ string

Convert a UCS-4 code point to a Javascript string. The codepoint can be any valid UCS-4 Unicode character, including supplementary characters. Standard Javascript only supports supplementary characters using the UTF-16 encoding, which has values in the range 0x0000-0xFFFF. String.fromCharCode() will only give you a string containing 16-bit characters, and will not properly convert the code point for a supplementary character (which has a value > 0xFFFF) into two UTF-16 surrogate characters. Instead, it will just just give you whatever single character happens to be the same as your code point modulo 0x10000, which is almost never what you want.

Similarly, that means if you use String.charCodeAt() you will only retrieve a 16-bit value, which may possibly be a single surrogate character that is part of a surrogate pair representing a character in the supplementary plane. It will not give you a code point. Use IString.codePointAt() to access code points in a string, or use an iterator to walk through the code points in a string.

Kind: static method of IString
Returns: string - a string containing the character represented by the codepoint

Param Type Description
codepoint number UCS-4 code point to convert to a character

IString.toCodePoint(str, index) ⇒ number

Convert the character or the surrogate pair at the given index into the intrinsic Javascript string to a Unicode UCS-4 code point.

Kind: static method of IString
Returns: number - code point of the character at the given index into the string

Param Type Description
str string string to get the code point from
index number index into the string

IString.@@Iterator()

Implement the iterator protocol over the characters in the string as a generator function. This allows an IString to be used with the for..of operator:

const s = new IString("test");
for (let ch of s) {
    console.log(ch);
}
// prints:
// t
// e
// s
// t

It can also be used with the spread operator:

const s = new IString("test");
console.log(`Chars are ${...s}`);
// prints:
// Chars are ['t','e','s','t']

This iterator properly skips over UTF-16 surrogate pairs and return the "astral plane" Unicode characters.

Kind: static method of IString