Docs/Native/String.md

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