# Class goog.Uri

code »

This class contains setters and getters for the parts of the URI. The `getXyz`/`setXyz` methods return the decoded part -- so`goog.Uri.parse('/foo%20bar').getPath()` will return the decoded path, `/foo bar`. Reserved characters (see RFC 3986 section 2.2) can be present in their percent-encoded form in scheme, domain, and path URI components and will not be auto-decoded. For example: `goog.Uri.parse('rel%61tive/path%2fto/resource').getPath()` will return `relative/path%2fto/resource`. The constructor accepts an optional unparsed, raw URI string. The parser is relaxed, so special characters that aren't escaped but don't cause ambiguities will not cause parse failures. All setters return `this` and so may be chained, a la `goog.Uri.parse('/foo').setFragment('part').toString()`.

## Constructor

goog.Uri ( opt_uri, opt_ignoreCase )

Parameters
opt_uri: `*=` Optional string URI to parse (use goog.Uri.create() to create a URI from parts), or if a goog.Uri is passed, a clone is created. opt_ignoreCase: `boolean=` If true, #getParameterValue will ignore the case of the parameter name.

## Classes

goog.Uri.QueryData Class used to represent URI query parameters.

Show:Public Protected Private

## Instance Methods

code »clone ( ) ⇒ `!goog.Uri`

Clones the URI instance.

Returns
New instance of the URI object.

code »enforceReadOnly ( )

Checks if this Uri has been marked as read only, and if so, throws an error. This should be called whenever any modifying function is called.

code »getDecodedQuery ( ) ⇒ `string`

Returns
The decoded URI query, not including the ?.

code »getDomain ( ) ⇒ `string`

Returns
The decoded domain.

code »getEncodedQuery ( ) ⇒ `string`

Returns
The encoded URI query, not including the ?.

code »getFragment ( ) ⇒ `string`

Returns
The URI fragment, not including the #.

code »getIgnoreCase ( ) ⇒ `boolean`

Returns
Whether to ignore case.

code »getParameterValue ( paramName ) ⇒ `(string|undefined)`

Returns the first value for a given cgi parameter or undefined if the given parameter name does not appear in the query string.

Parameters
paramName: `string` Unescaped parameter name.
Returns
The first value for a given cgi parameter or undefined if the given parameter name does not appear in the query string.

code »getParameterValues ( name ) ⇒ `!Array`

Returns the values for a given cgi parameter as a list of decoded query parameter values.

Parameters
name: `string` The parameter to get values for.
Returns
The values for a given cgi parameter as a list of decoded query parameter values.

code »getPath ( ) ⇒ `string`

Returns
The decoded path.

code »getPort ( ) ⇒ `?number`

Returns
The port number.

code »getQuery ( ) ⇒ `string`

Returns
The encoded URI query, not including the ?. Warning: This method, unlike other getter methods, returns encoded value, instead of decoded one.

code »getQueryData ( ) ⇒ `!goog.Uri.QueryData`

Returns the query data.

Returns
QueryData object.

code »getScheme ( ) ⇒ `string`

Returns
The encoded scheme/protocol for the URI.

code »getUserInfo ( ) ⇒ `string`

Returns
The decoded user info.

code »hasDomain ( ) ⇒ `boolean`

Returns
Whether the domain has been set.

code »hasFragment ( ) ⇒ `boolean`

Returns
Whether the URI has a fragment set.

code »hasPath ( ) ⇒ `boolean`

Returns
Whether the path has been set.

code »hasPort ( ) ⇒ `boolean`

Returns
Whether the port has been set.

code »hasQuery ( ) ⇒ `boolean`

Returns
Whether the query string has been set.

code »hasSameDomainAs ( uri2 ) ⇒ `boolean`

Returns true if this has the same domain as that of uri2.

Parameters
uri2: `goog.Uri` The URI object to compare to.
Returns
true if same domain; false otherwise.

code »hasScheme ( ) ⇒ `boolean`

Returns
Whether the scheme has been set.

code »hasUserInfo ( ) ⇒ `boolean`

Returns
Whether the user info has been set.

code »isReadOnly ( ) ⇒ `boolean`

Returns
Whether the URI is read only.

code »makeUnique ( ) ⇒ `!goog.Uri`

Adds a random parameter to the Uri.

Returns
Reference to this Uri object.

code »removeParameter ( key ) ⇒ `!goog.Uri`

Removes the named query parameter.

Parameters
key: `string` The parameter to remove.
Returns
Reference to this URI object.

code »resolve ( relativeUri ) ⇒ `!goog.Uri`

Resolves the given relative URI (a goog.Uri object), using the URI represented by this instance as the base URI. There are several kinds of relative URIs:
1. foo - replaces the last part of the path, the whole query and fragment
2. /foo - replaces the the path, the query and fragment
3. //foo - replaces everything from the domain on. foo is a domain name
4. ?foo - replace the query and fragment
5. #foo - replace the fragment only Additionally, if relative URI has a non-empty path, all ".." and "." segments will be resolved, as described in RFC 3986.

Parameters
relativeUri: `goog.Uri` The relative URI to resolve.
Returns
The resolved URI.

code »setDomain ( newDomain, opt_decode ) ⇒ `!goog.Uri`

Sets the domain.

Parameters
newDomain: `string` New domain value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »setFragment ( newFragment, opt_decode ) ⇒ `!goog.Uri`

Sets the URI fragment.

Parameters
newFragment: `string` New fragment value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »setIgnoreCase ( ignoreCase ) ⇒ `!goog.Uri`

Sets whether to ignore case. NOTE: If there are already key/value pairs in the QueryData, and ignoreCase_ is set to false, the keys will all be lower-cased.

Parameters
ignoreCase: `boolean` whether this goog.Uri should ignore case.
Returns
Reference to this Uri object.

code »setParameterValue ( key, value ) ⇒ `!goog.Uri`

Sets the value of the named query parameters, clearing previous values for that key.

Parameters
key: `string` The parameter to set. value: `*` The new value.
Returns
Reference to this URI object.

code »setParameterValues ( key, values ) ⇒ `!goog.Uri`

Sets the values of the named query parameters, clearing previous values for that key. Not new values will currently be moved to the end of the query string. So, `goog.Uri.parse('foo?a=b&c=d&e=f').setParameterValues('c', ['new'])` yields `foo?a=b&e=f&c=new`.

Parameters
key: `string` The parameter to set. values: `*` The new values. If values is a single string then it will be treated as the sole value.
Returns
Reference to this URI object.

code »setPath ( newPath, opt_decode ) ⇒ `!goog.Uri`

Sets the path.

Parameters
newPath: `string` New path value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »setPort ( newPort ) ⇒ `!goog.Uri`

Sets the port number.

Parameters
newPort: `*` Port number. Will be explicitly casted to a number.
Returns
Reference to this URI object.

code »setQuery ( newQuery, opt_decode ) ⇒ `!goog.Uri`

Sets the URI query.

Parameters
newQuery: `string` New query value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »setQueryData ( queryData, opt_decode ) ⇒ `!goog.Uri`

Sets the query data.

Parameters
queryData: `(goog.Uri.QueryData|string|undefined)` QueryData object. opt_decode: `boolean=` Optional param for whether to decode new value. Applies only if queryData is a string.
Returns
Reference to this URI object.

code »setReadOnly ( isReadOnly ) ⇒ `!goog.Uri`

Sets whether Uri is read only. If this goog.Uri is read-only, enforceReadOnly_ will be called at the start of any function that may modify this Uri.

Parameters
isReadOnly: `boolean` whether this goog.Uri should be read only.
Returns
Reference to this Uri object.

code »setScheme ( newScheme, opt_decode ) ⇒ `!goog.Uri`

Sets the scheme/protocol.

Parameters
newScheme: `string` New scheme value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »setUserInfo ( newUserInfo, opt_decode ) ⇒ `!goog.Uri`

Sets the userInfo.

Parameters
newUserInfo: `string` New userInfo value. opt_decode: `boolean=` Optional param for whether to decode new value.
Returns
Reference to this URI object.

code »toString ( ) ⇒ `string`

Returns
The string form of the url.

## Instance Properties

code »domain_ : `string`

Domain part, e.g. "www.google.com".

code »fragment_ : `string`

The fragment without the #.

code »ignoreCase_ : `boolean`

Whether or not to ignore case when comparing query params.

code »isReadOnly_ : `boolean`

Whether or not this Uri should be treated as Read Only.

code »path_ : `string`

Path, e.g. "/tests/img.png".

code »port_ : `?number`

Port, e.g. 8080.

code »queryData_ : `!goog.Uri.QueryData`

Object representing query data.

code »scheme_ : `string`

Scheme such as "http".

code »userInfo_ : `string`

User credentials in the form "username:password".

## Static Functions

code »goog.Uri.create ( opt_scheme, opt_userInfo, opt_domain, opt_port, opt_path, opt_query, opt_fragment, opt_ignoreCase ) ⇒ `!goog.Uri`

Creates a new goog.Uri object from unencoded parts.

Parameters
opt_scheme: `?string=` Scheme/protocol or full URI to parse. opt_userInfo: `?string=` username:password. opt_domain: `?string=` www.google.com. opt_port: `?number=` 9830. opt_path: `?string=` /some/path/to/a/file.html. opt_query: `(string|goog.Uri.QueryData)=` a=1&b=2. opt_fragment: `?string=` The fragment without the #. opt_ignoreCase: `boolean=` Whether to ignore parameter name case in #getParameterValue.
Returns
The new URI object.

code »goog.Uri.decodeOrEmpty_ ( val, opt_preserveReserved ) ⇒ `string`

Decodes a value or returns the empty string if it isn't defined or empty.

Parameters
val: `(string|undefined)` Value to decode. opt_preserveReserved: `boolean=` If true, restricted characters will not be decoded.
Returns
Decoded value.

code »goog.Uri.encodeChar_ ( ch ) ⇒ `string`

Converts a character in [\01-\177] to its unicode character equivalent.

Parameters
ch: `string` One character string.
Returns
Encoded string.

code »goog.Uri.encodeSpecialChars_ ( unescapedPart, extra, opt_removeDoubleEncoding ) ⇒ `?string`

If unescapedPart is non null, then escapes any characters in it that aren't valid characters in a url and also escapes any special characters that appear in extra.

Parameters
unescapedPart: `*` The string to encode. extra: `RegExp` A character set of characters in [\01-\177]. opt_removeDoubleEncoding: `boolean=` If true, remove double percent encoding.
Returns
null iff unescapedPart == null.

code »goog.Uri.haveSameDomain ( uri1String, uri2String ) ⇒ `boolean`

Checks whether two URIs have the same domain.

Parameters
uri1String: `string` First URI string. uri2String: `string` Second URI string.
Returns
true if the two URIs have the same domain; false otherwise.

code »goog.Uri.parse ( uri, opt_ignoreCase ) ⇒ `!goog.Uri`

Creates a uri from the string form. Basically an alias of new goog.Uri(). If a Uri object is passed to parse then it will return a clone of the object.

Parameters
uri: `*` Raw URI string or instance of Uri object. opt_ignoreCase: `boolean=` Whether to ignore the case of parameter names in #getParameterValue.
Returns
The new URI object.

code »goog.Uri.removeDotSegments ( path ) ⇒ `string`

Removes dot segments in given path component, as described in RFC 3986, section 5.2.4.

Parameters
path: `string` A non-empty path component.
Returns
Path component with removed dot segments.

code »goog.Uri.removeDoubleEncoding_ ( doubleEncodedString ) ⇒ `string`

Removes double percent-encoding from a string.

Parameters
doubleEncodedString: `string` String
Returns
String with double encoding removed.

code »goog.Uri.resolve ( base, rel ) ⇒ `!goog.Uri`

Resolves a relative Uri against a base Uri, accepting both strings and Uri objects.

Parameters
base: `*` Base Uri. rel: `*` Relative Uri.
Returns
Resolved uri.

## Static Properties

code »goog.Uri.RANDOM_PARAM : `string`

Parameter name added to stop caching.

code »goog.Uri.preserveParameterTypesCompatibilityFlag : `boolean`

If true, we preserve the type of query parameters set programmatically. This means that if you set a parameter to a boolean, and then call getParameterValue, you will get a boolean back. If false, we will coerce parameters to strings, just as they would appear in real URIs. TODO(nicksantos): Remove this once people have time to fix all tests.

code »goog.Uri.reDisallowedInAbsolutePath_ : `RegExp`

Regular expression for characters that are disallowed in an absolute path.

code »goog.Uri.reDisallowedInFragment_ : `RegExp`

Regular expression for characters that are disallowed in the fragment.

code »goog.Uri.reDisallowedInQuery_ : `RegExp`

Regular expression for characters that are disallowed in the query.

code »goog.Uri.reDisallowedInRelativePath_ : `RegExp`

Regular expression for characters that are disallowed in a relative path. Colon is included due to RFC 3986 3.3.

code »goog.Uri.reDisallowedInSchemeOrUserInfo_ : `RegExp`

Regular expression for characters that are disallowed in the scheme or userInfo part of the URI.