UniformResourceIdentification.h File Reference

#include "Stroika/Foundation/StroikaPreComp.h"
#include <compare>
#include <string>
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Common/Compare.h"
#include "Stroika/Foundation/Containers/Mapping.h"
#include "Stroika/Foundation/IO/Network/InternetAddress.h"
#include "Stroika/Foundation/IO/Network/Port.h"
#include "UniformResourceIdentification.inl"

Go to the source code of this file.

Classes
class	Stroika::Foundation::IO::Network::UniformResourceIdentification::SchemeType
class	Stroika::Foundation::IO::Network::UniformResourceIdentification::Host
class	Stroika::Foundation::IO::Network::UniformResourceIdentification::UserInfo
class	Stroika::Foundation::IO::Network::UniformResourceIdentification::Authority
	Authority is roughly the part of a URL where you say the hostname (and portnumber etc) - part just after //. More...
class	Stroika::Foundation::IO::Network::UniformResourceIdentification::Query
struct	Stroika::Foundation::IO::Network::UniformResourceIdentification::PCTEncodeOptions

Namespaces
namespace	Stroika::Foundation
namespace	Stroika::Foundation::IO::Network
namespace	std
	STL namespace.

Enumerations
enum class	Stroika::Foundation::IO::Network::UniformResourceIdentification::StringPCTEncodedFlag
	for some purposes, we may want to render objects PCT-encoded, and sometimes not (plain or decoded). This flag is just used to specify in some 'As<String>' APIs - which is preferred for output. The default often depends on the type being produced in the As<> method. More...

Functions
u8string	Stroika::Foundation::IO::Network::UniformResourceIdentification::PCTDecode (const u8string &s)

Detailed Description

Note

Code-Status: Release

TODO:

Definition in file UniformResourceIdentification.h.

Enumeration Type Documentation

StringPCTEncodedFlag

enum class Stroika::Foundation::IO::Network::UniformResourceIdentification::StringPCTEncodedFlag

strong

for some purposes, we may want to render objects PCT-encoded, and sometimes not (plain or decoded). This flag is just used to specify in some 'As<String>' APIs - which is preferred for output. The default often depends on the type being produced in the As<> method.

Base RFC References

Note

http://www.ietf.org/rfc/rfc1738.txt - Uniform Resource Locators (URL) - 1994 original FULL URL spec

http://tools.ietf.org/html/rfc1808 - Relative Uniform Resource Locators - 1995 original FULL URL spec

https://tools.ietf.org/html/rfc3986 - Uniform Resource Identifier (URI): Generic Syntax - 2005 Updates: 1738; Obsoletes 2732, 2396, 1808 (so combines relative and absolute)

Each RFC uses its own terminology for the parts of a URL. We the most recent of these RFCs for our primary terminology: https://tools.ietf.org/html/rfc3986#section-3.2

The generic URI syntax consists of a hierarchical sequence of
components referred to as the scheme, authority, path, query, and
fragment
...

The following are two example URIs and their component parts:

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment
   |   _____________________|__
  / \ /                        \
  urn:example:animal:ferret:nose

Empty String versus optional 'missing' !has_value

For the various optional pieces of a URL (or URI), we could represent this as
an empty string, or call the feature optional, and return nullopt.

We COULD allow for EITHER, but that would be clearly needlessly confusing.
PRO USE of optional
    o   its the normal way (since C++17) to represent that something is there, or not (string empty is a throwback
        sentinel value approach)
    o   Some objects (like port#, or authority) have formatting constraints and using optional makes
        clear that IF it exists its of the right form, and else it just doesn't exist (small point)
CONS USE of optional
    o   Backward compatibility with earlier versions of the API are a bit of a pain, as the old API used
        string and string.empty () in many places.
Performance:
    o   optional more often avoids allocating memory, but is larger, so probably a wash
Choice:
    o   API will use optional<> for sub-elements of URL and URI that may or may not be present, and
        if a string value is provided (not nullopt) - then it MUST be a legal value (not empty typically).
        So, for example, Authority.Get/SetUserInfo () - MUST be either nullopt or a non-empty string.
    o   Exception - because the https://tools.ietf.org/html/rfc3986#page-11 explicitly says the path is not optional

        "A path is always defined for a URI, though the defined path may be empty (zero length)"

        So the Path in Stroika does not use optional.

Note

As () versus AsEncoded () versus AsDecoded () Some objects (like Host, or UserInfo) make sense to access in either encoded or decoded form. Other objects, like an Authority, or URI, really don't make sense except in ENCODED form (because you couldn't parse out the pieces to get back to the original). So - for objects where it makes sense to access either way, we provide AsEncoded/AsDecoded methods, and for objects that really require the string form to be encoded - we just call that As<>.

One SLIGHT exception is the ToString() method, which is just for debugging, and there we emit what will be easier/better for debugging, and don't worry about reversibility.

See also

also StringPCTEncodedFlag flag

Note

- SEE http://stroika-bugs.sophists.com/browse/STK-1000 – issue about maybe needed more nuanced approach PERHAPS add another flag eDecodedUNICODEButEncodeSOMETUFFNeededToUnparseDisambiguate (not sure that ever happens)? (OK - I do have an example - the # character - and maybe sometimes ? character??? - (# in query for example - comes before fragment).

Definition at line 116 of file UniformResourceIdentification.h.

Function Documentation

PCTDecode()

u8string Stroika::Foundation::IO::Network::UniformResourceIdentification::PCTDecode

(

const u8string &

s

)

PCTDecode2String () takes the result of PCTDecode, and treats it as UTF8 text, and converts a String from that.

Definition at line 528 of file UniformResourceIdentification.cpp.