Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Inflector.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-util-Inflector'>/**
19 </span> * General purpose inflector class that {@link #pluralize pluralizes}, {@link #singularize singularizes} and
20  * {@link #ordinalize ordinalizes} words. Sample usage:
21  *
22  *     //turning singular words into plurals
23  *     Ext.util.Inflector.pluralize('word'); //'words'
24  *     Ext.util.Inflector.pluralize('person'); //'people'
25  *     Ext.util.Inflector.pluralize('sheep'); //'sheep'
26  *
27  *     //turning plurals into singulars
28  *     Ext.util.Inflector.singularize('words'); //'word'
29  *     Ext.util.Inflector.singularize('people'); //'person'
30  *     Ext.util.Inflector.singularize('sheep'); //'sheep'
31  *
32  *     //ordinalizing numbers
33  *     Ext.util.Inflector.ordinalize(11); //&quot;11th&quot;
34  *     Ext.util.Inflector.ordinalize(21); //&quot;21th&quot;
35  *     Ext.util.Inflector.ordinalize(1043); //&quot;1043rd&quot;
36  *
37  * # Customization
38  *
39  * The Inflector comes with a default set of US English pluralization rules. These can be augmented with additional
40  * rules if the default rules do not meet your application's requirements, or swapped out entirely for other languages.
41  * Here is how we might add a rule that pluralizes &quot;ox&quot; to &quot;oxen&quot;:
42  *
43  *     Ext.util.Inflector.plural(/^(ox)$/i, &quot;$1en&quot;);
44  *
45  * Each rule consists of two items - a regular expression that matches one or more rules, and a replacement string. In
46  * this case, the regular expression will only match the string &quot;ox&quot;, and will replace that match with &quot;oxen&quot;. Here's
47  * how we could add the inverse rule:
48  *
49  *     Ext.util.Inflector.singular(/^(ox)en$/i, &quot;$1&quot;);
50  *
51  * Note that the ox/oxen rules are present by default.
52  */
53 Ext.define('Ext.util.Inflector', {
54
55     /* Begin Definitions */
56
57     singleton: true,
58
59     /* End Definitions */
60
61 <span id='Ext-util-Inflector-property-plurals'>    /**
62 </span>     * @private
63      * The registered plural tuples. Each item in the array should contain two items - the first must be a regular
64      * expression that matchers the singular form of a word, the second must be a String that replaces the matched
65      * part of the regular expression. This is managed by the {@link #plural} method.
66      * @property {Array} plurals
67      */
68     plurals: [
69         [(/(quiz)$/i),                &quot;$1zes&quot;  ],
70         [(/^(ox)$/i),                 &quot;$1en&quot;   ],
71         [(/([m|l])ouse$/i),           &quot;$1ice&quot;  ],
72         [(/(matr|vert|ind)ix|ex$/i),  &quot;$1ices&quot; ],
73         [(/(x|ch|ss|sh)$/i),          &quot;$1es&quot;   ],
74         [(/([^aeiouy]|qu)y$/i),       &quot;$1ies&quot;  ],
75         [(/(hive)$/i),                &quot;$1s&quot;    ],
76         [(/(?:([^f])fe|([lr])f)$/i),  &quot;$1$2ves&quot;],
77         [(/sis$/i),                   &quot;ses&quot;    ],
78         [(/([ti])um$/i),              &quot;$1a&quot;    ],
79         [(/(buffal|tomat|potat)o$/i), &quot;$1oes&quot;  ],
80         [(/(bu)s$/i),                 &quot;$1ses&quot;  ],
81         [(/(alias|status|sex)$/i),    &quot;$1es&quot;   ],
82         [(/(octop|vir)us$/i),         &quot;$1i&quot;    ],
83         [(/(ax|test)is$/i),           &quot;$1es&quot;   ],
84         [(/^person$/),                &quot;people&quot; ],
85         [(/^man$/),                   &quot;men&quot;    ],
86         [(/^(child)$/),               &quot;$1ren&quot;  ],
87         [(/s$/i),                     &quot;s&quot;      ],
88         [(/$/),                       &quot;s&quot;      ]
89     ],
90
91 <span id='Ext-util-Inflector-property-singulars'>    /**
92 </span>     * @private
93      * The set of registered singular matchers. Each item in the array should contain two items - the first must be a
94      * regular expression that matches the plural form of a word, the second must be a String that replaces the
95      * matched part of the regular expression. This is managed by the {@link #singular} method.
96      * @property {Array} singulars
97      */
98     singulars: [
99       [(/(quiz)zes$/i),                                                    &quot;$1&quot;     ],
100       [(/(matr)ices$/i),                                                   &quot;$1ix&quot;   ],
101       [(/(vert|ind)ices$/i),                                               &quot;$1ex&quot;   ],
102       [(/^(ox)en/i),                                                       &quot;$1&quot;     ],
103       [(/(alias|status)es$/i),                                             &quot;$1&quot;     ],
104       [(/(octop|vir)i$/i),                                                 &quot;$1us&quot;   ],
105       [(/(cris|ax|test)es$/i),                                             &quot;$1is&quot;   ],
106       [(/(shoe)s$/i),                                                      &quot;$1&quot;     ],
107       [(/(o)es$/i),                                                        &quot;$1&quot;     ],
108       [(/(bus)es$/i),                                                      &quot;$1&quot;     ],
109       [(/([m|l])ice$/i),                                                   &quot;$1ouse&quot; ],
110       [(/(x|ch|ss|sh)es$/i),                                               &quot;$1&quot;     ],
111       [(/(m)ovies$/i),                                                     &quot;$1ovie&quot; ],
112       [(/(s)eries$/i),                                                     &quot;$1eries&quot;],
113       [(/([^aeiouy]|qu)ies$/i),                                            &quot;$1y&quot;    ],
114       [(/([lr])ves$/i),                                                    &quot;$1f&quot;    ],
115       [(/(tive)s$/i),                                                      &quot;$1&quot;     ],
116       [(/(hive)s$/i),                                                      &quot;$1&quot;     ],
117       [(/([^f])ves$/i),                                                    &quot;$1fe&quot;   ],
118       [(/(^analy)ses$/i),                                                  &quot;$1sis&quot;  ],
119       [(/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i), &quot;$1$2sis&quot;],
120       [(/([ti])a$/i),                                                      &quot;$1um&quot;   ],
121       [(/(n)ews$/i),                                                       &quot;$1ews&quot;  ],
122       [(/people$/i),                                                       &quot;person&quot; ],
123       [(/s$/i),                                                            &quot;&quot;       ]
124     ],
125
126 <span id='Ext-util-Inflector-property-uncountable'>    /**
127 </span>     * @private
128      * The registered uncountable words
129      * @property {String[]} uncountable
130      */
131      uncountable: [
132         &quot;sheep&quot;,
133         &quot;fish&quot;,
134         &quot;series&quot;,
135         &quot;species&quot;,
136         &quot;money&quot;,
137         &quot;rice&quot;,
138         &quot;information&quot;,
139         &quot;equipment&quot;,
140         &quot;grass&quot;,
141         &quot;mud&quot;,
142         &quot;offspring&quot;,
143         &quot;deer&quot;,
144         &quot;means&quot;
145     ],
146
147 <span id='Ext-util-Inflector-method-singular'>    /**
148 </span>     * Adds a new singularization rule to the Inflector. See the intro docs for more information
149      * @param {RegExp} matcher The matcher regex
150      * @param {String} replacer The replacement string, which can reference matches from the matcher argument
151      */
152     singular: function(matcher, replacer) {
153         this.singulars.unshift([matcher, replacer]);
154     },
155
156 <span id='Ext-util-Inflector-method-plural'>    /**
157 </span>     * Adds a new pluralization rule to the Inflector. See the intro docs for more information
158      * @param {RegExp} matcher The matcher regex
159      * @param {String} replacer The replacement string, which can reference matches from the matcher argument
160      */
161     plural: function(matcher, replacer) {
162         this.plurals.unshift([matcher, replacer]);
163     },
164
165 <span id='Ext-util-Inflector-method-clearSingulars'>    /**
166 </span>     * Removes all registered singularization rules
167      */
168     clearSingulars: function() {
169         this.singulars = [];
170     },
171
172 <span id='Ext-util-Inflector-method-clearPlurals'>    /**
173 </span>     * Removes all registered pluralization rules
174      */
175     clearPlurals: function() {
176         this.plurals = [];
177     },
178
179 <span id='Ext-util-Inflector-method-isTransnumeral'>    /**
180 </span>     * Returns true if the given word is transnumeral (the word is its own singular and plural form - e.g. sheep, fish)
181      * @param {String} word The word to test
182      * @return {Boolean} True if the word is transnumeral
183      */
184     isTransnumeral: function(word) {
185         return Ext.Array.indexOf(this.uncountable, word) != -1;
186     },
187
188 <span id='Ext-util-Inflector-method-pluralize'>    /**
189 </span>     * Returns the pluralized form of a word (e.g. Ext.util.Inflector.pluralize('word') returns 'words')
190      * @param {String} word The word to pluralize
191      * @return {String} The pluralized form of the word
192      */
193     pluralize: function(word) {
194         if (this.isTransnumeral(word)) {
195             return word;
196         }
197
198         var plurals = this.plurals,
199             length  = plurals.length,
200             tuple, regex, i;
201
202         for (i = 0; i &lt; length; i++) {
203             tuple = plurals[i];
204             regex = tuple[0];
205
206             if (regex == word || (regex.test &amp;&amp; regex.test(word))) {
207                 return word.replace(regex, tuple[1]);
208             }
209         }
210
211         return word;
212     },
213
214 <span id='Ext-util-Inflector-method-singularize'>    /**
215 </span>     * Returns the singularized form of a word (e.g. Ext.util.Inflector.singularize('words') returns 'word')
216      * @param {String} word The word to singularize
217      * @return {String} The singularized form of the word
218      */
219     singularize: function(word) {
220         if (this.isTransnumeral(word)) {
221             return word;
222         }
223
224         var singulars = this.singulars,
225             length    = singulars.length,
226             tuple, regex, i;
227
228         for (i = 0; i &lt; length; i++) {
229             tuple = singulars[i];
230             regex = tuple[0];
231
232             if (regex == word || (regex.test &amp;&amp; regex.test(word))) {
233                 return word.replace(regex, tuple[1]);
234             }
235         }
236
237         return word;
238     },
239
240 <span id='Ext-util-Inflector-method-classify'>    /**
241 </span>     * Returns the correct {@link Ext.data.Model Model} name for a given string. Mostly used internally by the data
242      * package
243      * @param {String} word The word to classify
244      * @return {String} The classified version of the word
245      */
246     classify: function(word) {
247         return Ext.String.capitalize(this.singularize(word));
248     },
249
250 <span id='Ext-util-Inflector-method-ordinalize'>    /**
251 </span>     * Ordinalizes a given number by adding a prefix such as 'st', 'nd', 'rd' or 'th' based on the last digit of the
252      * number. 21 -&gt; 21st, 22 -&gt; 22nd, 23 -&gt; 23rd, 24 -&gt; 24th etc
253      * @param {Number} number The number to ordinalize
254      * @return {String} The ordinalized number
255      */
256     ordinalize: function(number) {
257         var parsed = parseInt(number, 10),
258             mod10  = parsed % 10,
259             mod100 = parsed % 100;
260
261         //11 through 13 are a special case
262         if (11 &lt;= mod100 &amp;&amp; mod100 &lt;= 13) {
263             return number + &quot;th&quot;;
264         } else {
265             switch(mod10) {
266                 case 1 : return number + &quot;st&quot;;
267                 case 2 : return number + &quot;nd&quot;;
268                 case 3 : return number + &quot;rd&quot;;
269                 default: return number + &quot;th&quot;;
270             }
271         }
272     }
273 }, function() {
274     //aside from the rules above, there are a number of words that have irregular pluralization so we add them here
275     var irregulars = {
276             alumnus: 'alumni',
277             cactus : 'cacti',
278             focus  : 'foci',
279             nucleus: 'nuclei',
280             radius: 'radii',
281             stimulus: 'stimuli',
282             ellipsis: 'ellipses',
283             paralysis: 'paralyses',
284             oasis: 'oases',
285             appendix: 'appendices',
286             index: 'indexes',
287             beau: 'beaux',
288             bureau: 'bureaux',
289             tableau: 'tableaux',
290             woman: 'women',
291             child: 'children',
292             man: 'men',
293             corpus:     'corpora',
294             criterion: 'criteria',
295             curriculum: 'curricula',
296             genus: 'genera',
297             memorandum: 'memoranda',
298             phenomenon: 'phenomena',
299             foot: 'feet',
300             goose: 'geese',
301             tooth: 'teeth',
302             antenna: 'antennae',
303             formula: 'formulae',
304             nebula: 'nebulae',
305             vertebra: 'vertebrae',
306             vita: 'vitae'
307         },
308         singular;
309
310     for (singular in irregulars) {
311         this.plural(singular, irregulars[singular]);
312         this.singular(irregulars[singular], singular);
313     }
314 });</pre>
315 </body>
316 </html>