From 0960c3d1e459a1e5aeeae1cc0f86952f2aa47eea Mon Sep 17 00:00:00 2001
From: Daniel Lemire <daniel@lemire.me>
Date: Thu, 30 Jan 2025 13:44:28 -0500
Subject: [PATCH] why are our examples so complicated?

---
 README.md             | 20 ++++++++++----------
 tests/basic_tests.cpp | 22 ++++++++++++++++++++++
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 91f9e0404..17d4184c7 100644
--- a/README.md
+++ b/README.md
@@ -131,7 +131,7 @@ components (path, host, and so forth).
 - Parse and validate a URL from an ASCII or a valid UTF-8 string.
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 if (url) { /* URL is valid */ }
 ```
 
@@ -140,14 +140,14 @@ accessing it when you are not sure that it will succeed. The following
 code is unsafe:
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("some bad url");
+auto url = ada::parse("some bad url");
 url->get_href();
 ```
 
 You should do...
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("some bad url");
+auto url = ada::parse("some bad url");
 if(url) {
   // next line is now safe:
   url->get_href();
@@ -165,7 +165,7 @@ UTF-8 strings.
 - Get/Update credentials
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_username("username");
 url->set_password("password");
 // ada->get_href() will return "https://username:password@www.google.com/"
@@ -174,7 +174,7 @@ url->set_password("password");
 - Get/Update Protocol
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_protocol("wss");
 // url->get_protocol() will return "wss:"
 // url->get_href() will return "wss://www.google.com/"
@@ -183,7 +183,7 @@ url->set_protocol("wss");
 - Get/Update host
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_host("github.com");
 // url->get_host() will return "github.com"
 // you can use `url.set_hostname` depending on your usage.
@@ -192,7 +192,7 @@ url->set_host("github.com");
 - Get/Update port
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_port("8080");
 // url->get_port() will return "8080"
 ```
@@ -200,7 +200,7 @@ url->set_port("8080");
 - Get/Update pathname
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_pathname("/my-super-long-path")
 // url->get_pathname() will return "/my-super-long-path"
 ```
@@ -208,7 +208,7 @@ url->set_pathname("/my-super-long-path")
 - Get/Update search/query
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_search("target=self");
 // url->get_search() will return "?target=self"
 ```
@@ -216,7 +216,7 @@ url->set_search("target=self");
 - Get/Update hash/fragment
 
 ```cpp
-ada::result<ada::url_aggregator> url = ada::parse<ada::url_aggregator>("https://www.google.com");
+auto url = ada::parse("https://www.google.com");
 url->set_hash("is-this-the-real-life");
 // url->get_hash() will return "#is-this-the-real-life"
 ```
diff --git a/tests/basic_tests.cpp b/tests/basic_tests.cpp
index f67b44639..74046ae6f 100644
--- a/tests/basic_tests.cpp
+++ b/tests/basic_tests.cpp
@@ -94,6 +94,12 @@ TYPED_TEST(basic_tests, readme) {
   SUCCEED();
 }
 
+TYPED_TEST(basic_tests, readmefree) {
+  auto url = ada::parse("https://www.google.com");
+  ASSERT_TRUE(bool(url));
+  SUCCEED();
+}
+
 TYPED_TEST(basic_tests, readme2) {
   auto url = ada::parse<TypeParam>("https://www.google.com");
   url->set_username("username");
@@ -102,6 +108,14 @@ TYPED_TEST(basic_tests, readme2) {
   SUCCEED();
 }
 
+TYPED_TEST(basic_tests, readme2free) {
+  auto url = ada::parse("https://www.google.com");
+  url->set_username("username");
+  url->set_password("password");
+  ASSERT_EQ(url->get_href(), "https://username:password@www.google.com/");
+  SUCCEED();
+}
+
 TYPED_TEST(basic_tests, readme3) {
   auto url = ada::parse<TypeParam>("https://www.google.com");
   ASSERT_EQ(url->set_protocol("wss"), true);
@@ -110,6 +124,14 @@ TYPED_TEST(basic_tests, readme3) {
   SUCCEED();
 }
 
+TYPED_TEST(basic_tests, readme3free) {
+  auto url = ada::parse("https://www.google.com");
+  ASSERT_EQ(url->set_protocol("wss"), true);
+  ASSERT_EQ(url->get_protocol(), "wss:");
+  ASSERT_EQ(url->get_href(), "wss://www.google.com/");
+  SUCCEED();
+}
+
 TYPED_TEST(basic_tests, set_protocol_should_return_false_sometimes) {
   auto url = ada::parse<TypeParam>("file:");
   ASSERT_EQ(url->set_protocol("https"), false);