The reordering methods are a bit of a mess

[Manishearth]

I've improved the docs in #105 but I think our API surface for reordering is kinda bad.

We have the following APIs (I recommend going through the docs in #105 as well if it's not been landed and published):

• reordered_levels() and reordered_levels_per_char() which run L1
  • These are misnomers: they do not reorder the levels, rather they prepare the levels for reordering
  • Note that before Run reordering conformance tests, more docs for reordering, fix bug #105 these APIs were running L2 code from visual_runs() and then discarding it
• reorder_visual(), which runs L2.
  • Returns a visual-to-logical map given a list of levels. This matches a similar API exposed by ICU4C for people who want to manage their own levels.
  • The corresponding ICU4C API is used by skia; this is actually useful even though it may seem like a weird slice of the API. In particular, you can do things like feeding it a list of levels after you have collapsed down combining chars for L3.
  • A tricky thing about this is that it will happily reorder within byte indices if it has been fed byte indices.
• visual_runs().
  • Logically, this is the combination of reordered_levels_per_char() and reorder_visual(), except instead of returning a visual-to-logical map, it returns a vector of level runs in visual order
  • It makes some sense for this API to not return a visual-to-logical map since a visual-to-logical map that reorders every byte will be bad. Level runs are in general a very useful API for this since callers can handle L3 (combining chars) themselves.
  • However it still kind of makes sense to be able to get such a map at a per-character level.
• reorder_line(), which returns a line reordered char-by-char according to the result of visual_runs().
  • This can be misleading since it does not handle L3 (combining chars) or L4 (mirroring), so it'll produce a weird string with combining characters in the wrong place.
  • I'm not actually sure if this API makes sense at all: this crate makes the sensible decision to defer L3 and L4 to the caller engine (since it's entangled with engine-specific concerns), but this is a convenience API for reordering which goes straight-to-user.

Concrete issues:

• reorder_visual() produces a map, some visual_runs() produces a list of level runs. This feels inconsistent.
• reorder_visual() and visual_runs() do similar things but have very different names
• reordered_levels() doesn't actually reorder anything.
• reorder_line() is potentially useless

I think it might be worth doing a holistic overhaul of these after figuring out use cases, and deprecating the old APIs. I'm not particularly fond of the API surface of ICU4C either, I've always found it confusing.

cc @mbrubeck @sffc and maybe @markusicu