# 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 <n> as $<n>. 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 = <undefined>
        $7 = <undefined>
        $8 = #Related
        $9 = Related

where <undefined> 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 = <undefined>       userInfo -\
        $3 = www.ics.uci.edu   domain     | authority
        $4 = <undefined>       port     -/
        $5 = /pub/ietf/uri/    path
        $6 = <undefined>       query without ?
        $7 = Related           fragment without #

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

Regexp to find trailing question marks and ampersands.