Class ilib.String

Create a new string instance. This string inherits from the Javascript String class, and adds two more methods, fmt and fmtChoice. It can be used anywhere that a normal Javascript string is used. The formatting methods are of course most useful when localizing strings in an app or web site in combination with the ilib.ResBundle class.

Depends directive: !depends strings.js
Defined in: ilib-dyn-full.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	ilib.String(string)

Method Summary
Method Attributes	Method Name and Description
	charAt(index) Same as String.charAt()
	charCodeAt(index) Same as String.charCodeAt().
	charIterator() 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.
	codePointAt(index) Return the code point at the given index when the string is viewed as an array of code points.
	codePointLength() Return the number of code points in this string.
	concat(strings) Same as String.concat()
	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.
	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.
	format(params) Format this string instance as a message, replacing the parameters with the given values.
	formatChoice(argIndex, params) Format a string as one of a choice of strings dependent on the value of a particular argument index.
<static>	ilib.String.fromCodePoint(codepoint) Convert a UCS-4 code point to a Javascript string.
	getLocale() Return the locale to use when processing choice formats.
	indexOf(searchValue, start) Same as String.indexOf()
	iterator() 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.
	lastIndexOf(searchValue, start) Same as String.lastIndexOf()
<static>	ilib.String.loadPlurals(sync, locale, loadParams, onLoad) Load the plural the definitions of plurals for the locale.
	match(regexp) Same as String.match()
	replace(searchValue, newValue) Same as String.replace()
	search(regexp) Same as String.search()
	setLocale(locale, sync, loadParams, onLoad) Set the locale to use when processing choice formats.
	slice(start, end) Same as String.slice()
	split(separator, limit) Same as String.split()
	substr(start, length) Same as String.substr()
	substring(from, to) Same as String.substring()
<static>	ilib.String.toCodePoint(str, index) Convert the character or the surrogate pair at the given index into the intrinsic Javascript string to a Unicode UCS-4 code point.
	toLowerCase() Same as String.toLowerCase().
	toString() Same as String.toString()
	toUpperCase() Same as String.toUpperCase().
	valueOf() Same as String.valueOf()

Class Detail

ilib.String(string)

Parameters:
{string|ilib.String=} string: initialize this instance with this string

Method Detail

{ilib.String} charAt(index)

Same as String.charAt()

Parameters:
{number} index: the index of the character being sought

Returns:: {ilib.String} the character at the given index

{number} charCodeAt(index)

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:
{number} index: the index of the character being sought

Returns:: {number} the character code of the character at the given index in the string

{Object} charIterator()

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.

Returns:: {Object} an iterator that iterates through all the characters in the string

{number} codePointAt(index)

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:
{number} index: index of the code point

Returns:: {number} code point of the character at the given index into the string

{number} codePointLength()

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.

Returns:: {number} the number of code points in this string

{ilib.String} concat(strings)

Same as String.concat()

Parameters:
{string} strings: strings to concatenate to the current one

Returns:: {ilib.String} a concatenation of the given strings

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:
{function(string)} callback: 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:
{function(string)} callback: 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 ilib.String("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 ilib.String("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:
params: a Javascript object containing values for the replacement parameters in the current string

Returns:: a new ilib.String instance with as many replacement parameters filled out as possible with real values.

{string} formatChoice(argIndex, params)

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

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 ilib.String("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 ilib.String("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"

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.

Parameters:
{*} argIndex: The index into the choice array of the current parameter
{Object} params: The hash of parameter values that replace the replacement variables in the string

Throws:
: "syntax error in choice format pattern: " if there is a syntax error

Returns:: {string} the formatted string

<static> {string} ilib.String.fromCodePoint(codepoint)

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 ilib.String.codePointAt() to access code points in a string, or use an iterator to walk through the code points in a string.

Parameters:
{number} codepoint: UCS-4 code point to convert to a character

Returns:: {string} a string containing the character represented by the codepoint

{string} getLocale()

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".

Returns:: {string} localespec to use when processing choice formats with this string

{number} indexOf(searchValue, start)

Same as String.indexOf()

Parameters:
{string} searchValue: string to search for
{number} start: index into the string to start searching, or undefined to search the entire string

Returns:: {number} index into the string of the string being sought, or -1 if the string is not found

{Object} iterator()

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.

Returns:: {Object} an iterator that iterates through all the code points in the string

{number} lastIndexOf(searchValue, start)

Same as String.lastIndexOf()

Parameters:
{string} searchValue: string to search for
{number} start: index into the string to start searching, or undefined to search the entire string

Returns:: {number} index into the string of the string being sought, or -1 if the string is not found

<static> ilib.String.loadPlurals(sync, locale, loadParams, onLoad)

Load the plural the definitions of plurals for the locale.

Parameters:
{boolean=} sync
{ilib.Locale|string=} locale
{Object=} loadParams
{function(*)=} onLoad

{Array.<string>} match(regexp)

Same as String.match()

Parameters:
{string} regexp: the regular expression to match

Returns:: {Array.<string>} an array of matches

{ilib.String} replace(searchValue, newValue)

Same as String.replace()

Parameters:
{string} searchValue: a regular expression to search for
{string} newValue: the string to replace the matches with

Returns:: {ilib.String} a new string with all the matches replaced with the new value

{number} search(regexp)

Same as String.search()

Parameters:
{string} regexp: the regular expression to search for

Returns:: {number} position of the match, or -1 for no match

setLocale(locale, sync, loadParams, onLoad)

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:
{ilib.Locale|string} locale: locale to use when processing choice formats with this string
{boolean=} sync: [optional] whether to load the locale data synchronously or not
{Object=} loadParams: [optional] parameters to pass to the loader function
{function(*)=} onLoad: [optional] function to call when the loading is done

{ilib.String} slice(start, end)

Same as String.slice()

Parameters:
{number} start: first character to include in the string
{number} end: include all characters up to, but not including the end character

Returns:: {ilib.String} a slice of the current string

{Array.<string>} split(separator, limit)

Same as String.split()

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

Returns:: {Array.<string>} the parts of the current string split by the separator

{ilib.String} substr(start, length)

Same as String.substr()

Parameters:
{number} start: the index of the character that should begin the returned substring
{number} length: the number of characters to return after the start character.

Returns:: {ilib.String} the requested substring

{ilib.String} substring(from, to)

Same as String.substring()

Parameters:
{number} from: the index of the character that should begin the returned substring
{number} to: the index where to stop the extraction. If omitted, extracts the rest of the string

Returns:: {ilib.String} the requested substring

<static> {number} ilib.String.toCodePoint(str, index)

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

Parameters:
{string} str: string to get the code point from
{number} index: index into the string

Returns:: {number} code point of the character at the given index into the string

{ilib.String} toLowerCase()

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

Returns:: {ilib.String} a string with the first character lower-cased

{string} toString()

Same as String.toString()

Returns:: {string} this instance as regular Javascript string

{ilib.String} toUpperCase()

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

Returns:: {ilib.String} a string with the first character upper-cased

{string} valueOf()

Same as String.valueOf()

Returns:: {string} this instance as a regular Javascript string

Classes

Class ilib.String