Class goog.Uri

code »

This class contains setters and getters for the parts of the URI. The getXyz/setXyz methods return the decoded part -- sogoog.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:PublicProtectedPrivate

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.