# 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.