Class Index | File Index

Classes


Class GlyphString


Extends IString.
Create a new glyph string instance. This string inherits from the IString class, and adds methods that allow you to access whole glyphs at a time.

In Unicode, various accented characters can be created by using a base character and one or more combining characters following it. These appear on the screen to the user as a single glyph. For example, the Latin character "a" (U+0061) followed by the combining diaresis character "¨" (U+0308) combine together to form the "a with diaresis" glyph "ä", which looks like a single character on the screen.

The big problem with combining characters for web developers is that many CSS engines do not ellipsize text between glyphs. They only deal with single Unicode characters. So if a particular space only allows for 4 characters, the CSS engine will truncate a string at 4 Unicode characters and then add the ellipsis (...) character. What if the fourth Unicode character is the "a" and the fifth one is the diaresis? Then a string like "xxxäxxx" that is ellipsized at 4 characters will appear as "xxxa..." on the screen instead of "xxxä...".

In the Latin script as it is commonly used, it is not so common to form accented characters using combining accents, so the above example is mostly for illustrative purposes. It is not unheard of however. The situation is much, much worse in scripts such as Thai and Devanagari that normally make very heavy use of combining characters. These scripts do so because Unicode does not include pre-composed versions of the accented characters like it does for Latin, so combining accents are the only way to create these accented and combined versions of the characters.

The solution to thise problem is not to use the the CSS property "text-overflow: ellipsis" in your web site, ever. Instead, use a glyph string to truncate text between glyphs instead of between characters.

Glyph strings are also useful for truncation, hyphenation, and line wrapping, as all of these should be done between glyphs instead of between characters.

The options parameter is optional, and may contain any combination of the following properties:


Defined in: ilib-full-dyn.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
GlyphString(str, options)
Method Summary
Method Attributes Method Name and Description
 
Return an iterator that will step through all of the characters in the string one at a time, taking care to step through decomposed characters and through surrogate pairs in the UTF-16 encoding as single characters.
 
ellipsize(length)
Truncate the current string at the given number of glyphs and add an ellipsis to indicate that is more to the string.
 
truncate(length)
Truncate the current string at the given number of whole glyphs and return the resulting string.
Methods borrowed from class IString:
charAt, charCodeAt, codePointAt, codePointLength, concat, forEach, forEachCodePoint, format, formatChoice, getLocale, indexOf, iterator, lastIndexOf, match, replace, search, setLocale, slice, split, substr, substring, toLowerCase, toString, toUpperCase, valueOf
Class Detail
GlyphString(str, options)
Parameters:
{string|IString=} str
initialize this instance with this string
{Object=} options
options governing the way this instance works
Method Detail
{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 decomposed characters and through surrogate pairs in the UTF-16 encoding as single characters.

The GlyphString class will return decomposed Unicode characters as a single unit that a user might see on the screen as a single glyph. If the next character in the iteration is a base character and it is followed by combining characters, the base and all its following combining characters are returned as a single unit.

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

{string} ellipsize(length)
Truncate the current string at the given number of glyphs and add an ellipsis to indicate that is more to the string. The ellipsis forms the last character in the string, so the string is actually truncated at length-1 glyphs.
Parameters:
{number} length
the number of whole glyphs to keep in the string including the ellipsis
Returns:
{string} a string truncated to the requested number of glyphs with an ellipsis

{string} truncate(length)
Truncate the current string at the given number of whole glyphs and return the resulting string.
Parameters:
{number} length
the number of whole glyphs to keep in the string
Returns:
{string} a string truncated to the requested number of glyphs

Documentation generated by JsDoc Toolkit 2.4.0 on Tue Feb 02 2016 15:53:55 GMT-0800 (PST)