adding .segmentCoded() to provide en/decoding interface to .segment() -

closes #79

README.md

@@ -209,19 +209,20 @@ URI.js is published under the [MIT license](http://www.opensource.org/licenses/m
 
 ### `[dev-version]` (master branch) ###
 
-* optimize [`relativeTo()`](http://medialize.github.com/URI.js/docs.html#relativeto) results - ([Issue #78](https://github.com/medialize/URI.js/issues/78), [Issue #95](https://github.com/medialize/URI.js/issues/95))
+* adding [`.segmentCoded()`](http://medialize.github.com/URI.js/docs.html#accessors-segmentCoded) to provide en/decoding interface to `.segment()` - ([Issue #79](https://github.com/medialize/URI.js/issues/79))
+* optimize [`.relativeTo()`](http://medialize.github.com/URI.js/docs.html#relativeto) results - ([Issue #78](https://github.com/medialize/URI.js/issues/78), [Issue #95](https://github.com/medialize/URI.js/issues/95))
 * removing obsolete code fragments from `URI.parse()` and `relativeTo()` - ([Issue #100](https://github.com/medialize/URI.js/issues/100))
 * adding setting `URI.escapeQuerySpace` to control if query string should escape spaces using `+` or `%20` - ([Issue #74](https://github.com/medialize/URI.js/issues/74))
 * updating [Punycode.js](https://github.com/bestiejs/punycode.js/) to version 1.2.3
 * fixing internal `strictEncodeURIComponent()` to work in Firefox 3.6 - ([Issue #91](https://github.com/medialize/URI.js/issues/91))
 * fixing [`.normalizePath()`](http://medialize.github.io/URI.js/docs.html#normalize-path) to properly resolve `/.` and `/.//` to `/` - ([Issue #97](https://github.com/medialize/URI.js/issues/97))
-* fixing [`path()`](http://medialize.github.io/URI.js/docs.html#accessors-pathname) to return empty string if there is no path - ([Issue #82](https://github.com/medialize/URI.js/issues/82))
+* fixing [`.path()`](http://medialize.github.io/URI.js/docs.html#accessors-pathname) to return empty string if there is no path - ([Issue #82](https://github.com/medialize/URI.js/issues/82))
 * fixing crashing of `URI.decodeQuery()` on malformed input - now returns original undecoded data - ([Issue #87](https://github.com/medialize/URI.js/issues/87), [Issue #92](https://github.com/medialize/URI.js/issues/92))
 * fixing build tool - ([Issue #83](https://github.com/medialize/URI.js/issues/83))
 * fixing for-loop to make closure compiler happy - ([Issue #93](https://github.com/medialize/URI.js/issues/93))
 * adding [`URI.noConflict()`](http://medialize.github.io/URI.js/docs.html#static-noConflict) - ([Issue #84](https://github.com/medialize/URI.js/issue/84))
 * fixing whitespace in code - ([Issue #84](https://github.com/medialize/URI.js/issue/84))
-* fixing [`readable()`](http://medialize.github.com/URI.js/docs.html#readable) to decode the hash value as well - ([Issue #90](https://github.com/medialize/URI.js/issue/90))
+* fixing [`.readable()`](http://medialize.github.com/URI.js/docs.html#readable) to decode the hash value as well - ([Issue #90](https://github.com/medialize/URI.js/issue/90))
 * prevent `jquery.URI.js from` temporarily using `window.location` as the `href` of an empty attribute of a DOM element - ([Issue #94](https://github.com/medialize/URI.js/issues/94))
 * fixing internal `getType()` for IE8 with undefined value - ([Issue #96](https://github.com/medialize/URI.js/issues/96))
 * adding DOM elements to [URI constructor](http://medialize.github.io/URI.js/docs.html#constructor) - ([Issue #77](https://github.com/medialize/URI.js/issues/77)):

docs.html

@@ -70,6 +70,7 @@ <h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1>
                 <li><a href="#accessors-filename">filename()</a></li>
                 <li><a href="#accessors-suffix">suffix()</a></li>
                 <li><a href="#accessors-segment">segment()</a></li>
+                <li><a href="#accessors-segmentCoded">segmentCoded()</a></li>
 
                 <li><a href="#accessors-search">search(), query()</a></li>
                 <li><a href="#accessors-hash">hash(), fragment()</a></li>
@@ -461,7 +462,7 @@ <h3 id="accessors-suffix">suffix()</h3>
 uri.suffix(true) === "würgh";</pre>
 
     <h3 id="accessors-segment">segment()</h3>
-    <p>.segment() allows convenient access to directory levels / URN segments within the path</p>
+    <p>.segment() allows convenient access to directory levels / URN segments within the path. See <a href="#accessors-segmentCoded">.segmentCoded()</a> for an interface that transparently encodes and decodes path segments.</p>
     <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html");
 // get segments
 uri.segment(); // returns array ["foo", "hello.html"]
@@ -477,9 +478,28 @@ <h3 id="accessors-segment">segment()</h3>
 // remove specific level
 uri.segment(0, ""); // -> http://example.org/bar/foobar.html
 
-
 // append level
 uri.segment("appendthis"); // -> http://example.org/bar/foobar.html/appendthis</pre>
+
+    <h3 id="accessors-segmentCoded">segmentCoded()</h3>
+    <p>.segmentCoded() works the same way <a href="#accessors-segment">.segment()</a> does, with the difference of transparently encoding and decoding values.</p>
+    <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello%20world.html");
+// get segments
+uri.segment(); // returns array ["foo", "hello world.html"]
+// set segments
+uri.segment(["foo", "bar", "foo bar.html"]); // -> http://example.org/foo/bar/foo%20bar.html
+
+// get specific level
+uri.segment(0); // returns "foo"
+uri.segment(1); // returns "bar"
+uri.segment(-1); // returns "foo bar.html"
+// set specific level
+uri.segment(0, "bar bam"); // -> http://example.org/bar%20bam/bar/foobar.html
+// remove specific level
+uri.segment(0, ""); // -> http://example.org/bar/foobar.html
+
+// append level
+uri.segment("append this"); // -> http://example.org/bar/foobar.html/append%20this</pre>
 
 
     <h3 id="accessors-search">search(), query()</h3>

src/URI.js

@@ -1392,7 +1392,7 @@ p.segment = function(segment, v, build) {
     var absolute = path.substring(0, 1) === '/';
     var segments = path.split(separator);
 
-    if (typeof segment !== 'number') {
+    if (segment !== undefined && typeof segment !== 'number') {
         build = v;
         v = segment;
         segment = undefined;
@@ -1441,6 +1441,38 @@ p.segment = function(segment, v, build) {
 
     return this.path(segments.join(separator), build);
 };
+p.segmentCoded = function(segment, v, build) {
+    var segments, i, l;
+
+    if (typeof segment !== 'number') {
+        build = v;
+        v = segment;
+        segment = undefined;
+    }
+
+    if (v === undefined) {
+        segments = this.segment(segment, v, build);
+        if (!isArray(segments)) {
+            segments = segments !== undefined ? URI.decode(segments) : undefined;
+        } else {
+            for (i = 0, l = segments.length; i < l; i++) {
+                segments[i] = URI.decode(segments[i]);
+            }
+        }
+
+        return segments;
+    }
+
+    if (!isArray(v)) {
+        v = typeof v === 'string' ? URI.encode(v) : v;
+    } else {
+        for (i = 0, l = v.length; i < l; i++) {
+            v[i] = URI.decode(v[i]);
+        }
+    }
+
+    return this.segment(segment, v, build);
+};
 
 // mutating query string
 var q = p.query;

test/test.js

@@ -597,6 +597,27 @@ test("segment", function() {
     u.segment('test');
     equal(u.path(), "/foo/test", "segment append trailing empty");
 });
+test("segmentCoded", function() {
+    var u = new URI("http://www.example.org/some%20thing/directory/foo.html"),
+        s = u.segmentCoded();
+
+    equal(s.join('||'), "some thing||directory||foo.html", "segmentCoded get array");
+
+    u.segmentCoded(['hello world', 'mars', 'foo.html']);
+    equal(u.path(), "/hello%20world/mars/foo.html", "segmentCoded set array");
+
+    equal(u.segmentCoded(0), "hello world", "segmentCoded get 0");
+    equal(u.segmentCoded(2), "foo.html", "segmentCoded get 2");
+    equal(u.segmentCoded(3), undefined, "segmentCoded get 3");
+
+    u.segmentCoded("zapp zerapp");
+    equal(u.path(), "/hello%20world/mars/foo.html/zapp%20zerapp", "segmentCoded append");
+
+    u.segmentCoded(2, "");
+    equal(u.path(), "/hello%20world/mars/zapp%20zerapp", "segmentCoded del 3 ''");
+    u.segmentCoded(2, null);
+    equal(u.path(), "/hello%20world/mars", "segmentCoded del 3 null");
+});
 
 module("mutating query strings");
 test("mutating object", function() {