Re: Boost.URL -- some notes

From: Gavin Lambert (boost_at_[hidden])
Date: 2022-06-09 03:31:24

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.