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