} The buffer argument.
* @private
*/
goog.uri.utils.buildQueryDataBufferFromMap_ = function(buffer, map) {
for (var key in map) {
goog.uri.utils.appendKeyValuePairs_(key, map[key], buffer);
}
return buffer;
};
/**
* Builds a query data string from a map.
*
* Currently generates "&key=&" for empty args; there is no way to generate
* "&key&" arguments with no equal sign.
*
* @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 encoded query string, in the for 'a=1&b=2'.
*/
goog.uri.utils.buildQueryDataFromMap = function(map) {
var buffer = goog.uri.utils.buildQueryDataBufferFromMap_([], map);
buffer[0] = '';
return buffer.join('');
};
/**
* Appends URI parameters to an existing URI.
*
* The variable arguments msay 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.
* Must not contain a fragment identifier.
* @param {string|*|Array.<*>} var_args Alternating key strings (which are
* already encoded) and values. Keys with a null or undefined value will
* be skipped entirely. Keys with a non-array value will have the values
* converted to a string, encoded, and emitted as key=value, whereas keys
* with an array value will have each element emitted as a value.
* @return {string} The URI with all query parameters added.
*/
goog.uri.utils.appendParams = function(uri, var_args) {
return goog.uri.utils.appendQueryData_(
goog.uri.utils.buildQueryDataBuffer_([uri], arguments, 1));
};
/**
* Appends query parameters from a map.
*
* @param {string} uri The original URI, which may already have query data.
* Must not contain a fragment identifier.
* @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) {
return goog.uri.utils.appendQueryData_(
goog.uri.utils.buildQueryDataBufferFromMap_([uri], map));
};
/**
* 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.
* Must not contain a fragment identifier.
* @param {string} key The key, which must already be URI encoded.
* @param {string} value The value, which should NOT be URI-encoded.
* @return {string} The URI with the query parameter added.
*/
goog.uri.utils.appendParam = function(uri, key, value) {
return goog.uri.utils.appendQueryData_(
[uri, '&', key, '=', goog.string.urlEncode(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 framgnet.
* @param {string} keyEncoded The URI-encoded key. Case-snsitive.
* @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) {
goog.uri.utils.assertNoFragments_(uri);
var length = uri.length;
var position = 0;
var foundIndex;
var buffer = [];
// Look for a query parameter.
while ((foundIndex =
goog.uri.utils.findParam_(uri, position, keyEncoded, length)) >= 0) {
// Get the portion of the query string, skipping the delimiter character
// itself.
buffer.push(uri.substring(position, foundIndex));
// Progress to immediately after the '&'. If not found, go to the end.
position = (uri.indexOf('&', foundIndex) + 1) || length;
}
// 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_, '');
};