Botan::URI Class Reference

#include <uri.h>

Classes
class	Authority

Public Types
using	Host = Authority::Host
	A validated DNS name, or a literal IPv4 or IPv6 address.
using	HostKind = Authority::HostKind
	Tag for the alternative held by Host.

Public Member Functions
const std::optional< Authority > &	authority () const
const std::optional< std::string > &	fragment () const
std::optional< std::reference_wrapper< const Host > >	host () const
std::strong_ordering	operator<=> (const URI &other) const
bool	operator== (const URI &other) const
const std::string &	original_input () const
const std::string &	path () const
const std::optional< std::string > &	query () const
std::optional< std::string_view >	raw_authority () const
const std::string &	scheme () const

Static Public Member Functions
static std::vector< URI >	filter_scheme (std::string_view scheme, std::span< const URI > uris)
static std::optional< URI >	from_string (std::string_view raw)

Detailed Description

URI (RFC 3986 subset)

Definition at line 25 of file uri.h.

Member Typedef Documentation

Host

using Botan::URI::Host = Authority::Host

A validated DNS name, or a literal IPv4 or IPv6 address.

Definition at line 114 of file uri.h.

HostKind

using Botan::URI::HostKind = Authority::HostKind

Tag for the alternative held by Host.

Definition at line 117 of file uri.h.

Member Function Documentation

authority()

const std::optional< Authority > & Botan::URI::authority ( ) const

inline

Return the parsed URI authority, if this URI has one.

Definition at line 132 of file uri.h.

{ return m_authority; }

Referenced by from_string(), and Botan::HTTP::http_sync().

filter_scheme()

std::vector< URI > Botan::URI::filter_scheme ( std::string_view scheme, std::span< const URI > uris )

static

Return a list of URIs (possibly empty) which match the specified scheme and which contain a non-empty authority

Definition at line 367 of file uri.cpp.

                                                                                {
   std::vector<URI> results;
 
   const auto normalized_scheme = tolower_string(scheme);
 
   for(const auto& uri : uris) {
      if(uri.scheme() == normalized_scheme && uri.authority().has_value()) {
         results.push_back(uri);
      }
   }
 
   return results;
}

References scheme(), and Botan::tolower_string().

fragment()

const std::optional< std::string > & Botan::URI::fragment ( ) const

inline

The fragment component, without the leading "#". Nullopt if no "#" was present; present-but-empty distinguishes "http://h/p#" from "http://h/p".

Definition at line 168 of file uri.h.

{ return m_fragment; }

Referenced by from_string().

from_string()

std::optional< URI > Botan::URI::from_string ( std::string_view raw )

static

Parse a URI, return nullopt on failure

Definition at line 164 of file uri.cpp.

                                                    {
   // Empty string is not a valid URI
   if(raw.empty()) {
      return {};
   }
 
   // RFC 3986:
   // scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
   constexpr auto is_scheme_cont_char = CharacterValidityTable::alpha_numeric_plus("+-.");
 
   const auto is_ascii_alpha = [](char c) -> bool { return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'); };
 
   // Check the first scheme character
   if(!is_ascii_alpha(raw.front())) {
      return {};
   }
 
   // Scan the rest of the scheme
   size_t i = 1;
   while(i < raw.size() && is_scheme_cont_char(raw[i])) {
      ++i;
   }
   // Scheme wasn't followed by ':' -> invalid
   if(i >= raw.size() || raw[i] != ':') {
      return {};
   }
 
   // Canonicalize the scheme
   const std::string scheme = tolower_string(raw.substr(0, i));
 
   auto rest = raw.substr(i + 1);
 
   std::optional<Authority> parsed_authority;
   std::string_view path_query_fragment;
 
   if(rest.starts_with("//")) {
      rest.remove_prefix(2);  // Strip off the '//'
 
      // Authority runs to the first '/', '?' or '#'. The remaining is `path ? query # fragment`,
      // which is validated against the RFC 3986 character set.
      const auto end = rest.find_first_of("/?#");
      const auto authority = (end == std::string_view::npos) ? rest : rest.substr(0, end);
      path_query_fragment = (end == std::string_view::npos) ? std::string_view{} : rest.substr(end);
 
      // Parse and validate non-empty authority strings (hostname, IPv4, or IPv6 address)
      if(!authority.empty()) {
         parsed_authority = Authority::from_string(authority);
         if(!parsed_authority.has_value()) {
            return {};
         }
      }
   } else {
      path_query_fragment = rest;
   }
 
   // Validate any `path ? query # fragment` portions of the URL
   if(!validate_path_query_fragment(path_query_fragment)) {
      return {};
   }
 
   // Split into path / query / fragment. Validation above guarantees at most
   // one '#', so the first '#' is the fragment delimiter, and within the
   // pre-fragment portion the first '?' (if any) is the query delimiter.
   const auto hash = path_query_fragment.find('#');
   const auto pre_fragment =
      (hash == std::string_view::npos) ? path_query_fragment : path_query_fragment.substr(0, hash);
   std::optional<std::string> fragment;
   if(hash != std::string_view::npos) {
      fragment = std::string(path_query_fragment.substr(hash + 1));
   }
 
   const auto qmark = pre_fragment.find('?');
   const auto path = (qmark == std::string_view::npos) ? pre_fragment : pre_fragment.substr(0, qmark);
   std::optional<std::string> query;
   if(qmark != std::string_view::npos) {
      query = std::string(pre_fragment.substr(qmark + 1));
   }
 
   // Accept
   return URI(
      std::string(raw), scheme, std::move(parsed_authority), std::string(path), std::move(query), std::move(fragment));
}

References Botan::CharacterValidityTable::alpha_numeric_plus(), authority(), fragment(), Botan::URI::Authority::from_string(), path(), query(), scheme(), and Botan::tolower_string().

Referenced by Botan::AlternativeName::add_uri().

host()

std::optional< std::reference_wrapper< const Host > > Botan::URI::host ( ) const

inline

Return the parsed host, if this URI has an authority. TODO(C++26) This can return std::optional<const Host&>

Definition at line 144 of file uri.h.

                                                                 {
         return m_authority.has_value() ? std::optional<std::reference_wrapper<const Host>>(m_authority->host())
                                        : std::nullopt;
      }

operator<=>()

std::strong_ordering Botan::URI::operator<=>

(

const URI &

other

)

const

Order two URIs

Parameters

other

the URI to compare against

Returns

the ordering of this URI relative to other

Definition at line 115 of file uri.cpp.

                               =>(const URI& other) const {
   const bool has_authority = raw_authority().has_value();
   const bool other_has_authority = other.raw_authority().has_value();
 
   return std::tie(m_scheme, has_authority, m_authority, m_path, m_query, m_fragment) <=>
          std::tie(
             other.m_scheme, other_has_authority, other.m_authority, other.m_path, other.m_query, other.m_fragment);
}

References raw_authority().

operator==()

bool Botan::URI::operator==

(

const URI &

other

)

const

Compare two URIs

Parameters

other

the URI to compare against

Returns

true if the two URIs are equal

Definition at line 124 of file uri.cpp.

                                         {
   return m_scheme == other.m_scheme && raw_authority().has_value() == other.raw_authority().has_value() &&
          m_authority == other.m_authority && m_path == other.m_path && m_query == other.m_query &&
          m_fragment == other.m_fragment;
}

References raw_authority().

original_input()

const std::string & Botan::URI::original_input ( ) const

inline

The original input that was parsed.

Definition at line 173 of file uri.h.

{ return m_raw; }

Referenced by Botan::URI::Authority::from_string().

path()

const std::string & Botan::URI::path ( ) const

inline

The path component, preserved verbatim. Begins with "/" when present; empty if the parsed URI had no path (e.g. "http://example.com" or "http://example.com?q").

Definition at line 154 of file uri.h.

{ return m_path; }

Referenced by from_string(), and Botan::HTTP::http_sync().

query()

const std::optional< std::string > & Botan::URI::query ( ) const

inline

The query component, without the leading "?". Nullopt if no "?" was present; present-but-empty distinguishes "http://h/p?" from "http://h/p".

Definition at line 161 of file uri.h.

{ return m_query; }

Referenced by from_string(), and Botan::HTTP::http_sync().

raw_authority()

std::optional< std::string_view > Botan::URI::raw_authority

(

)

const

Return the raw authority component if this URI included one, including the empty string for URIs such as "ldap:///CN=...".

Definition at line 130 of file uri.cpp.

                                                     {
   const auto colon = m_raw.find(':');
   BOTAN_ASSERT_NOMSG(colon != std::string::npos);
 
   const size_t rest_offset = colon + 1;
   if(m_raw.size() < rest_offset + 2 || m_raw[rest_offset] != '/' || m_raw[rest_offset + 1] != '/') {
      return std::nullopt;
   }
 
   const size_t authority_start = rest_offset + 2;
   const auto authority_end = m_raw.find_first_of("/?#", authority_start);
   const size_t authority_len =
      (authority_end == std::string::npos) ? std::string::npos : authority_end - authority_start;
   return std::string_view(m_raw).substr(authority_start, authority_len);
}

References BOTAN_ASSERT_NOMSG.

Referenced by operator<=>(), and operator==().

scheme()

const std::string & Botan::URI::scheme ( ) const

inline

Return the scheme, lowercase normalized

Definition at line 127 of file uri.h.

{ return m_scheme; }

Referenced by filter_scheme(), from_string(), and Botan::HTTP::http_sync().

---

The documentation for this class was generated from the following files:

• src/lib/utils/uri/uri.h
• src/lib/utils/uri/uri.cpp