From da402268acc5ba334c53b5b20c3ac13e2a2a66ea Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:37:26 +0100 Subject: [PATCH] doc: Merged and updated old docs for Hash#toQueryString. --- src/lang/hash.js | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 2c40203..21e2b5f 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -242,7 +242,41 @@ var Hash = Class.create(Enumerable, (function() { /** related to: String#toQueryParams * Hash#toQueryString() -> String * - * Turns a hash into its URL-encoded query string representation. + * Returns a URL-encoded string containing the hash's contents as query + * parameters according to the following rules: + * + * - An undefined value results a parameter with no value portion at all + * (simply the key name, no equal sign). + * - A null value results a parameter with a blank value (the key followed + * by an equal sign and nothing else). + * - A boolean value results a parameter with the value "true" or "false". + * - An Array value results in a parameter for each array element, in + * array order, each using the same key. + * - All keys and values are URI-encoded using JavaScript's native + * `encodeURIComponent` function. + * + * The order of pairs in the string is not guaranteed, other than the order + * of array values described above. + * + * ### Example + * + * $H({action: 'ship', + * order_id: 123, + * fees: ['f1', 'f2'] + * }).toQueryString(); + * // -> "action=ship&order_id=123&fees=f1&fees=f2" + * + * $H({comment: '', + * 'key with spaces': true, + * related_order: undefined, + * contents: null, + * 'label': 'a demo' + * }).toQueryString(); + * // -> "comment=&key%20with%20spaces=true&related_order&contents=&label=a%20demo" + * + * // an empty hash is an empty query string: + * $H().toQueryString(); + * // -> "" **/ function toQueryString() { return this.inject([], function(results, pair) {