On 9/06/2022 14:57, Vinnie Falco wrote:
Right, if you want to treat the path (or query) as a single unit then the corresponding members of url_view and url are used (those in the aqua and lavender boxes). However if you want to deal with the path as a const or modifiable range of segments then you use the containers returned by the functions encoded_segments() or segments().
The [encoded_]segments view is *technically* illegal for non-URL URIs (or at least non-sensible), though I suppose there's no particular harm if you just don't use it (or only use it if the data format happens to coincidentally be slash-separated, assuming it won't add stray leading slashes).
Functions with the word "set" are mutating, otherwise they are not. Functions with the word "encoded" always return percent-encoded strings. This is how things are stored natively. We should add this somewhere to the docs if it is not already there/
It would be nice to explicitly call out that the "encoded" form is the original unmodified text (and not, for example, parsed and then re-encoded). I've only really skimmed the docs at this point so I certainly might have overlooked that, but what I saw seemed to imply this but didn't really state it explicitly.
The Reference Card assumes some familiarity with the library and consolidates the bulk of the APIs of the library into one page for convenience. I'm experimenting with some new documentation ideas.
There's an example of an URN being parsed to scheme and path in the RFC; it might be nice to add that (or perhaps a mailto:) to your diagram for clarity. Although perhaps also including query and fragment parts too, since those are legal parts of the grammar.