adding .setSearch() - fix #64

README.md

@@ -207,6 +207,8 @@ URI.js is published under the [MIT license](http://www.opensource.org/licenses/m
 
 ## Changelog ##
 
+* adding [`.setQuery()`](http://medialize.github.com/URI.js/docs.html#search-set) - ([Issue #64](https://github.com/medialize/URI.js/issues/64))
+
 ### 1.8.3 (January 9th 2013) ###
 
 * fixing [UglifyJS2](https://github.com/mishoo/UglifyJS2) compression - ([Issue #60](https://github.com/medialize/URI.js/issues/60), [fidian](https://github.com/fidian))

docs.html

@@ -81,6 +81,7 @@ <h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1>
             Working with the query string
             <ul>
                 <li><a href="#accessors-search">search(), query()</a></li>
+                <li><a href="#search-set">setSearch(), setQuery()</a></li>
                 <li><a href="#search-add">addSearch(), addQuery()</a></li>
                 <li><a href="#search-remove">removeSearch(), removeQuery()</a></li>
             </ul>
@@ -576,6 +577,24 @@ <h3 id="is">is()</h3>
 
     <h2 id="querystrings">Working with the query string</h2>
 
+    <h3 id="search-set">setSearch(), setQuery()</h3>
+    <p>.setQuery() is an alias of .setSearch()</p>
+    <pre class="prettyprint lang-js">var uri = new URI("?hello=world");
+uri.setSearch("hello", "mars"); // returns the URI instance for chaining
+// uri == "?hello=mars"
+
+uri.setSearch({ foo: "bar", goodbye : ["world", "mars"] });
+// uri == "?hello=mars&amp;foo=bar&amp;goodbye=world&amp;goodbye=mars"
+
+uri.setSearch("goodbye", "sun");
+// uri == "?hello=mars&amp;foo=bar&amp;goodbye=sun"
+
+// CAUTION: beware of arrays, the following are not quite the same
+// If you're dealing with PHP, you probably want the latter…
+uri.setSearch("foo", ["bar", "baz"]);
+uri.setSearch("foo[]", ["bar", "baz"]);</pre>
+    <p>Note that names and values passed in are encoded automatically.</p>
+
     <h3 id="search-add">addSearch(), addQuery()</h3>
     <p>.addQuery() is an alias of .addSearch()</p>
     <pre class="prettyprint lang-js">var uri = new URI("?hello=world");

src/URI.js

@@ -1242,6 +1242,29 @@ p.query = function(v, build) {
         return q.call(this, v, build);
     }
 };
+p.setQuery = function(name, value, build) {
+    var data = URI.parseQuery(this._parts.query);
+
+    if (typeof name === "object") {
+        for (var key in name) {
+            if (hasOwn.call(name, key)) {
+                data[key] = name[key];
+            }
+        }
+    } else if (typeof name === "string") {
+        data[name] = value !== undefined ? value : null;
+    } else {
+        throw new TypeError("URI.addQuery() accepts an object, string as the name parameter");
+    }
+
+    this._parts.query = URI.buildQuery(data, this._parts.duplicateQueryParameters);
+    if (typeof name !== "string") {
+        build = value;
+    }
+
+    this.build(!build);
+    return this;
+};
 p.addQuery = function(name, value, build) {
     var data = URI.parseQuery(this._parts.query);
     URI.addQuery(data, name, value === undefined ? null : value);
@@ -1264,6 +1287,7 @@ p.removeQuery = function(name, value, build) {
     this.build(!build);
     return this;
 };
+p.setSearch = p.setQuery;
 p.addSearch = p.addQuery;
 p.removeSearch = p.removeQuery;
 

test/test.js

@@ -553,6 +553,38 @@ test("mutating object", function() {
     u.query(q);
     equal(u.query(), 'something=new&something=and&something=funky', "removing array");
 });
+test("addQuery", function() {
+    var u = URI('?foo=bar');
+    u.setQuery('foo', 'bam');
+    equal(u.query(), 'foo=bam', "set name, value");
+
+    u.setQuery('array', ['one', 'two']);
+    equal(u.query(), 'foo=bam&array=one&array=two', "set name, array");
+
+    u.query('?foo=bar');
+    u.setQuery({'obj': 'bam', foo: "baz"});
+    equal(u.query(), 'foo=baz&obj=bam', "set {name: value}");
+
+    u.setQuery({'foo': 'foo', bar: ['1', '2']});
+    equal(u.query(), 'foo=foo&obj=bam&bar=1&bar=2', "set {name: array}");
+
+    u.query('?foo=bar');
+    u.setQuery({'bam': null, 'baz': ''});
+    equal(u.query(), 'foo=bar&bam&baz=', "set {name: null}");
+
+    u.query('?foo=bar');
+    u.setQuery('empty');
+    equal(u.query(), 'foo=bar&empty', "set undefined");
+
+    u.query('?foo=bar');
+    u.setQuery('empty', "");
+    equal(u.query(), 'foo=bar&empty=', "set empty string");
+
+    u.query('');
+    u.setQuery('some value', "must be encoded because of = and ? and #");
+    equal(u.query(), 'some+value=must+be+encoded+because+of+%3D+and+%3F+and+%23', "encoding");
+    equal(u.query(true)['some value'], "must be encoded because of = and ? and #", "decoding");
+});
 test("addQuery", function() {
     var u = URI('?foo=bar');
     u.addQuery('baz', 'bam');