# Namespace goog.uri.utils

code »

## Enumerations

goog.uri.utils.CharCode_ Character codes inlined to avoid object allocations due to charCode. goog.uri.utils.ComponentIndex The index of each URI component in the return value of goog.uri.utils.split. goog.uri.utils.StandardQueryParam Standard supported query parameters.

Show:Public Protected Private

## Type Definitions

code »goog.uri.utils.QueryArray : `!Array`
An array representing a set of query parameters with alternating keys and values. Keys are assumed to be URI encoded already and live at even indices. See goog.uri.utils.QueryValue for details on how parameter values are encoded. Example:

     var data = [
       // Simple param: ?name=BobBarker
       'name', 'BobBarker',
       // Conditional param -- may be omitted entirely.
       'specialDietaryNeeds', hasDietaryNeeds() ? getDietaryNeeds() : null,
       // Multi-valued param: &house=LosAngeles&house=NewYork&house=null
       'house', ['LosAngeles', 'NewYork', null]
     ];

code »goog.uri.utils.QueryValue : `*`
Supported query parameter values by the parameter serializing utilities. If a value is null or undefined, the key-value pair is skipped, as an easy way to omit parameters conditionally. Non-array parameters are converted to a string and URI encoded. Array values are expanded into multiple &key=value pairs, with each element stringized and URI-encoded.

## Global Functions

code »goog.uri.utils.appendKeyValuePairs_ ( key, value, pairs )

Appends key=value pairs to an array, supporting multi-valued objects.

Parameters
key: `string` The key prefix. value: `goog.uri.utils.QueryValue` The value to serialize. pairs: `!Array.<string>` The array to which the 'key=value' strings should be appended.

code »goog.uri.utils.appendParam ( uri, key, opt_value ) ⇒ `string`

Appends a single URI parameter. Repeated calls to this can exhibit quadratic behavior in IE6 due to the way string append works, though it should be limited given the 2kb limit.

Parameters
uri: `string` The original URI, which may already have query data. key: `string` The key, which must already be URI encoded. opt_value: `*=` The value, which will be stringized and encoded (assumed not already to be encoded). If omitted, undefined, or null, the key will be added as a valueless parameter.
Returns
The URI with the query parameter added.

code »goog.uri.utils.appendParams ( uri, var_args ) ⇒ `string`

Appends URI parameters to an existing URI. The variable arguments may contain alternating keys and values. Keys are assumed to be already URI encoded. The values should not be URI-encoded, and will instead be encoded by this function.

     appendParams('http://www.foo.com?existing=true',
         'key1', 'value1',
         'key2', 'value?willBeEncoded',
         'key3', ['valueA', 'valueB', 'valueC'],
         'key4', null);
     result: 'http://www.foo.com?existing=true&' +
         'key1=value1&' +
         'key2=value%3FwillBeEncoded&' +
         'key3=valueA&key3=valueB&key3=valueC'

A single call to this function will not exhibit quadratic behavior in IE, whereas multiple repeated calls may, although the effect is limited by fact that URL's generally can't exceed 2kb.

Parameters
uri: `string` The original URI, which may already have query data. var_args: `...(goog.uri.utils.QueryArray|string|goog.uri.utils.QueryValue)` An array or argument list conforming to goog.uri.utils.QueryArray.
Returns
The URI with all query parameters added.

code »goog.uri.utils.appendParamsFromMap ( uri, map ) ⇒ `string`

Appends query parameters from a map.

Parameters
uri: `string` The original URI, which may already have query data. map: `Object` An object where keys are URI-encoded parameter keys, and the values are arbitrary types or arrays. Keys with a null value are dropped.
Returns
The new parameters.

code »goog.uri.utils.appendPath ( baseUri, path ) ⇒ `string`

Generates a URI path using a given URI and a path with checks to prevent consecutive "//". The baseUri passed in must not contain query or fragment identifiers. The path to append may not contain query or fragment identifiers.

Parameters
baseUri: `string` URI to use as the base. path: `string` Path to append.
Returns
Updated URI.

code »goog.uri.utils.appendQueryData_ ( buffer ) ⇒ `string`

Appends a URI and query data in a string buffer with special preconditions. Internal implementation utility, performing very few object allocations.

Parameters
buffer: `!Array` A string buffer. The first element must be the base URI, and may have a fragment identifier. If the array contains more than one element, the second element must be an ampersand, and may be overwritten, depending on the base URI. Undefined elements are treated as empty-string.
Returns
The concatenated URI and query data.

code »goog.uri.utils.assertNoFragmentsOrQueries_ ( uri )

Asserts that there are no fragment or query identifiers, only in uncompiled mode.

Parameters
uri: `string` The URI to examine.

code »goog.uri.utils.buildFromEncodedParts ( opt_scheme, opt_userInfo, opt_domain, opt_port, opt_path, opt_queryData, opt_fragment ) ⇒ `string`

Builds a URI string from already-encoded parts. No encoding is performed. Any component may be omitted as either null or undefined.

Parameters
opt_scheme: `?string=` The scheme such as 'http'. opt_userInfo: `?string=` The user name before the '@'. opt_domain: `?string=` The domain such as 'www.google.com', already URI-encoded. opt_port: `(string|number|null)=` The port number. opt_path: `?string=` The path, already URI-encoded. If it is not empty, it must begin with a slash. opt_queryData: `?string=` The URI-encoded query data. opt_fragment: `?string=` The URI-encoded fragment identifier.
Returns
The fully combined URI.

code »goog.uri.utils.buildQueryData ( keysAndValues, opt_startIndex ) ⇒ `string`

Builds a query data string from a sequence of alternating keys and values. Currently generates "&key&" for empty args.

Parameters
keysAndValues: `goog.uri.utils.QueryArray` Alternating keys and values. See the typedef. opt_startIndex: `number=` A start offset into the arary, defaults to 0.
Returns
The encoded query string, in the form 'a=1&b=2'.

code »goog.uri.utils.buildQueryDataBufferFromMap_ ( buffer, map ) ⇒ `!Array`

Builds a buffer of query data from a map.

Parameters
buffer: `!Array` A string buffer to append to. The first element appended will be an '&', and may be replaced by the caller. map: `Object.<goog.uri.utils.QueryValue>` An object where keys are URI-encoded parameter keys, and the values conform to the contract specified in the goog.uri.utils.QueryValue typedef.
Returns
The buffer argument.

code »goog.uri.utils.buildQueryDataBuffer_ ( buffer, keysAndValues, opt_startIndex ) ⇒ `!Array`

Builds a buffer of query data from a sequence of alternating keys and values.

Parameters
buffer: `!Array` A string buffer to append to. The first element appended will be an '&', and may be replaced by the caller. keysAndValues: `(goog.uri.utils.QueryArray|Arguments)` An array with alternating keys and values -- see the typedef. opt_startIndex: `number=` A start offset into the arary, defaults to 0.
Returns
The buffer argument.

code »goog.uri.utils.buildQueryDataFromMap ( map ) ⇒ `string`

Builds a query data string from a map. Currently generates "&key&" for empty args.

Parameters
map: `Object` An object where keys are URI-encoded parameter keys, and the values are arbitrary types or arrays. Keys with a null value are dropped.
Returns
The encoded query string, in the form 'a=1&b=2'.

code »goog.uri.utils.decodeIfPossible_ ( uri, opt_preserveReserved ) ⇒ `?string`

Parameters
uri: `?string` A possibly null string. opt_preserveReserved: `boolean=` If true, percent-encoding of RFC-3986 reserved characters will not be removed.
Returns
The string URI-decoded, or null if uri is null.

code »goog.uri.utils.findParam_ ( uri, startIndex, keyEncoded, hashOrEndIndex ) ⇒ `number`

Finds the next instance of a query parameter with the specified name. Does not instantiate any objects.

Parameters
uri: `string` The URI to search. May contain a fragment identifier if opt_hashIndex is specified. startIndex: `number` The index to begin searching for the key at. A match may be found even if this is one character after the ampersand. keyEncoded: `string` The URI-encoded key. hashOrEndIndex: `number` Index to stop looking at. If a hash mark is present, it should be its index, otherwise it should be the length of the string.
Returns
The position of the first character in the key's name, immediately after either a question mark or a dot.

code »goog.uri.utils.getComponentByIndex_ ( componentIndex, uri ) ⇒ `?string`

Gets a URI component by index. It is preferred to use the getPathEncoded() variety of functions ahead, since they are more readable.

Parameters
componentIndex: `goog.uri.utils.ComponentIndex` The component index. uri: `string` The URI to examine.
Returns
The still-encoded component, or null if the component is not present.

code »goog.uri.utils.getDomain ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The decoded domain, or null if none.

code »goog.uri.utils.getDomainEncoded ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The domain name still encoded, or null if none.

code »goog.uri.utils.getEffectiveScheme ( uri ) ⇒ `string`

Gets the effective scheme for the URL. If the URL is relative then the scheme is derived from the page's location.

Parameters
uri: `string` The URI to examine.
Returns
The protocol or scheme, always lower case.

code »goog.uri.utils.getFragment ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The decoded fragment identifier, or null if none. Does not include the hash mark.

code »goog.uri.utils.getFragmentEncoded ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The fragment identifier, or null if none. Does not include the hash mark itself.

code »goog.uri.utils.getHost ( uri ) ⇒ `string`

Extracts everything up to the port of the URI.

Parameters
uri: `string` The URI string.
Returns
Everything up to and including the port.

code »goog.uri.utils.getParamValue ( uri, keyEncoded ) ⇒ `?string`

Gets the first value of a query parameter.

Parameters
uri: `string` The URI to process. May contain a fragment. keyEncoded: `string` The URI-encoded key. Case-sensitive.
Returns
The first value of the parameter (URI-decoded), or null if the parameter is not found.

code »goog.uri.utils.getParamValues ( uri, keyEncoded ) ⇒ `!Array.<string>`

Gets all values of a query parameter.

Parameters
uri: `string` The URI to process. May contain a framgnet. keyEncoded: `string` The URI-encoded key. Case-snsitive.
Returns
All URI-decoded values with the given key. If the key is not found, this will have length 0, but never be null.

code »goog.uri.utils.getPath ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The decoded path, or null if none. Includes the leading slash, if any.

code »goog.uri.utils.getPathAndAfter ( uri ) ⇒ `string`

Extracts the path of the URL and everything after.

Parameters
uri: `string` The URI string.
Returns
The URI, starting at the path and including the query parameters and fragment identifier.

code »goog.uri.utils.getPathEncoded ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The path still encoded, or null if none. Includes the leading slash, if any.

code »goog.uri.utils.getPort ( uri ) ⇒ `?number`

Parameters
uri: `string` The URI to examine.
Returns
The port number, or null if none.

code »goog.uri.utils.getQueryData ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The query data still encoded, or null if none. Does not include the question mark itself.

code »goog.uri.utils.getScheme ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The protocol or scheme, or null if none. Does not include trailing colons or slashes.

code »goog.uri.utils.getUserInfo ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The decoded user info, or null if none.

code »goog.uri.utils.getUserInfoEncoded ( uri ) ⇒ `?string`

Parameters
uri: `string` The URI to examine.
Returns
The user name still encoded, or null if none.

code »goog.uri.utils.hasParam ( uri, keyEncoded ) ⇒ `boolean`

Determines if the URI contains a specific key. Performs no object instantiations.

Parameters
uri: `string` The URI to process. May contain a fragment identifier. keyEncoded: `string` The URI-encoded key. Case-sensitive.
Returns
Whether the key is present.

code »goog.uri.utils.haveSameDomain ( uri1, uri2 ) ⇒ `boolean`

Ensures that two URI's have the exact same domain, scheme, and port. Unlike the version in goog.Uri, this checks protocol, and therefore is suitable for checking against the browser's same-origin policy.

Parameters
uri1: `string` The first URI. uri2: `string` The second URI.
Returns
Whether they have the same scheme, domain and port.

code »goog.uri.utils.makeUnique ( uri ) ⇒ `string`

Sets the zx parameter of a URI to a random value.

Parameters
uri: `string` Any URI.
Returns
That URI with the "zx" parameter added or replaced to contain a random string.

code »goog.uri.utils.phishingProtection_ ( )

Check to see if the user is being phished.

code »goog.uri.utils.removeFragment ( uri ) ⇒ `string`

Gets the URI with the fragment identifier removed.

Parameters
uri: `string` The URI to examine.
Returns
Everything preceding the hash mark.

code »goog.uri.utils.removeParam ( uri, keyEncoded ) ⇒ `string`

Removes all instances of a query parameter.

Parameters
uri: `string` The URI to process. Must not contain a fragment. keyEncoded: `string` The URI-encoded key.
Returns
The URI with all instances of the parameter removed.

code »goog.uri.utils.setFragmentEncoded ( uri, fragment ) ⇒ `string`

Parameters
uri: `string` The URI to examine. fragment: `?string` The encoded fragment identifier, or null if none. Does not include the hash mark itself.
Returns
The URI with the fragment set.

code »goog.uri.utils.setParam ( uri, keyEncoded, value ) ⇒ `string`

Replaces all existing definitions of a parameter with a single definition. Repeated calls to this can exhibit quadratic behavior due to the need to find existing instances and reconstruct the string, though it should be limited given the 2kb limit. Consider using appendParams to append multiple parameters in bulk.

Parameters
uri: `string` The original URI, which may already have query data. keyEncoded: `string` The key, which must already be URI encoded. value: `*` The value, which will be stringized and encoded (assumed not already to be encoded).
Returns
The URI with the query parameter added.

code »goog.uri.utils.setPath ( uri, path ) ⇒ `string`

Replaces the path.

Parameters
uri: `string` URI to use as the base. path: `string` New path.
Returns
Updated URI.

code »goog.uri.utils.split ( uri ) ⇒ `!Array`

Splits a URI into its component parts. Each component can be accessed via the component indices; for example:

     goog.uri.utils.split(someStr)[goog.uri.utils.CompontentIndex.QUERY_DATA];

Parameters
uri: `string` The URI string to examine.
Returns
Each component still URI-encoded. Each component that is present will contain the encoded value, whereas components that are not present will be undefined or empty, depending on the browser's regular expression implementation. Never null, since arbitrary strings may still look like path names.

## Global Properties

code »goog.uri.utils.hashOrEndRe_ : `RegExp`

Regular expression for finding a hash mark or end of string.

code »goog.uri.utils.needsPhishingProtection_ : `boolean`

Safari has a nasty bug where if you have an http URL with a username, e.g., http://evil.com%2F@google.com/ Safari will report that window.location.href is http://evil.com/google.com/ so that anyone who tries to parse the domain of that URL will get the wrong domain. We've seen exploits where people use this to trick Safari into loading resources from evil domains. To work around this, we run a little "Safari phishing check", and throw an exception if we see this happening. There is no convenient place to put this check. We apply it to anyone doing URI parsing on Webkit. We're not happy about this, but it fixes the problem. This should be removed once Safari fixes their bug. Exploit reported by Masato Kinugawa.

code »goog.uri.utils.splitRe_ : `!RegExp`

A regular expression for breaking a URI into its component parts. `http://www.ietf.org/rfc/rfc3986.txt` says in Appendix B As the "first-match-wins" algorithm is identical to the "greedy" disambiguation method used by POSIX regular expressions, it is natural and commonplace to use a regular expression for parsing the potential five components of a URI reference. The following line is the regular expression for breaking-down a well-formed URI reference into its components.

     ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
      12            3  4          5       6  7        8 9

The numbers in the second line above are only to assist readability; they indicate the reference points for each subexpression (i.e., each paired parenthesis). We refer to the value matched for subexpression as $. For example, matching the above expression to

         http://www.ics.uci.edu/pub/ietf/uri/#Related

results in the following subexpression matches:

        $1 = http:
        $2 = http
        $3 = //www.ics.uci.edu
        $4 = www.ics.uci.edu
        $5 = /pub/ietf/uri/
        $6 =
        $7 =
        $8 = #Related
        $9 = Related

where indicates that the component is not present, as is the case for the query component in the above example. Therefore, we can determine the value of the five components as

        scheme    = $2
        authority = $4
        path      = $5
        query     = $7
        fragment  = $9

The regular expression has been modified slightly to expose the userInfo, domain, and port separately from the authority. The modified version yields

        $1 = http              scheme
        $2 =        userInfo -\
        $3 = www.ics.uci.edu   domain     | authority
        $4 =        port     -/
        $5 = /pub/ietf/uri/    path
        $6 =        query without ?
        $7 = Related           fragment without #

code »goog.uri.utils.trailingQueryPunctuationRe_ : `RegExp`

Regexp to find trailing question marks and ampersands.