advance() can work in backward direction.

advance() now can decrement the iterator if the number of steps to advance is negative.

README.md

@@ -321,8 +321,8 @@ void advance (octet_iterator& it, distance_type n, octet_iterator end);
 `octet_iterator`: an input iterator.  
 `distance_type`: an integral type convertible to `octet_iterator`'s difference type.  
 `it`: a reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the nth following code point.  
-`n`: a positive integer that shows how many code points we want to advance.  
-`end`: end of the UTF-8 sequence to be processed. If `it` gets equal to `end` during the extraction of a code point, an `utf8::not_enough_room` exception is thrown.  
+`n`: number of code points `it` should be advanced. A negative value means decrement.  
+`end`: limit of the UTF-8 sequence to be processed. If `n` is positive and `it` gets equal to `end` during the extraction of a code point, an `utf8::not_enough_room` exception is thrown. If `n` is negative and `it` reaches `end` while `it` points t a trail byte of a UTF-8 sequence, a `utf8::invalid_code_point` exception is thrown.
 
 Example of use:
 
@@ -331,10 +331,10 @@ char* twochars = "\xe6\x97\xa5\xd1\x88";
 unsigned char* w = twochars;
 advance (w, 2, twochars + 6);
 assert (w == twochars + 5);
+advance (w, -2, twochars);
+assert (w == twochars);
 ```
 
-This function works only "forward". In case of a negative `n`, there is no effect.
-
 In case of an invalid code point, a `utf8::invalid_code_point` exception is thrown.
 
 #### utf8::distance
@@ -1049,8 +1049,8 @@ template <typename octet_iterator, typename distance_type>
 void advance (octet_iterator& it, distance_type n);
 ```
 
-`it`: a reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the nth following code point.  
-`n`: a positive integer that shows how many code points we want to advance.  
+`it`: a reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the nth following code point.
+`n`: number of code points `it` should be advanced. A negative value means decrement.
 
 Example of use:
 
@@ -1061,8 +1061,6 @@ unchecked::advance (w, 2);
 assert (w == twochars + 5);
 ```
 
-This function works only "forward". In case of a negative `n`, there is no effect.
-
 This is a faster but less safe version of `utf8::advance`. It does not check for validity of the supplied UTF-8 sequence and offers no boundary checking.
 
 #### utf8::unchecked::distance

source/utf8/checked.h

@@ -177,8 +177,16 @@ namespace utf8
     template <typename octet_iterator, typename distance_type>
     void advance (octet_iterator& it, distance_type n, octet_iterator end)
     {
-        for (distance_type i = 0; i < n; ++i)
-            utf8::next(it, end);
+        const distance_type zero(0);
+        if (n < zero) {
+            // backward
+            for (distance_type i = n; i < zero; ++i)
+                utf8::prior(it, end);
+        } else {
+            // forward
+            for (distance_type i = zero; i < n; ++i)
+                utf8::next(it, end);
+        }
     }
 
     template <typename octet_iterator>

source/utf8/unchecked.h

@@ -105,8 +105,16 @@ namespace utf8
         template <typename octet_iterator, typename distance_type>
         void advance (octet_iterator& it, distance_type n)
         {
-            for (distance_type i = 0; i < n; ++i)
-                utf8::unchecked::next(it);
+            const distance_type zero(0);
+            if (n < zero) {
+                // backward
+                for (distance_type i = n; i < zero; ++i)
+                    utf8::unchecked::prior(it);
+            } else {
+                // forward
+                for (distance_type i = zero; i < n; ++i)
+                    utf8::unchecked::next(it);
+            }
         }
 
         template <typename octet_iterator>

test_drivers/smoke_test/test.cpp

@@ -66,9 +66,17 @@ int main()
     assert (w == threechars); 
 
     // advance
-    w = twochars;
-    advance (w, 2, twochars + 6);
-    assert (w == twochars + 5);
+    w = threechars;
+    advance(w, 2, threechars + 9);
+    assert(w == threechars + 7);
+    advance(w, -2, threechars);
+    assert(w == threechars);
+    advance(w, 3, threechars + 9);
+    assert(w == threechars + 9);
+    advance(w, -2, threechars);
+    assert(w == threechars + 4);
+    advance(w, -1, threechars);
+    assert(w == threechars);
 
     // distance
     size_t dist = utf8::distance(twochars, twochars + 5);
@@ -194,9 +202,17 @@ int main()
     assert (cw == twochars);
 
     // advance
-    w = twochars;
-    unchecked::advance (w, 2);
-    assert (w == twochars + 5);
+    w = threechars;
+    unchecked::advance(w, 2);
+    assert(w == threechars + 7);
+    unchecked::advance(w, -2);
+    assert(w == threechars);
+    unchecked::advance(w, 3);
+    assert(w == threechars + 9);
+    unchecked::advance(w, -2);
+    assert(w == threechars + 4);
+    unchecked::advance(w, -1);
+    assert(w == threechars);
 
     // distance
     dist = unchecked::distance(twochars, twochars + 5);