# Namespace goog.string

code »

## Enumerations

goog.string.Unicode Common Unicode string characters.

Show:Public Protected Private

## Global Functions

code »goog.string.buildString ( var_args ) ⇒ `string`

Concatenates string expressions. This is useful since some browsers are very inefficient when it comes to using plus to concat strings. Be careful when using null and undefined here since these will not be included in the result. If you need to represent these be sure to cast the argument to a String first. For example:

    buildString('a', 'b', 'c', 'd') -> 'abcd'
     buildString(null, undefined) -> ''

Parameters
var_args: `...*` A list of strings to concatenate. If not a string, it will be casted to one.
Returns
The concatenation of `var_args`.

code »goog.string.canonicalizeNewlines ( str ) ⇒ `string`

Replaces Windows and Mac new lines with unix style: \r or \r\n with \n.

Parameters
str: `string` The string to in which to canonicalize newlines.
Returns
`str` A copy of {@code} with canonicalized newlines.

code »goog.string.caseInsensitiveCompare ( str1, str2 ) ⇒ `number`

A string comparator that ignores case. -1 = str1 less than str2 0 = str1 equals str2 1 = str1 greater than str2

Parameters
str1: `string` The string to compare. str2: `string` The string to compare `str1` to.
Returns
The comparator result, as described above.

code »goog.string.caseInsensitiveEndsWith ( str, suffix ) ⇒ `boolean`

Case-insensitive suffix-checker.

Parameters
str: `string` The string to check. suffix: `string` A string to look for at the end of `str`.
Returns
True if `str` ends with `suffix` (ignoring case).

code »goog.string.caseInsensitiveEquals ( str1, str2 ) ⇒ `boolean`

Case-insensitive equality checker.

Parameters
str1: `string` First string to check. str2: `string` Second string to check.
Returns
True if `str1` and `str2` are the same string, ignoring case.

code »goog.string.caseInsensitiveStartsWith ( str, prefix ) ⇒ `boolean`

Case-insensitive prefix-checker.

Parameters
str: `string` The string to check. prefix: `string` A string to look for at the end of `str`.
Returns
True if `str` begins with `prefix` (ignoring case).

code »goog.string.collapseBreakingSpaces ( str ) ⇒ `string`

Removes the breaking spaces from the left and right of the string and collapses the sequences of breaking spaces in the middle into single spaces. The original and the result strings render the same way in HTML.

Parameters
str: `string` A string in which to collapse spaces.
Returns
Copy of the string with normalized breaking spaces.

code »goog.string.collapseWhitespace ( str ) ⇒ `string`

Converts multiple whitespace chars (spaces, non-breaking-spaces, new lines and tabs) to a single space, and strips leading and trailing whitespace.

Parameters
str: `string` Input string.
Returns
A copy of `str` with collapsed whitespace.

code »goog.string.compareElements_ ( left, right ) ⇒ `number`

Compares elements of a version number.

Parameters
left: `(string|number|boolean)` An element from a version number. right: `(string|number|boolean)` An element from a version number.
Returns
1 if `left` is higher. 0 if arguments are equal. -1 if `right` is higher.

code »goog.string.compareVersions ( version1, version2 ) ⇒ `number`

Compares two version numbers.

Parameters
version1: `(string|number)` Version of first item. version2: `(string|number)` Version of second item.
Returns
1 if `version1` is higher. 0 if arguments are equal. -1 if `version2` is higher.

code »goog.string.contains ( s, ss ) ⇒ `boolean`

Checks whether a string contains a given substring.

Parameters
s: `string` The string to test. ss: `string` The substring to test for.
Returns
True if `s` contains `ss`.

code »goog.string.countOf ( s, ss ) ⇒ `number`

Returns the non-overlapping occurrences of ss in s. If either s or ss evalutes to false, then returns zero.

Parameters
s: `string` The string to look in. ss: `string` The string to look for.
Returns
Number of occurrences of ss in s.

code »goog.string.createUniqueString ( ) ⇒ `string`

Generates and returns a string which is unique in the current document. This is useful, for example, to create unique IDs for DOM elements.

Returns
A unique id.

code »goog.string.endsWith ( str, suffix ) ⇒ `boolean`

Fast suffix-checker.

Parameters
str: `string` The string to check. suffix: `string` A string to look for at the end of `str`.
Returns
True if `str` ends with `suffix`.

code »goog.string.escapeChar ( c ) ⇒ `string`

Takes a character and returns the escaped string for that character. For example escapeChar(String.fromCharCode(15)) -> "\\x0E".

Parameters
c: `string` The character to escape.
Returns
An escaped string representing `c`.

code »goog.string.escapeString ( str ) ⇒ `string`

Takes a string and returns the escaped string for that character.

Parameters
str: `string` The string to escape.
Returns
An escaped string representing `str`.

code »goog.string.getRandomString ( ) ⇒ `string`

Returns a string with at least 64-bits of randomness. Doesn't trust Javascript's random function entirely. Uses a combination of random and current timestamp, and then encodes the string in base-36 to make it shorter.

Returns
A random string, e.g. sn1s7vb4gcic.

code »goog.string.hashCode ( str ) ⇒ `number`

String hash function similar to java.lang.String.hashCode(). The hash code for a string is computed as s[0] * 31 ^ (n - 1) + s[1] * 31 ^ (n - 2) + ... + s[n - 1], where s[i] is the ith character of the string and n is the length of the string. We mod the result to make it between 0 (inclusive) and 2^32 (exclusive).

Parameters
str: `string` A string.
Returns
Hash value for `str`, between 0 (inclusive) and 2^32 (exclusive). The empty string returns 0.

code »goog.string.htmlEscape ( str, opt_isLikelyToContainHtmlChars ) ⇒ `string`

Escape double quote '"' characters in addition to '&', '<', and '>' so that a string can be included in an HTML tag attribute value within double quotes. It should be noted that > doesn't need to be escaped for the HTML or XML to be valid, but it has been decided to escape it for consistency with other implementations. NOTE(user): HtmlEscape is often called during the generation of large blocks of HTML. Using statics for the regular expressions and strings is an optimization that can more than half the amount of time IE spends in this function for large apps, since strings and regexes both contribute to GC allocations. Testing for the presence of a character before escaping increases the number of function calls, but actually provides a speed increase for the average case -- since the average case often doesn't require the escaping of all 4 characters and indexOf() is much cheaper than replace(). The worst case does suffer slightly from the additional calls, therefore the opt_isLikelyToContainHtmlChars option has been included for situations where all 4 HTML entities are very likely to be present and need escaping. Some benchmarks (times tended to fluctuate +-0.05ms): FireFox IE6 (no chars / average (mix of cases) / all 4 chars) no checks 0.13 / 0.22 / 0.22 0.23 / 0.53 / 0.80 indexOf 0.08 / 0.17 / 0.26 0.22 / 0.54 / 0.84 indexOf + re test 0.07 / 0.17 / 0.28 0.19 / 0.50 / 0.85 An additional advantage of checking if replace actually needs to be called is a reduction in the number of object allocations, so as the size of the application grows the difference between the various methods would increase.

Parameters
str: `string` string to be escaped. opt_isLikelyToContainHtmlChars: `boolean=` Don't perform a check to see if the character needs replacing - use this option if you expect each of the characters to appear often. Leave false if you expect few html characters to occur in your strings, such as if you are escaping HTML.
Returns
An escaped copy of `str`.

code »goog.string.isAlpha ( str ) ⇒ `boolean`

Checks if a string contains all letters.

Parameters
str: `string` string to check.
Returns
True if `str` consists entirely of letters.

code »goog.string.isAlphaNumeric ( str ) ⇒ `boolean`

Checks if a string contains only numbers or letters.

Parameters
str: `string` string to check.
Returns
True if `str` is alphanumeric.

code »goog.string.isBreakingWhitespace ( str ) ⇒ `boolean`

Checks if a string is all breaking whitespace.

Parameters
str: `string` The string to check.
Returns
Whether the string is all breaking whitespace.

code »goog.string.isEmpty ( str ) ⇒ `boolean`

Checks if a string is empty or contains only whitespaces.

Parameters
str: `string` The string to check.
Returns
True if `str` is empty or whitespace only.

code »goog.string.isEmptySafe ( str ) ⇒ `boolean`

Checks if a string is null, undefined, empty or contains only whitespaces.

Parameters
str: `*` The string to check.
Returns
True if`str` is null, undefined, empty, or whitespace only.

code »goog.string.isLowerCamelCase ( str ) ⇒ `boolean`

Returns whether the given string is lower camel case (e.g. "isFooBar"). Note that this assumes the string is entirely letters.

Parameters
str: `string` String to test.
Returns
Whether the string is lower camel case.

code »goog.string.isNumeric ( str ) ⇒ `boolean`

Checks if a string contains only numbers.

Parameters
str: `*` string to check. If not a string, it will be casted to one.
Returns
True if `str` is numeric.

code »goog.string.isSpace ( ch ) ⇒ `boolean`

Checks if a character is a space character.

Parameters
ch: `string` Character to check.
Returns
True if {code ch} is a space.

code »goog.string.isUnicodeChar ( ch ) ⇒ `boolean`

Checks if a character is a valid unicode character.

Parameters
ch: `string` Character to check.
Returns
True if {code ch} is a valid unicode character.

code »goog.string.isUpperCamelCase ( str ) ⇒ `boolean`

Returns whether the given string is upper camel case (e.g. "FooBarBaz"). Note that this assumes the string is entirely letters.

Parameters
str: `string` String to test.
Returns
Whether the string is upper camel case.

code »goog.string.makeSafe ( obj ) ⇒ `string`

Returns a string representation of the given object, with null and undefined being returned as the empty string.

Parameters
obj: `*` The object to convert.
Returns
A string representation of the `obj`.

code »goog.string.newLineToBr ( str, opt_xml ) ⇒ `string`

Converts \n to
s or
s.

Parameters
str: `string` The string in which to convert newlines. opt_xml: `boolean=` Whether to use XML compatible tags.
Returns
A copy of `str` with converted newlines.

code »goog.string.normalizeSpaces ( str ) ⇒ `string`

Normalizes spaces in a string, replacing all consecutive spaces and tabs with a single space. Replaces non-breaking space with a space.

Parameters
str: `string` The string in which to normalize spaces.
Returns
A copy of `str` with all consecutive spaces and tabs replaced with a single space.

code »goog.string.normalizeWhitespace ( str ) ⇒ `string`

Normalizes whitespace in a string, replacing all whitespace chars with a space.

Parameters
str: `string` The string in which to normalize whitespace.
Returns
A copy of `str` with all whitespace normalized.

code »goog.string.numerateCompare ( str1, str2 ) ⇒ `number`

String comparison function that handles numbers in a way humans might expect. Using this function, the string "File 2.jpg" sorts before "File 10.jpg". The comparison is mostly case-insensitive, though strings that are identical except for case are sorted with the upper-case strings before lower-case. This comparison function is significantly slower (about 500x) than either the default or the case-insensitive compare. It should not be used in time-critical code, but should be fast enough to sort several hundred short strings (like filenames) with a reasonable delay.

Parameters
str1: `string` The string to compare in a numerically sensitive way. str2: `string` The string to compare `str1` to.
Returns
less than 0 if str1 < str2, 0 if str1 == str2, greater than 0 if str1 > str2.

code »goog.string.padNumber ( num, length, opt_precision ) ⇒ `string`

Pads number to given length and optionally rounds it to a given precision. For example:

    padNumber(1.25, 2, 3) -> '01.250'
     padNumber(1.25, 2) -> '01.25'
     padNumber(1.25, 2, 1) -> '01.3'
     padNumber(1.25, 0) -> '1.25'

Parameters
num: `number` The number to pad. length: `number` The desired length. opt_precision: `number=` The desired precision.
Returns
`num` as a string with the given options.

code »goog.string.parseInt ( value ) ⇒ `number`

Parse a string in decimal or hexidecimal ('0xFFFF') form. To parse a particular radix, please use parseInt(string, radix) directly. See https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/parseInt This is a wrapper for the built-in parseInt function that will only parse numbers as base 10 or base 16. Some JS implementations assume strings starting with "0" are intended to be octal. ES3 allowed but discouraged this behavior. ES5 forbids it. This function emulates the ES5 behavior. For more information, see Mozilla JS Reference: http://goo.gl/8RiFj

Parameters
value: `(string|number|null|undefined)` The value to be parsed.
Returns
The number, parsed. If the string failed to parse, this will be NaN.

code »goog.string.quote ( s ) ⇒ `string`

Encloses a string in double quotes and escapes characters so that the string is a valid JS string.

Parameters
s: `string` The string to quote.
Returns
A copy of `s` surrounded by double quotes.

code »goog.string.regExpEscape ( s ) ⇒ `string`

Escapes characters in the string that are not safe to use in a RegExp.

Parameters
s: `*` The string to escape. If not a string, it will be casted to one.
Returns
A RegExp safe, escaped copy of `s`.

code »goog.string.remove ( s, ss ) ⇒ `string`

Removes the first occurrence of a substring from a string.

Parameters
s: `string` The base string from which to remove. ss: `string` The string to remove.
Returns
A copy of `s` with `ss` removed or the full string if nothing is removed.

code »goog.string.removeAll ( s, ss ) ⇒ `string`

Removes all occurrences of a substring from a string.

Parameters
s: `string` The base string from which to remove. ss: `string` The string to remove.
Returns
A copy of `s` with `ss` removed or the full string if nothing is removed.

code »goog.string.removeAt ( s, index, stringLength ) ⇒ `string`

Removes a substring of a specified length at a specific index in a string.

Parameters
s: `string` The base string from which to remove. index: `number` The index at which to remove the substring. stringLength: `number` The length of the substring to remove.
Returns
A copy of `s` with the substring removed or the full string if nothing is removed or the input is invalid.

code »goog.string.repeat ( string, length ) ⇒ `string`

Repeats a string n times.

Parameters
string: `string` The string to repeat. length: `number` The number of times to repeat.
Returns
A string containing `length` repetitions of `string`.

code »goog.string.splitLimit ( str, separator, limit ) ⇒ `!Array.<string>`

Splits a string on a separator a limited number of times. This implementation is more similar to Python or Java, where the limit parameter specifies the maximum number of splits rather than truncating the number of results. See http://docs.python.org/2/library/stdtypes.html#str.split See JavaDoc: http://goo.gl/F2AsY See Mozilla reference: http://goo.gl/dZdZs

Parameters
str: `string` String to split. separator: `string` The separator. limit: `number` The limit to the number of splits. The resulting array will have a maximum length of limit+1. Negative numbers are the same as zero.
Returns
The string, split.

code »goog.string.startsWith ( str, prefix ) ⇒ `boolean`

Fast prefix-checker.

Parameters
str: `string` The string to check. prefix: `string` A string to look for at the start of `str`.
Returns
True if `str` begins with `prefix`.

code »goog.string.stripNewlines ( str ) ⇒ `string`

Takes a string and replaces newlines with a space. Multiple lines are replaced with a single space.

Parameters
str: `string` The string from which to strip newlines.
Returns
A copy of `str` stripped of newlines.

code »goog.string.stripQuotes ( str, quoteChars ) ⇒ `string`

Strip quote characters around a string. The second argument is a string of characters to treat as quotes. This can be a single character or a string of multiple character and in that case each of those are treated as possible quote characters. For example:

     goog.string.stripQuotes('"abc"', '"`') --> 'abc'
     goog.string.stripQuotes('`abc`', '"`') --> 'abc'

Parameters
str: `string` The string to strip. quoteChars: `string` The quote characters to strip.
Returns
A copy of `str` without the quotes.

code »goog.string.subs ( str, var_args ) ⇒ `string`

Does simple python-style string substitution. subs("foo%s hot%s", "bar", "dog") becomes "foobar hotdog".

Parameters
str: `string` The string containing the pattern. var_args: `...*` The items to substitute into the pattern.
Returns
A copy of `str` in which each occurrence of `%s` has been replaced an argument from `var_args`.

code »goog.string.toCamelCase ( str ) ⇒ `string`

Converts a string from selector-case to camelCase (e.g. from "multi-part-string" to "multiPartString"), useful for converting CSS selectors and HTML dataset keys to their equivalent JS properties.

Parameters
str: `string` The string in selector-case form.
Returns
The string in camelCase form.

code »goog.string.toMap ( s ) ⇒ `Object`

Takes a string and creates a map (Object) in which the keys are the characters in the string. The value for the key is set to true. You can then use goog.object.map or goog.array.map to change the values.

Parameters
s: `string` The string to build the map from.
Returns
The map of characters used.

code »goog.string.toNumber ( str ) ⇒ `number`

Converts the supplied string to a number, which may be Ininity or NaN. This function strips whitespace: (toNumber(' 123') === 123) This function accepts scientific notation: (toNumber('1e1') === 10) This is better than Javascript's built-in conversions because, sadly: (Number(' ') === 0) and (parseFloat('123a') === 123)

Parameters
str: `string` The string to convert.
Returns
The number the supplied string represents, or NaN.

code »goog.string.toSelectorCase ( str ) ⇒ `string`

Converts a string from camelCase to selector-case (e.g. from "multiPartString" to "multi-part-string"), useful for converting JS style and dataset properties to equivalent CSS selectors and HTML keys.

Parameters
str: `string` The string in camelCase form.
Returns
The string in selector-case form.

code »goog.string.toTitleCase ( str, opt_delimiters ) ⇒ `string`

Converts a string into TitleCase. First character of the string is always capitalized in addition to the first letter of every subsequent word. Words are delimited by one or more whitespaces by default. Custom delimiters can optionally be specified to replace the default, which doesn't preserve whitespace delimiters and instead must be explicitly included if needed. Default delimiter => " ": goog.string.toTitleCase('oneTwoThree') => 'OneTwoThree' goog.string.toTitleCase('one two three') => 'One Two Three' goog.string.toTitleCase(' one two ') => ' One Two ' goog.string.toTitleCase('one_two_three') => 'One_two_three' goog.string.toTitleCase('one-two-three') => 'One-two-three' Custom delimiter => "_-.": goog.string.toTitleCase('oneTwoThree', '_-.') => 'OneTwoThree' goog.string.toTitleCase('one two three', '_-.') => 'One two three' goog.string.toTitleCase(' one two ', '_-.') => ' one two ' goog.string.toTitleCase('one_two_three', '_-.') => 'One_Two_Three' goog.string.toTitleCase('one-two-three', '_-.') => 'One-Two-Three' goog.string.toTitleCase('one...two...three', '_-.') => 'One...Two...Three' goog.string.toTitleCase('one. two. three', '_-.') => 'One. two. three' goog.string.toTitleCase('one-two.three', '_-.') => 'One-Two.Three'

Parameters
str: `string` String value in camelCase form. opt_delimiters: `string=` Custom delimiter character set used to distinguish words in the string value. Each character represents a single delimiter. When provided, default whitespace delimiter is overridden and must be explicitly included if needed.
Returns
String value in TitleCase form.

code »goog.string.trim ( str ) ⇒ `string`

Trims white spaces to the left and right of a string.

Parameters
str: `string` The string to trim.
Returns
A trimmed copy of `str`.

code »goog.string.trimLeft ( str ) ⇒ `string`

Trims whitespaces at the left end of a string.

Parameters
str: `string` The string to left trim.
Returns
A trimmed copy of `str`.

code »goog.string.trimRight ( str ) ⇒ `string`

Trims whitespaces at the right end of a string.

Parameters
str: `string` The string to right trim.
Returns
A trimmed copy of `str`.

code »goog.string.truncate ( str, chars, opt_protectEscapedCharacters ) ⇒ `string`

Truncates a string to a certain length and adds '...' if necessary. The length also accounts for the ellipsis, so a maximum length of 10 and a string 'Hello World!' produces 'Hello W...'.

Parameters
str: `string` The string to truncate. chars: `number` Max number of characters. opt_protectEscapedCharacters: `boolean=` Whether to protect escaped characters from being cut off in the middle.
Returns
The truncated `str` string.

code »goog.string.truncateMiddle ( str, chars, opt_protectEscapedCharacters, opt_trailingChars ) ⇒ `string`

Truncate a string in the middle, adding "..." if necessary, and favoring the beginning of the string.

Parameters
str: `string` The string to truncate the middle of. chars: `number` Max number of characters. opt_protectEscapedCharacters: `boolean=` Whether to protect escaped characters from being cutoff in the middle. opt_trailingChars: `number=` Optional number of trailing characters to leave at the end of the string, instead of truncating as close to the middle as possible.
Returns
A truncated copy of `str`.

code »goog.string.unescapeEntities ( str ) ⇒ `string`

Unescapes an HTML string.

Parameters
str: `string` The string to unescape.
Returns
An unescaped copy of `str`.

code »goog.string.unescapeEntitiesUsingDom_ ( str ) ⇒ `string`

Unescapes an HTML string using a DOM to resolve non-XML, non-numeric entities. This function is XSS-safe and whitespace-preserving.

Parameters
str: `string` The string to unescape.
Returns
The unescaped `str` string.

code »goog.string.unescapePureXmlEntities_ ( str ) ⇒ `string`

Unescapes XML entities.

Parameters
str: `string` The string to unescape.
Returns
An unescaped copy of `str`.

code »goog.string.urlDecode ( str ) ⇒ `string`

URL-decodes the string. We need to specially handle '+'s because the javascript library doesn't convert them to spaces.

Parameters
str: `string` The string to url decode.
Returns
The decoded `str`.

code »goog.string.urlEncode ( str ) ⇒ `string`

URL-encodes a string

Parameters
str: `*` The string to url-encode.
Returns
An encoded copy of `str` that is safe for urls. Note that '#', ':', and other characters used to delimit portions of URLs *will* be encoded.

code »goog.string.whitespaceEscape ( str, opt_xml ) ⇒ `string`

Do escaping of whitespace to preserve spatial formatting. We use character entity #160 to make it safer for xml.

Parameters
str: `string` The string in which to escape whitespace. opt_xml: `boolean=` Whether to use XML compatible tags.
Returns
An escaped copy of `str`.

## Global Properties

code »goog.string.HASHCODE_MAX_ : `number`

Maximum value of #goog.string.hashCode, exclusive. 2^32.

code »goog.string.HTML_ENTITY_PATTERN_ : `!RegExp`

Regular expression that matches an HTML entity. See also HTML5: Tokenization / Tokenizing character references.

code »goog.string.allRe_ : `RegExp`

Regular expression that matches any character that needs to be escaped.

code »goog.string.amperRe_ : `RegExp`

Regular expression that matches an ampersand, for use in escaping.

code »goog.string.gtRe_ : `RegExp`

Regular expression that matches a greater than sign, for use in escaping.

code »goog.string.jsEscapeCache_ : `Object`

Character mappings used internally for goog.string.escapeChar.

code »goog.string.ltRe_ : `RegExp`

Regular expression that matches a less than sign, for use in escaping.

code »goog.string.numerateCompareRegExp_ : `RegExp`

Regular expression used for splitting a string into substrings of fractional numbers, integers, and non-numeric characters.

code »goog.string.quotRe_ : `RegExp`

Regular expression that matches a double quote, for use in escaping.

code »goog.string.specialEscapeChars_ : `Object`

Special chars that need to be escaped for goog.string.quote.

code »goog.string.uniqueStringCounter_ : `number`

The most recent unique ID. |0 is equivalent to Math.floor in this case.