goog.uri.utils

Provided By	`goog.uri.utils`

No description available.

VIEW SOURCE

Functions

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

string

The URI with the query parameter added.

VIEW SOURCE

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`	`...*`
	An array or argument list conforming to goog.uri.utils.QueryArray.

Returns

string

The URI with all query parameters added.

VIEW SOURCE

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

string

The new parameters.

VIEW SOURCE

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

string

Updated URI.

VIEW SOURCE

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\|null)=`
	The scheme such as 'http'.
`opt_userInfo`	`(string\|null)=`
	The user name before the '@'.
`opt_domain`	`(string\|null)=`
	The domain such as 'www.google.com', already URI-encoded.
`opt_port`	`(string\|number\|null)=`
	The port number.
`opt_path`	`(string\|null)=`
	The path, already URI-encoded. If it is not empty, it must begin with a slash.
`opt_queryData`	`(string\|null)=`
	The URI-encoded query data.
`opt_fragment`	`(string\|null)=`
	The URI-encoded fragment identifier.

Returns

string

The fully combined URI.

VIEW SOURCE

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

Parameters

`keysAndValues`	`IArrayLike<*>`
	Alternating keys and values. See the QueryArray typedef.
`opt_startIndex`	`number=`
	A start offset into the arary, defaults to 0.

Returns

string

The encoded query string, in the form 'a=1&b=2'.

VIEW SOURCE

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

Parameters

`map`	`Object<string, *>`
	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

string

The encoded query string, in the form 'a=1&b=2'.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The decoded domain, or null if none.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The domain name still encoded, or null if none.

VIEW SOURCE

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

string

The protocol or scheme, always lower case.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The decoded fragment identifier, or null if none. Does not include the hash mark.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The fragment identifier, or null if none. Does not include the hash mark itself.

VIEW SOURCE

Extracts everything up to the port of the URI.

Parameters

`uri`	`string`
	The URI string.

Returns

string

Everything up to and including the port.

VIEW SOURCE

Returns the origin for a given URL.

Parameters

`uri`	`string`
	The URI string.

Returns

string

Everything up to and including the port.

VIEW SOURCE

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

(string|null)

The first value of the parameter (URI-decoded), or null if the parameter is not found.

VIEW SOURCE

Gets all values of a query parameter.

Parameters

`uri`	`string`
	The URI to process. May contain a fragment.
`keyEncoded`	`string`
	The URI-encoded key. Case-sensitive.

Returns

Array<string>

All URI-decoded values with the given key. If the key is not found, this will have length 0, but never be null.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The decoded path, or null if none. Includes the leading slash, if any.

VIEW SOURCE

Extracts the path of the URL and everything after.

Parameters

`uri`	`string`
	The URI string.

Returns

string

The URI, starting at the path and including the query parameters and fragment identifier.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The path still encoded, or null if none. Includes the leading slash, if any.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(number|null)

The port number, or null if none.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The query data still encoded, or null if none. Does not include the question mark itself.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The protocol or scheme, or null if none. Does not include trailing colons or slashes.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The decoded user info, or null if none.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.

Returns

(string|null)

The user name still encoded, or null if none.

VIEW SOURCE

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

boolean

Whether the key is present.

VIEW SOURCE

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

boolean

Whether they have the same scheme, domain and port.

VIEW SOURCE

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

Parameters

`uri`	`string`
	Any URI.

Returns

string

That URI with the "zx" parameter added or replaced to contain a random string.

VIEW SOURCE

Parses encoded query parameters and calls callback function for every parameter found in the string.

Missing value of parameter (e.g. “…&key&…”) is treated as if the value was an empty string. Keys may be empty strings (e.g. “…&=value&…”) which also means that “…&=&…” and “…&&…” will result in an empty key and value.

Parameters

`encodedQuery`	`string`
	Encoded query string excluding question mark at the beginning.
`callback`	`function(string, string): ?`
	Function called for every parameter found in query string. The first argument (name) will not be urldecoded (so the function is consistent with buildQueryData), but the second will. If the parameter has no value (i.e. “=” was not present) the second argument (value) will be an empty string.

VIEW SOURCE

Gets the URI with the fragment identifier removed.

Parameters

`uri`	`string`
	The URI to examine.

Returns

string

Everything preceding the hash mark.

VIEW SOURCE

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

string

The URI with all instances of the parameter removed.

VIEW SOURCE

Parameters

`uri`	`string`
	The URI to examine.
`fragment`	`(string\|null)`
	The encoded fragment identifier, or null if none. Does not include the hash mark itself.

Returns

string

The URI with the fragment set.

VIEW SOURCE

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 or setParamsFromMap to update 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

string

The URI with the query parameter added.

VIEW SOURCE

Effeciently set or remove multiple query parameters in a URI. Order of unchanged parameters will not be modified, all updated parameters will be appended to the end of the query. Params with values of null or undefined are removed.

Parameters

`uri`	`string`
	The URI to process.
`params`	`Object<string, *>`
	A list of parameters to update. If null or undefined, the param will be removed.

Returns

string

An updated URI where the query data has been updated with the params.

VIEW SOURCE

Replaces the path.

Parameters

`uri`	`string`
	URI to use as the base.
`path`	`string`
	New path.

Returns

string

Updated URI.

VIEW SOURCE

Parameters

`handler`	`(function(string): ?\|null)`
	The handler function to call when a URI with a protocol that is better supported by the Closure URL package is detected.

VIEW SOURCE

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.ComponentIndex.QUERY_DATA];

Parameters

`uri`	`string`
	The URI string to examine.

Returns

Array<(string|undefined)>

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.

VIEW SOURCE

Properties

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]
 ];

VIEW SOURCE

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.

VIEW SOURCE

goog.uri.utils

Functions

appendParam( uri, key, opt_value ) → string

appendParams( uri, ...var_args ) → string

appendParamsFromMap( uri, map ) → string

appendPath( baseUri, path ) → string

buildFromEncodedParts( opt_scheme, opt_userInfo, opt_domain, opt_port, opt_path, opt_queryData, opt_fragment ) → string

buildQueryData( keysAndValues, opt_startIndex ) → string

buildQueryDataFromMap( map ) → string

getDomain( uri ) → (string|null)

getDomainEncoded( uri ) → (string|null)

getEffectiveScheme( uri ) → string

getFragment( uri ) → (string|null)

getFragmentEncoded( uri ) → (string|null)

getHost( uri ) → string

getOrigin( uri ) → string

getParamValue( uri, keyEncoded ) → (string|null)

getParamValues( uri, keyEncoded ) → Array<string>

getPath( uri ) → (string|null)

getPathAndAfter( uri ) → string

getPathEncoded( uri ) → (string|null)

getPort( uri ) → (number|null)

getQueryData( uri ) → (string|null)

getScheme( uri ) → (string|null)

getUserInfo( uri ) → (string|null)

getUserInfoEncoded( uri ) → (string|null)

hasParam( uri, keyEncoded ) → boolean

haveSameDomain( uri1, uri2 ) → boolean

makeUnique( uri ) → string

parseQueryData( encodedQuery, callback ) → void

removeFragment( uri ) → string

removeParam( uri, keyEncoded ) → string

setFragmentEncoded( uri, fragment ) → string

setParam( uri, keyEncoded, value ) → string

setParamsFromMap( uri, params ) → string

setPath( uri, path ) → string

setUrlPackageSupportLoggingHandler( handler ) → void

split( uri ) → Array<(string|undefined)>

Properties

QueryArray → Array<*>

QueryValue → *

Enumerations

appendParam( `uri`, `key`, `opt_value` ) `→` `string`

appendParams( `uri`, `...var_args` ) `→` `string`

appendParamsFromMap( `uri`, `map` ) `→` `string`

appendPath( `baseUri`, `path` ) `→` `string`

buildFromEncodedParts( `opt_scheme`, `opt_userInfo`, `opt_domain`, `opt_port`, `opt_path`, `opt_queryData`, `opt_fragment` ) `→` `string`

buildQueryData( `keysAndValues`, `opt_startIndex` ) `→` `string`

buildQueryDataFromMap( `map` ) `→` `string`

getDomain( `uri` ) `→` `(string|null)`

getDomainEncoded( `uri` ) `→` `(string|null)`

getEffectiveScheme( `uri` ) `→` `string`

getFragment( `uri` ) `→` `(string|null)`

getFragmentEncoded( `uri` ) `→` `(string|null)`

getHost( `uri` ) `→` `string`

getOrigin( `uri` ) `→` `string`

getParamValue( `uri`, `keyEncoded` ) `→` `(string|null)`

getParamValues( `uri`, `keyEncoded` ) `→` `Array<string>`

getPath( `uri` ) `→` `(string|null)`

getPathAndAfter( `uri` ) `→` `string`

getPathEncoded( `uri` ) `→` `(string|null)`

getPort( `uri` ) `→` `(number|null)`

getQueryData( `uri` ) `→` `(string|null)`

getScheme( `uri` ) `→` `(string|null)`

getUserInfo( `uri` ) `→` `(string|null)`

getUserInfoEncoded( `uri` ) `→` `(string|null)`

hasParam( `uri`, `keyEncoded` ) `→` `boolean`

haveSameDomain( `uri1`, `uri2` ) `→` `boolean`

makeUnique( `uri` ) `→` `string`

parseQueryData( `encodedQuery`, `callback` ) `→` `void`

removeFragment( `uri` ) `→` `string`

removeParam( `uri`, `keyEncoded` ) `→` `string`

setFragmentEncoded( `uri`, `fragment` ) `→` `string`

setParam( `uri`, `keyEncoded`, `value` ) `→` `string`

setParamsFromMap( `uri`, `params` ) `→` `string`

setPath( `uri`, `path` ) `→` `string`

setUrlPackageSupportLoggingHandler( `handler` ) `→` `void`

split( `uri` ) `→` `Array<(string|undefined)>`

QueryArray `→` `Array<*>`

QueryValue `→` `*`