Docs/Types/String.md

   1 Type: String {#String}
   2 ====================
   3
   4 A collection of the String Object methods and functions.
   5
   6 ### See Also:
   7
   8 - [MDN String][]
   9
  10
  11
  12 Function: String.from {#String:String-from}
  13 ------------------------------------
  14
  15 Returns the passed parameter as a String.
  16
  17 ### Syntax:
  18
  19         String.from(arg);
  20
  21 ### Arguments:
  22
  23 1. arg - (*mixed*) The argument to return as a string.
  24
  25 ### Returns:
  26
  27 * (*string*) The argument as a string.
  28
  29 ### Example:
  30
  31         String.from(2); // returns '2'
  32         String.from(true); // returns 'true'
  33
  34
  35
  36 Function: String.uniqueID {#String:String-uniqueID}
  37 ---------------------------------------------------
  38
  39 Generates a unique ID
  40
  41 ### Syntax:
  42
  43         String.uniqueID();
  44
  45 ### Returns:
  46
  47 * (*string*) A unique ID.
  48
  49 ### Example:
  50
  51         String.uniqueID();
  52
  53
  54 String method: test {#String:test}
  55 ---------------------------
  56
  57 Searches for a match between the string and a regular expression.
  58 For more information see [MDN Regexp:test][].
  59
  60 ### Syntax:
  61
  62         myString.test(regex[, params]);
  63
  64 ### Arguments:
  65
  66 1. regex  - (*mixed*) The string or regular expression you want to match the string with.
  67 2. params - (*string*, optional) If first parameter is a string, any parameters you want to pass to the regular expression ('g' has no effect).
  68
  69 ### Returns:
  70
  71 * (*boolean*) `true`, if a match for the regular expression is found in this string.
  72 * (*boolean*) `false` if is not found
  73
  74 ### Examples:
  75
  76         'I like cookies'.test('cookie'); // returns true
  77         'I like cookies'.test('COOKIE', 'i'); // returns true (ignore case)
  78         'I like cookies'.test('cake'); // returns false
  79
  80 ### See Also:
  81
  82 - [MDN Regular Expressions][]
  83
  84
  85
  86 String method: contains {#String:contains}
  87 -----------------------------------
  88
  89 Checks to see if the string passed in is contained in this string.
  90 If the position parameter is passed, it will only check for the string from that point.
  91
  92 ### Syntax:
  93
  94         myString.contains(string[, position]);
  95
  96 ### Arguments:
  97
  98 1. string    - (*string*) The string to search for.
  99 2. position - (*number*, optional) Position in the string to begin searching for `string`, defaults to `0`.
 100
 101 ### Returns:
 102
 103 * (*boolean*) `true` if the string is contained in this string
 104 * (*boolean*) `false` if not.
 105
 106 ### Examples:
 107
 108         'a bc'.contains('bc'); // returns true
 109         'abc'.contains('b', 1); // returns true
 110         'abc'.contains('b', 2); // returns false
 111
 112 ### See Also:
 113
 114 - [MDN String:indexOf][]
 115 - [MDN String:contains][]
 116
 117 ### Note:
 118
 119 Since MooTools 1.5 the second parameter changed from `separator` to `position` so it conforms the ES6 specification.
 120 If using the 1.4 compatibility layer, this method will be overwritten to have the old behavior.
 121
 122 String method: trim {#String:trim}
 123 ---------------------------
 124
 125 Trims the leading and trailing spaces off a string.
 126
 127 ### Syntax:
 128
 129         myString.trim();
 130
 131 ### Returns:
 132
 133 * (*string*) The trimmed string.
 134
 135 ### Examples:
 136
 137         '    i like cookies     '.trim(); // returns 'i like cookies'
 138
 139 ### See Also:
 140
 141 - [MDN String:trim][]
 142
 143 String method: clean {#String:clean}
 144 -----------------------------
 145
 146 Removes all extraneous whitespace from a string and trims it ([String:trim][]).
 147
 148 ### Syntax:
 149
 150         myString.clean();
 151
 152 ### Returns:
 153
 154 * (*string*) The cleaned string.
 155
 156 ### Examples:
 157
 158         ' i      like     cookies      \n\n'.clean(); // returns 'i like cookies'
 159
 160
 161
 162 String method: camelCase {#String:camelCase}
 163 -------------------------------------
 164
 165 Converts a hyphenated string to a camelcased string.
 166
 167 ### Syntax:
 168
 169         myString.camelCase();
 170
 171 ### Returns:
 172
 173 * (*string*) The camelcased string.
 174
 175 ### Examples:
 176
 177         'I-like-cookies'.camelCase(); // returns 'ILikeCookies'
 178
 179
 180
 181 String method: hyphenate {#String:hyphenate}
 182 -------------------------------------
 183
 184 Converts a camelcased string to a hyphenated string.
 185
 186 ### Syntax:
 187
 188         myString.hyphenate();
 189
 190 ### Returns:
 191
 192 * (*string*) The hyphenated string.
 193
 194 ### Examples:
 195
 196         'ILikeCookies'.hyphenate(); // returns '-i-like-cookies'
 197
 198
 199
 200 String method: capitalize {#String:capitalize}
 201 ---------------------------------------
 202
 203 Converts the first letter of each word in a string to uppercase.
 204
 205 ### Syntax:
 206
 207         myString.capitalize();
 208
 209 ### Returns:
 210
 211 * (*string*) The capitalized string.
 212
 213 ### Examples:
 214
 215         'i like cookies'.capitalize(); // returns 'I Like Cookies'
 216
 217
 218
 219 String method: escapeRegExp {#String:escapeRegExp}
 220 -------------------------------------------
 221
 222 Escapes all regular expression characters from the string.
 223
 224 ### Syntax:
 225
 226         myString.escapeRegExp();
 227
 228 ### Returns:
 229
 230 * (*string*) The escaped string.
 231
 232 ### Examples:
 233
 234         'animals.sheep[1]'.escapeRegExp(); // returns 'animals\.sheep\[1\]'
 235
 236
 237
 238 String method: toInt {#String:toInt}
 239 -----------------------------
 240
 241 Parses this string and returns a number of the specified radix or base.
 242
 243 ### Syntax:
 244
 245         myString.toInt([base]);
 246
 247 ### Arguments:
 248
 249 1. base - (*number*, optional) The base to use (defaults to 10).
 250
 251 ### Returns:
 252
 253 * (*number*) The number.
 254 * (*NaN*) If the string is not numeric, returns NaN.
 255
 256 ### Examples:
 257
 258         '4em'.toInt(); // returns 4
 259         '10px'.toInt(); // returns 10
 260
 261 ### See Also:
 262
 263 - [MDN parseInt][]
 264
 265
 266
 267 String method: toFloat {#String:toFloat}
 268 ---------------------------------
 269
 270 Parses this string and returns a floating point number.
 271
 272 ### Syntax:
 273
 274         myString.toFloat();
 275
 276 ### Returns:
 277
 278 * (*number*) The float.
 279 * (*NaN*) If the string is not numeric, returns NaN.
 280
 281 ### Examples:
 282
 283                 '95.25%'.toFloat(); // returns 95.25
 284                 '10.848'.toFloat(); // returns 10.848
 285
 286 ### See Also:
 287
 288 - [MDN parseFloat][]
 289
 290
 291
 292 String method: hexToRgb {#String:hexToRgb}
 293 -----------------------------------
 294
 295 Converts a hexadecimal color value to RGB. Input string must be in one of the following hexadecimal color formats (with or without the hash).
 296 '#ffffff', #fff', 'ffffff', or 'fff'
 297
 298 ### Syntax:
 299
 300         myString.hexToRgb([array]);
 301
 302 ### Arguments:
 303
 304 1. array - (*boolean*, optional) If true is passed, will output an array (e.g. \[255, 51, 0\]) instead of a string (e.g. 'rgb(255, 51, 0)').
 305
 306 ### Returns:
 307
 308 * (*string*) A string representing the color in RGB.
 309 * (*array*) If the array flag is set, an array will be returned instead.
 310
 311 ### Examples:
 312
 313         '#123'.hexToRgb(); // returns 'rgb(17, 34, 51)'
 314         '112233'.hexToRgb(); // returns 'rgb(17, 34, 51)'
 315         '#112233'.hexToRgb(true); // returns [17, 34, 51]
 316
 317
 318
 319 String method: rgbToHex {#String:rgbToHex}
 320 -----------------------------------
 321
 322 Converts an RGB color value to hexadecimal. Input string must be in one of the following RGB color formats.
 323 'rgb(255, 255, 255)', or 'rgba(255, 255, 255, 1)'
 324
 325 ### Syntax:
 326
 327         myString.rgbToHex([array]);
 328
 329 ### Arguments:
 330
 331 1. array - (*boolean*, optional) If true is passed, will output an array (e.g. \['ff', '33', '00'\]) instead of a string (e.g. '#ff3300').
 332
 333 ### Returns:
 334
 335 * (*string*) A string representing the color in hexadecimal, or transparent if the fourth value of rgba in the input string is 0.
 336 * (*array*) If the array flag is set, an array will be returned instead.
 337
 338 ### Examples:
 339
 340         'rgb(17, 34, 51)'.rgbToHex(); // returns '#112233'
 341         'rgb(17, 34, 51)'.rgbToHex(true); // returns ['11', '22', '33']
 342         'rgba(17, 34, 51, 0)'.rgbToHex(); // returns 'transparent'
 343
 344 ### See Also:
 345
 346 - [Array:rgbToHex][]
 347
 348
 349
 350 String method: substitute {#String:substitute}
 351 ---------------------------------------
 352
 353 Substitutes keywords in a string using an object/array.
 354 Removes undefined keywords and ignores escaped keywords.
 355
 356 ### Syntax:
 357
 358         myString.substitute(object[, regexp]);
 359
 360 ### Arguments:
 361
 362 1. object - (*mixed*) The key/value pairs used to substitute a string.
 363 1. regexp - (*regexp*, optional) The regexp pattern to be used in the string keywords, with global flag. Defaults to /\\?\{([^}]+)\}/g .
 364
 365 ### Returns:
 366
 367 * (*string*) - The substituted string.
 368
 369 ### Examples:
 370
 371         var myString = '{subject} is {property_1} and {property_2}.';
 372         var myObject = {subject: 'Jack Bauer', property_1: 'our lord', property_2: 'saviour'};
 373         myString.substitute(myObject); // returns Jack Bauer is our lord and saviour
 374
 375
 376
 377 String method: stripScripts {#String:stripScripts}
 378 ----------------------------------------------------
 379
 380 Strips the String of its *<script>* tags and anything in between them.
 381
 382 ### Syntax:
 383
 384         myString.stripScripts([evaluate]);
 385
 386 ### Arguments:
 387
 388 1. evaluate - (*boolean*, optional) If true is passed, the scripts within the String will be evaluated.
 389
 390 ### Returns:
 391
 392 * (*string*) - The String without the stripped scripts.
 393
 394 ### Examples:
 395
 396         var myString = "<script>alert('Hello')</script>Hello, World.";
 397         myString.stripScripts(); // returns 'Hello, World.'
 398         myString.stripScripts(true); // alerts 'Hello', then returns 'Hello, World.'
 399
 400
 401
 402 [MDN String]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String
 403 [MDN String:contains]: https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String/contains
 404 [MDN String:indexOf]: https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String/indexOf
 405 [MDN String:trim]: https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/String/trim
 406 [MDN Regexp:test]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/RegExp/test
 407 [MDN Regular Expressions]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide/Regular_Expressions
 408 [MDN parseInt]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Functions/parseInt
 409 [MDN parseFloat]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Functions/parseFloat
 410 [MDN Array]: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array
 411 [String:trim]: #String:trim
 412 [Array:rgbToHex]: /core/Types/Array/#Array:rgbToHex
 413 [String:trim]: #String:trim