[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('text-accentfold', function (Y, NAME) {
   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.17.2', {"requires": ["array-extras", "text-data-accentfold"]});