Methods
# charAt(index) → {IString}
Same as String.charAt()
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
the index of the character being sought |
the character at the given index
# 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.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
the index of the character being sought |
the character code of the character at the given index in the string
number
# 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.
an iterator that iterates through all the characters in the string
Object
# 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.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
index of the code point |
code point of the character at the given index into the string
number
# 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.
the number of code points in this string
number
# concat(strings) → {IString}
Same as String.concat()
Parameters:
| Name | Type | Description |
|---|---|---|
strings |
string
|
strings to concatenate to the current one |
a concatenation of the given strings
# endsWith() → {boolean}
Same as String.endsWith().
true if the given characters are found at the end of the string, and false otherwise
boolean
# 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.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function
|
a callback function to call with each full character in the current string |
# 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.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function
|
a callback function to call with each code point in the current string |
# 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:
var 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:
var 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.
Parameters:
| Name | Type | Description |
|---|---|---|
params |
a Javascript object containing values for the replacement parameters in the current string |
a new IString instance with as many replacement parameters filled out as possible with real values.
# 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:
var num = 2;
var 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:
var num = 22;
var 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:
var 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.");
var 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.
Parameters:
| Name | 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
|
"syntax error in choice format pattern: " if there is a syntax error
the formatted string
string
# 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".
localespec to use when processing choice formats with this string
string
# includes() → {boolean}
Same as String.includes().
true if the search string is found anywhere with the given string, and false otherwise
boolean
# indexOf(searchValue, start) → {number}
Same as String.indexOf()
Parameters:
| Name | Type | Description |
|---|---|---|
searchValue |
string
|
string to search for |
start |
number
|
index into the string to start searching, or undefined to search the entire string |
index into the string of the string being sought, or -1 if the string is not found
number
# 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.
an iterator that iterates through all the code points in the string
Object
# lastIndexOf(searchValue, start) → {number}
Same as String.lastIndexOf()
Parameters:
| Name | Type | Description |
|---|---|---|
searchValue |
string
|
string to search for |
start |
number
|
index into the string to start searching, or undefined to search the entire string |
index into the string of the string being sought, or -1 if the string is not found
number
# match(regexp) → {Array.<string>}
Same as String.match()
Parameters:
| Name | Type | Description |
|---|---|---|
regexp |
string
|
the regular expression to match |
an array of matches
Array.<string>
# matchAll(regexp) → {iterator}
Same as String.matchAll()
Parameters:
| Name | Type | Description |
|---|---|---|
regexp |
string
|
the regular expression to match |
an iterator of the matches
iterator
# normalize() → {string}
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).
the string in normalized form
string
# padEnd() → {string}
Same as String.padEnd().
a string of the specified length with the pad string applied at the end of the current string
string
# padStart() → {string}
Same as String.padStart().
a string of the specified length with the pad string applied at the end of the current string
string
# repeat() → {string}
Same as String.repeat().
a new string containing the specified number of copies of the given string
string
# replace(searchValue, newValue) → {IString}
Same as String.replace()
Parameters:
| Name | Type | Description |
|---|---|---|
searchValue |
string
|
a regular expression to search for |
newValue |
string
|
the string to replace the matches with |
a new string with all the matches replaced with the new value
# search(regexp) → {number}
Same as String.search()
Parameters:
| Name | Type | Description |
|---|---|---|
regexp |
string
|
the regular expression to search for |
position of the match, or -1 for no match
number
# setLocale(locale, syncopt, loadParamsopt, onLoadopt)
Set 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".
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
locale |
Locale
|
string
|
locale to use when processing choice formats with this string |
|
sync |
boolean
|
<optional> |
[optional] whether to load the locale data synchronously or not |
loadParams |
Object
|
<optional> |
[optional] parameters to pass to the loader function |
onLoad |
function
|
<optional> |
[optional] function to call when the loading is done |
# slice(start, end) → {IString}
Same as String.slice()
Parameters:
| Name | Type | Description |
|---|---|---|
start |
number
|
first character to include in the string |
end |
number
|
include all characters up to, but not including the end character |
a slice of the current string
# split(separator, limit) → {Array.<string>}
Same as String.split()
Parameters:
| Name | 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. |
the parts of the current string split by the separator
Array.<string>
# startsWith() → {boolean}
Same as String.startsWith().
true if the given characters are found at the beginning of the string, and false otherwise
boolean
# substr(start, length) → {IString}
Same as String.substr()
Parameters:
| Name | 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. |
the requested substring
# substring(from, to) → {IString}
Same as String.substring()
Parameters:
| Name | 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 |
the requested substring
# toLocaleLowerCase() → {string}
Same as String.toLocaleLowerCase(). If the JS engine does not support this method, you can use the ilib CaseMapper class instead.
a new string representing the calling string converted to lower case, according to any locale-sensitive case mappings
string
# toLocaleUpperCase() → {string}
Same as String.toLocaleUpperCase(). If the JS engine does not support this method, you can use the ilib CaseMapper class instead.
a new string representing the calling string converted to upper case, according to any locale-sensitive case mappings
string
# toLowerCase() → {IString}
Same as String.toLowerCase(). Note that this method is not locale-sensitive.
a string with the first character lower-cased
# toUpperCase() → {IString}
Same as String.toUpperCase(). Note that this method is not locale-sensitive. Use toLocaleUpperCase() instead to get locale-sensitive behaviour.
a string with the first character upper-cased
# trim() → {string}
Same as String.trim().
a new string representing the calling string stripped of whitespace from both ends.
string
# trimEnd() → {string}
Same as String.trimEnd().
a new string representing the calling string stripped of whitespace from its (right) end.
string
# trimLeft() → {string}
Same as String.trimLeft().
A new string representing the calling string stripped of whitespace from its beginning (left end).
string
# trimRight() → {string}
Same as String.trimRight().
a new string representing the calling string stripped of whitespace from its (right) end.
string
# trimStart() → {string}
Same as String.trimStart().
A new string representing the calling string stripped of whitespace from its beginning (left end).
string
# static 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.
Parameters:
| Name | Type | Description |
|---|---|---|
codepoint |
number
|
UCS-4 code point to convert to a character |
a string containing the character represented by the codepoint
string
# static loadPlurals(syncopt, locale, loadParamsopt, onLoadopt)
Load the plural the definitions of plurals for the locale.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
sync |
boolean
|
<optional> |
|
locale |
Locale
|
string
|
||
loadParams |
Object
|
<optional> |
|
onLoad |
function
|
<optional> |
# static 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.
Parameters:
| Name | Type | Description |
|---|---|---|
str |
string
|
string to get the code point from |
index |
number
|
index into the string |
code point of the character at the given index into the string
number