76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Text utilities.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @module text
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @since 3.3.0
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Provides a basic accent folding implementation that converts common accented
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * letters (like "á") to their non-accented forms (like "a").
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @module text
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @submodule text-accentfold
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Provides a basic accent folding implementation that converts common accented
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * letters (like "á") to their non-accented forms (like "a").
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * This implementation is not comprehensive, and should only be used as a last
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * resort when accent folding can't be done on the server. A comprehensive
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * accent folding implementation would require much more character data to be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * sent to the browser, resulting in a significant performance penalty. This
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * implementation strives for a compromise between usefulness and performance.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Accent folding is a destructive operation that can't be reversed, and may
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * change or destroy the actual meaning of the text depending on the language.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * It should not be used on strings that will later be displayed to a user,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * unless this is done with the understanding that linguistic meaning may be
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * lost and that you may in fact confuse or insult the user by doing so.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * When used for matching, accent folding is likely to produce erroneous matches
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * for languages in which characters with diacritics are considered different
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * from their base characters, or where correct folding would map to other
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * character sequences than just stripped characters. For example, in German
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * "ü" is a character that's clearly different from "u" and should match "ue"
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * instead. The word "betrügen" means "to defraud", while "betrugen" is the past
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * tense of "to behave". The name "Müller" is expected to match "Mueller", but
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * not "Muller". On the other hand, accent folding falls short for languages
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * where different base characters are expected to match. In Japanese, for
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * example, hiragana and katakana characters with the same pronunciation ("あ"
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * and "ア") are commonly treated as equivalent for lookups, but accent folding
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * treats them as different.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @class Text.AccentFold
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glassvar YArray = Y.Array,
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass // -- Public Static Methods ------------------------------------------------
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Returns <code>true</code> if the specified string contains one or more
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * characters that can be folded, <code>false</code> otherwise.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method canFold
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} string String to test.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Boolean}
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return true;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return false;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Compares the accent-folded versions of two strings and returns
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * <code>true</code> if they're the same, <code>false</code> otherwise. If
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * a custom comparison function is supplied, the accent-folded strings will
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * be passed to that function for comparison.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method compare
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} a First string to compare.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String} b Second string to compare.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Function} func (optional) Custom comparison function. Should
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * return a truthy or falsy value.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Boolean} Results of the comparison.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass return func ? !!func(aFolded, bFolded) : aFolded === bFolded;
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Returns a copy of <em>haystack</em> containing only the strings for which
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * the supplied function returns <code>true</code>.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * While comparisons will be made using accent-folded strings, the returned
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * array of matches will contain the original strings that were passed in.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method filter
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Array} haystack Array of strings to filter.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {Function} func Comparison function. Will receive an accent-folded
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * haystack string as an argument, and should return a truthy or falsy
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {Array} Filtered copy of <em>haystack</em>.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * Accent-folds the specified string or array of strings and returns a copy
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * in which common accented letters have been converted to their closest
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * non-accented, lowercase forms.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @method fold
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @param {String|Array} input String or array of strings to be folded.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass * @return {String|Array} Folded string or array of strings.
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass Y.Object.each(FoldData, function (regex, letter) {
76ca635d61eb3f9fb7c9d788a44fa8b1690aa138Dav Glass}, '@VERSION@' ,{requires:['array-extras', 'text-data-accentfold']});