} map An object where keys
* are URI-encoded parameter keys, and the values are arbitrary types
* or arrays. Keys with a null value are dropped.
* @return {string} The encoded query string, in the form 'a=1&b=2'.
*/
goog.uri.utils.buildQueryDataFromMap = function(map) {
var params = [];
for (var key in map) {
goog.uri.utils.appendKeyValuePairs_(key, map[key], params);
}
return params.join('&');
};
/**
* 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.
*
* @param {string} uri The original URI, which may already have query data.
* @param {...(goog.uri.utils.QueryArray|goog.uri.utils.QueryValue)}
* var_args
* An array or argument list conforming to goog.uri.utils.QueryArray.
* @return {string} The URI with all query parameters added.
*/
goog.uri.utils.appendParams = function(uri, var_args) {
var queryData = arguments.length == 2 ?
goog.uri.utils.buildQueryData(arguments[1], 0) :
goog.uri.utils.buildQueryData(arguments, 1);
return goog.uri.utils.appendQueryDataToUri_(uri, queryData);
};
/**
* Appends query parameters from a map.
*
* @param {string} uri The original URI, which may already have query data.
* @param {!Object} map An object where keys are
* URI-encoded parameter keys, and the values are arbitrary types or arrays.
* Keys with a null value are dropped.
* @return {string} The new parameters.
*/
goog.uri.utils.appendParamsFromMap = function(uri, map) {
var queryData = goog.uri.utils.buildQueryDataFromMap(map);
return goog.uri.utils.appendQueryDataToUri_(uri, queryData);
};
/**
* 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.
*
* @param {string} uri The original URI, which may already have query data.
* @param {string} key The key, which must already be URI encoded.
* @param {*=} 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.
* @return {string} The URI with the query parameter added.
*/
goog.uri.utils.appendParam = function(uri, key, opt_value) {
var value = goog.isDefAndNotNull(opt_value) ?
'=' + goog.string.urlEncode(opt_value) :
'';
return goog.uri.utils.appendQueryDataToUri_(uri, key + value);
};
/**
* Finds the next instance of a query parameter with the specified name.
*
* Does not instantiate any objects.
*
* @param {string} uri The URI to search. May contain a fragment identifier
* if opt_hashIndex is specified.
* @param {number} startIndex The index to begin searching for the key at. A
* match may be found even if this is one character after the ampersand.
* @param {string} keyEncoded The URI-encoded key.
* @param {number} hashOrEndIndex 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.
* @return {number} The position of the first character in the key's name,
* immediately after either a question mark or a dot.
* @private
*/
goog.uri.utils.findParam_ = function(
uri, startIndex, keyEncoded, hashOrEndIndex) {
var index = startIndex;
var keyLength = keyEncoded.length;
// Search for the key itself and post-filter for surronuding punctuation,
// rather than expensively building a regexp.
while ((index = uri.indexOf(keyEncoded, index)) >= 0 &&
index < hashOrEndIndex) {
var precedingChar = uri.charCodeAt(index - 1);
// Ensure that the preceding character is '&' or '?'.
if (precedingChar == goog.uri.utils.CharCode_.AMPERSAND ||
precedingChar == goog.uri.utils.CharCode_.QUESTION) {
// Ensure the following character is '&', '=', '#', or NaN
// (end of string).
var followingChar = uri.charCodeAt(index + keyLength);
if (!followingChar || followingChar == goog.uri.utils.CharCode_.EQUAL ||
followingChar == goog.uri.utils.CharCode_.AMPERSAND ||
followingChar == goog.uri.utils.CharCode_.HASH) {
return index;
}
}
index += keyLength + 1;
}
return -1;
};
/**
* Regular expression for finding a hash mark or end of string.
* @type {RegExp}
* @private
*/
goog.uri.utils.hashOrEndRe_ = /#|$/;
/**
* Determines if the URI contains a specific key.
*
* Performs no object instantiations.
*
* @param {string} uri The URI to process. May contain a fragment
* identifier.
* @param {string} keyEncoded The URI-encoded key. Case-sensitive.
* @return {boolean} Whether the key is present.
*/
goog.uri.utils.hasParam = function(uri, keyEncoded) {
return goog.uri.utils.findParam_(
uri, 0, keyEncoded, uri.search(goog.uri.utils.hashOrEndRe_)) >= 0;
};
/**
* Gets the first value of a query parameter.
* @param {string} uri The URI to process. May contain a fragment.
* @param {string} keyEncoded The URI-encoded key. Case-sensitive.
* @return {?string} The first value of the parameter (URI-decoded), or null
* if the parameter is not found.
*/
goog.uri.utils.getParamValue = function(uri, keyEncoded) {
var hashOrEndIndex = uri.search(goog.uri.utils.hashOrEndRe_);
var foundIndex =
goog.uri.utils.findParam_(uri, 0, keyEncoded, hashOrEndIndex);
if (foundIndex < 0) {
return null;
} else {
var endPosition = uri.indexOf('&', foundIndex);
if (endPosition < 0 || endPosition > hashOrEndIndex) {
endPosition = hashOrEndIndex;
}
// Progress forth to the end of the "key=" or "key&" substring.
foundIndex += keyEncoded.length + 1;
// Use substr, because it (unlike substring) will return empty string
// if foundIndex > endPosition.
return goog.string.urlDecode(
uri.substr(foundIndex, endPosition - foundIndex));
}
};
/**
* Gets all values of a query parameter.
* @param {string} uri The URI to process. May contain a fragment.
* @param {string} keyEncoded The URI-encoded key. Case-sensitive.
* @return {!Array} All URI-decoded values with the given key.
* If the key is not found, this will have length 0, but never be null.
*/
goog.uri.utils.getParamValues = function(uri, keyEncoded) {
var hashOrEndIndex = uri.search(goog.uri.utils.hashOrEndRe_);
var position = 0;
var foundIndex;
var result = [];
while ((foundIndex = goog.uri.utils.findParam_(
uri, position, keyEncoded, hashOrEndIndex)) >= 0) {
// Find where this parameter ends, either the '&' or the end of the
// query parameters.
position = uri.indexOf('&', foundIndex);
if (position < 0 || position > hashOrEndIndex) {
position = hashOrEndIndex;
}
// Progress forth to the end of the "key=" or "key&" substring.
foundIndex += keyEncoded.length + 1;
// Use substr, because it (unlike substring) will return empty string
// if foundIndex > position.
result.push(
goog.string.urlDecode(uri.substr(foundIndex, position - foundIndex)));
}
return result;
};
/**
* Regexp to find trailing question marks and ampersands.
* @type {RegExp}
* @private
*/
goog.uri.utils.trailingQueryPunctuationRe_ = /[?&]($|#)/;
/**
* Removes all instances of a query parameter.
* @param {string} uri The URI to process. Must not contain a fragment.
* @param {string} keyEncoded The URI-encoded key.
* @return {string} The URI with all instances of the parameter removed.
*/
goog.uri.utils.removeParam = function(uri, keyEncoded) {
var hashOrEndIndex = uri.search(goog.uri.utils.hashOrEndRe_);
var position = 0;
var foundIndex;
var buffer = [];
// Look for a query parameter.
while ((foundIndex = goog.uri.utils.findParam_(
uri, position, keyEncoded, hashOrEndIndex)) >= 0) {
// Get the portion of the query string up to, but not including, the ?
// or & starting the parameter.
buffer.push(uri.substring(position, foundIndex));
// Progress to immediately after the '&'. If not found, go to the end.
// Avoid including the hash mark.
position = Math.min(
(uri.indexOf('&', foundIndex) + 1) || hashOrEndIndex, hashOrEndIndex);
}
// Append everything that is remaining.
buffer.push(uri.substr(position));
// Join the buffer, and remove trailing punctuation that remains.
return buffer.join('').replace(
goog.uri.utils.trailingQueryPunctuationRe_, '$1');
};
/**
* 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.
*
* @param {string} uri The original URI, which may already have query data.
* @param {string} keyEncoded The key, which must already be URI encoded.
* @param {*} value The value, which will be stringized and encoded (assumed
* not already to be encoded).
* @return {string} The URI with the query parameter added.
*/
goog.uri.utils.setParam = function(uri, keyEncoded, value) {
return goog.uri.utils.appendParam(
goog.uri.utils.removeParam(uri, keyEncoded), keyEncoded, value);
};
/**
* 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.
*
* @param {string} uri The URI to process.
* @param {!Object} params A list of
* parameters to update. If null or undefined, the param will be removed.
* @return {string} An updated URI where the query data has been updated with
* the params.
*/
goog.uri.utils.setParamsFromMap = function(uri, params) {
var parts = goog.uri.utils.splitQueryData_(uri);
var queryData = parts[1];
var buffer = [];
if (queryData) {
goog.array.forEach(queryData.split('&'), function(pair) {
var indexOfEquals = pair.indexOf('=');
var name = indexOfEquals >= 0 ? pair.substr(0, indexOfEquals) : pair;
if (!params.hasOwnProperty(name)) {
buffer.push(pair);
}
});
}
parts[1] = goog.uri.utils.appendQueryData_(
buffer.join('&'), goog.uri.utils.buildQueryDataFromMap(params));
return goog.uri.utils.joinQueryData_(parts);
};
/**
* 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.
*
* @param {string} baseUri URI to use as the base.
* @param {string} path Path to append.
* @return {string} Updated URI.
*/
goog.uri.utils.appendPath = function(baseUri, path) {
goog.uri.utils.assertNoFragmentsOrQueries_(baseUri);
// Remove any trailing '/'
if (goog.string.endsWith(baseUri, '/')) {
baseUri = baseUri.substr(0, baseUri.length - 1);
}
// Remove any leading '/'
if (goog.string.startsWith(path, '/')) {
path = path.substr(1);
}
return goog.string.buildString(baseUri, '/', path);
};
/**
* Replaces the path.
* @param {string} uri URI to use as the base.
* @param {string} path New path.
* @return {string} Updated URI.
*/
goog.uri.utils.setPath = function(uri, path) {
// Add any missing '/'.
if (!goog.string.startsWith(path, '/')) {
path = '/' + path;
}
var parts = goog.uri.utils.split(uri);
return goog.uri.utils.buildFromEncodedParts(
parts[goog.uri.utils.ComponentIndex.SCHEME],
parts[goog.uri.utils.ComponentIndex.USER_INFO],
parts[goog.uri.utils.ComponentIndex.DOMAIN],
parts[goog.uri.utils.ComponentIndex.PORT], path,
parts[goog.uri.utils.ComponentIndex.QUERY_DATA],
parts[goog.uri.utils.ComponentIndex.FRAGMENT]);
};
/**
* Standard supported query parameters.
* @enum {string}
*/
goog.uri.utils.StandardQueryParam = {
/** Unused parameter for unique-ifying. */
RANDOM: 'zx'
};
/**
* Sets the zx parameter of a URI to a random value.
* @param {string} uri Any URI.
* @return {string} That URI with the "zx" parameter added or replaced to
* contain a random string.
*/
goog.uri.utils.makeUnique = function(uri) {
return goog.uri.utils.setParam(
uri, goog.uri.utils.StandardQueryParam.RANDOM,
goog.string.getRandomString());
};