Review: examples

[alandefreitas]

From the review

In particular, I miss an example (and possibly a page) about composing
and mutating URLs (starting with a base URL, add some segments and query
parameters, emphasizing on when percent encoding gets applied).
This is a pretty typical task when you're consuming a third party
REST API.

I'd add a page and an example on percent encoding functions, as they
are only explained in the reference and the explanation assumes
familiarity with the CharSet concept.

Comments

I would find this useful (this builds a QR code using Google's
Infographic API):

#include <boost/url.hpp>
#include <iostream>

using namespace boost::urls;

int
main(int argc, char **argv)
{
url u ("https://chart.googleapis.com/");
u.segments().insert(u.segments().end(), "charts");
u.params().append("cht", "qr");
u.params().append("chs", "600x600");
u.params().append("chs", argv[1]);

std::cout << u << std::endl;
}

small examples may be
even more useful to newcomers.
Having this would have saved me some
time when coding my use case.

[vinniefalco]

I would like to see if we can find many examples of specs for building URIs for APIs - like this one for Google's QR code thingy. We could combine them into one big example program with a command-line driver or we could just make each of them their own tiny program like the one above.

[sehe]

+1 for short examples, command line drivers with option parsing muddy the code (depending a bit on what they're used for). We can assume people know how to do that.

I think I'd like to see resolve used in that example, unless I misunderstood it's applicability and it should not be used here.

[alandefreitas]

More comments

I found resolve a bit mystifying. While I appreciate the docs not trying to
duplicate the RFC specifying what the operation means, I think it will be a big
help to have inspirational examples, like example one that I came up with a
while ago:

boost::url make_url(boost::url_view base_api, boost::url_view method) {
    assert(!method.is_path_absolute());
    assert(base_api.data()[base_api.size() - 1] == '/');

    boost::urls::error_code ec;
    boost::url              url;
    resolve(base_api, method, url, ec);
    if (ec)
        throw boost::system::system_error(ec);
    return url;
}

// example of use:
static boost::url_view const base_api{"wss://[api.binance.com/api/v3/](http://api.binance.com/api/v3/)"};

boost::url method{"depth"};
method.params().append("symbol", "BTCUSDT");

std::cout << make_url(base_api, method); // "wss://[api.binance.com/api/v3/depth?symbol=BTCUSDT](http://api.binance.com/api/v3/depth?symbol=BTCUSDT)"

[alandefreitas]

Perhaps the examples would be better when
fleshed out in long form, then linked to.

[alandefreitas]

I would recommend not to start your example page with a 700 lines
implementation of magnet links, that's super intimidating.

[alandefreitas]

Something I missed was a simple example showing that the parse functions
also accept unknown schemes like opc.tcp:// for example.

[vinniefalco]

we still need more small examples...

[alandefreitas]

I've been thinking of more examples.

Besides #165, I can't think of anything else. The binance example seems a little boring and redundant now that we have the qrcode example.

[vinniefalco]

Ask the mailing list