D-Programming-Language/phobos — pull request #950 by monarchdodra (2012-11-15 17:24:48+00:00)
Title: tweaks in doc and impl

This was primarily a documentation tweak for std.utf: Certains functions, such as `stride` did not actually fully validate their input. As such, they were marked as:

"May throw a $(D UTFException)". Afterwards, in the "notes" the garantees (if any) are specified.

`decode` was specifically marked as "fully guarantees a valid sequence".

More asserts, and comments on the asserts: A commented assert is always better than an array out of range error... Also, strideBack now asserts that `index > 0`.

----
I also did a few tweaks in the implementations, in

* `strideBack(char)`:
The "ifs" were re-organized to first check if the index is higher than 4, in which case this will be the only check done. If the index is *not* higher than 4, this will not require extra ifs either, so win-win.

* `strideBack(wchar)`:
UTF-16 is "self synchronizing", so only looking at the last object is enough to know the length of the strideBack. This is faster than the current implementation. Validation is even weaker, but this does not seem to be a problem for the other forms of stride...

* `strideBack(char) For bidirectionalRange`:
Removed the calls to save: saving a range to avoid modifying it is inconsistent with the rest of phobos: It is the caller's job to pass a saved range if re-use is intended.
Furthermore, all flavors of `stride` accept only `input` range: If stride doesn't save, why should `strideBack`?

NOTE: Will squash soon.