jssource/src_files/include/javascript/yui3/build/text/text-accentfold.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('text-accentfold', function(Y) {
   9
  10 /**
  11  * Text utilities.
  12  *
  13  * @module text
  14  * @since 3.3.0
  15  */
  16
  17 /**
  18  * Provides a basic accent folding implementation that converts common accented
  19  * letters (like "á") to their non-accented forms (like "a").
  20  *
  21  * @module text
  22  * @submodule text-accentfold
  23  */
  24
  25 /**
  26  * <p>
  27  * Provides a basic accent folding implementation that converts common accented
  28  * letters (like "á") to their non-accented forms (like "a").
  29  * </p>
  30  *
  31  * <p>
  32  * This implementation is not comprehensive, and should only be used as a last
  33  * resort when accent folding can't be done on the server. A comprehensive
  34  * accent folding implementation would require much more character data to be
  35  * sent to the browser, resulting in a significant performance penalty. This
  36  * implementation strives for a compromise between usefulness and performance.
  37  * </p>
  38  *
  39  * <p>
  40  * Accent folding is a destructive operation that can't be reversed, and may
  41  * change or destroy the actual meaning of the text depending on the language.
  42  * It should not be used on strings that will later be displayed to a user,
  43  * unless this is done with the understanding that linguistic meaning may be
  44  * lost and that you may in fact confuse or insult the user by doing so.
  45  * </p>
  46  *
  47  * <p>
  48  * When used for matching, accent folding is likely to produce erroneous matches
  49  * for languages in which characters with diacritics are considered different
  50  * from their base characters, or where correct folding would map to other
  51  * character sequences than just stripped characters. For example, in German
  52  * "ü" is a character that's clearly different from "u" and should match "ue"
  53  * instead. The word "betrügen" means "to defraud", while "betrugen" is the past
  54  * tense of "to behave". The name "Müller" is expected to match "Mueller", but
  55  * not "Muller". On the other hand, accent folding falls short for languages
  56  * where different base characters are expected to match. In Japanese, for
  57  * example, hiragana and katakana characters with the same pronunciation ("あ"
  58  * and "ア") are commonly treated as equivalent for lookups, but accent folding
  59  * treats them as different.
  60  * </p>
  61  *
  62  * @class Text.AccentFold
  63  * @static
  64  */
  65
  66 var YArray   = Y.Array,
  67     Text     = Y.Text,
  68     FoldData = Text.Data.AccentFold,
  69
  70 AccentFold = {
  71     // -- Public Static Methods ------------------------------------------------
  72
  73     /**
  74      * Returns <code>true</code> if the specified string contains one or more
  75      * characters that can be folded, <code>false</code> otherwise.
  76      *
  77      * @method canFold
  78      * @param {String} string String to test.
  79      * @return {Boolean}
  80      * @static
  81      */
  82     canFold: function (string) {
  83         var letter;
  84
  85         for (letter in FoldData) {
  86             if (FoldData.hasOwnProperty(letter) &&
  87                     string.search(FoldData[letter]) !== -1) {
  88                 return true;
  89             }
  90         }
  91
  92         return false;
  93     },
  94
  95     /**
  96      * Compares the accent-folded versions of two strings and returns
  97      * <code>true</code> if they're the same, <code>false</code> otherwise. If
  98      * a custom comparison function is supplied, the accent-folded strings will
  99      * be passed to that function for comparison.
 100      *
 101      * @method compare
 102      * @param {String} a First string to compare.
 103      * @param {String} b Second string to compare.
 104      * @param {Function} func (optional) Custom comparison function. Should
 105      *   return a truthy or falsy value.
 106      * @return {Boolean} Results of the comparison.
 107      * @static
 108      */
 109     compare: function (a, b, func) {
 110         var aFolded = AccentFold.fold(a),
 111             bFolded = AccentFold.fold(b);
 112
 113         return func ? !!func(aFolded, bFolded) : aFolded === bFolded;
 114     },
 115
 116     /**
 117      * <p>
 118      * Returns a copy of <em>haystack</em> containing only the strings for which
 119      * the supplied function returns <code>true</code>.
 120      * </p>
 121      *
 122      * <p>
 123      * While comparisons will be made using accent-folded strings, the returned
 124      * array of matches will contain the original strings that were passed in.
 125      * </p>
 126      *
 127      * @method filter
 128      * @param {Array} haystack Array of strings to filter.
 129      * @param {Function} func Comparison function. Will receive an accent-folded
 130      *   haystack string as an argument, and should return a truthy or falsy
 131      *   value.
 132      * @return {Array} Filtered copy of <em>haystack</em>.
 133      * @static
 134      */
 135     filter: function (haystack, func) {
 136         return YArray.filter(haystack, function (item) {
 137             return func(AccentFold.fold(item));
 138         });
 139     },
 140
 141     /**
 142      * Accent-folds the specified string or array of strings and returns a copy
 143      * in which common accented letters have been converted to their closest
 144      * non-accented, lowercase forms.
 145      *
 146      * @method fold
 147      * @param {String|Array} input String or array of strings to be folded.
 148      * @return {String|Array} Folded string or array of strings.
 149      * @static
 150      */
 151     fold: function (input) {
 152         if (Y.Lang.isArray(input)) {
 153             return YArray.map(input, AccentFold.fold);
 154         }
 155
 156         input = input.toLowerCase();
 157
 158         Y.Object.each(FoldData, function (regex, letter) {
 159             input = input.replace(regex, letter);
 160         });
 161
 162         return input;
 163     }
 164 };
 165
 166 Text.AccentFold = AccentFold;
 167
 168
 169 }, '3.3.0' ,{requires:['array-extras', 'text-data-accentfold']});