document better our UTF-8 expectations. (#871)

Author: lemire

include/ada/url_pattern.h

@@ -189,6 +189,8 @@ class url_pattern_component {
   bool has_regexp_groups = false;
 };
 
+// A URLPattern input can be either a string or a URLPatternInit object.
+// If it is a string, it must be a valid UTF-8 string.
 using url_pattern_input = std::variant<std::string_view, url_pattern_init>;
 
 // A struct providing the URLPattern matching results for all
@@ -221,19 +223,24 @@ struct url_pattern_options {
 // defined in https://wicg.github.io/urlpattern.
 // More information about the URL Pattern syntax can be found at
 // https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API
+//
+// We require all strings to be valid UTF-8: it is the user's responsibility
+// to ensure that the provided strings are valid UTF-8.
 template <url_pattern_regex::regex_concept regex_provider>
 class url_pattern {
  public:
   url_pattern() = default;
 
   /**
+   * If non-null, base_url must pointer at a valid UTF-8 string.
    * @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-exec
    */
   result<std::optional<url_pattern_result>> exec(
       const url_pattern_input& input,
       const std::string_view* base_url = nullptr);
 
   /**
+   * If non-null, base_url must pointer at a valid UTF-8 string.
    * @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-test
    */
   result<bool> test(const url_pattern_input& input,

include/ada/url_pattern_init.h

@@ -32,7 +32,9 @@ concept url_pattern_encoding_callback = requires(F f, std::string_view sv) {
 // either a string or a URLPatternInit struct. If a string is given,
 // it will be parsed to create a URLPatternInit. The URLPatternInit
 // API is defined as part of the URLPattern specification.
+// All provided strings must be valid UTF-8.
 struct url_pattern_init {
+  // All strings must be valid UTF-8.
   // @see https://urlpattern.spec.whatwg.org/#process-a-urlpatterninit
   static tl::expected<url_pattern_init, errors> process(
       url_pattern_init init, std::string_view type,
@@ -92,15 +94,23 @@ struct url_pattern_init {
 #endif  // ADA_TESTING
 
   bool operator==(const url_pattern_init&) const;
-
+  // If present, must be valid UTF-8.
   std::optional<std::string> protocol{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> username{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> password{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> hostname{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> port{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> pathname{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> search{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> hash{};
+  // If present, must be valid UTF-8.
   std::optional<std::string> base_url{};
 };
 }  // namespace ada

include/ada/url_search_params-inl.h

@@ -162,6 +162,7 @@ inline void url_search_params::remove(const std::string_view key,
 }
 
 inline void url_search_params::sort() {
+  // We rely on the fact that the content is valid UTF-8.
   std::ranges::stable_sort(params, [](const key_value_pair &lhs,
                                       const key_value_pair &rhs) {
     size_t i = 0, j = 0;

include/ada/url_search_params.h

@@ -33,6 +33,8 @@ using url_search_params_entries_iter =
                            url_search_params_iter_type::ENTRIES>;
 
 /**
+ * We require all strings to be valid UTF-8. It is the user's responsibility to
+ * ensure that the provided strings are valid UTF-8.
  * @see https://url.spec.whatwg.org/#interface-urlsearchparams
  */
 struct url_search_params {
@@ -55,6 +57,7 @@ struct url_search_params {
   [[nodiscard]] inline size_t size() const noexcept;
 
   /**
+   * Both key and value must be valid UTF-8.
    * @see https://url.spec.whatwg.org/#dom-urlsearchparams-append
    */
   inline void append(std::string_view key, std::string_view value);
@@ -82,6 +85,7 @@ struct url_search_params {
   inline bool has(std::string_view key, std::string_view value) noexcept;
 
   /**
+   * Both key and value must be valid UTF-8.
    * @see https://url.spec.whatwg.org/#dom-urlsearchparams-set
    */
   inline void set(std::string_view key, std::string_view value);
@@ -145,6 +149,7 @@ struct url_search_params {
   std::vector<key_value_pair> params{};
 
   /**
+   * The init parameter must be valid UTF-8.
    * @see https://url.spec.whatwg.org/#concept-urlencoded-parser
    */
   void initialize(std::string_view init);