lib/yui/3.5.1/build/text-accentfold/text-accentfold.js

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