AdaUrlHandle

public sealed class AdaUrlHandle : SafeHandle

A parsed URL that can live beyond one method: in a field, a cache, or across await. It costs one small allocation and a finalizer registration per URL. Use AdaUrl when the URL does not need to leave the method.

Dispose it. The finalizer frees the native memory if you forget, but only when the garbage collector gets to it.

Parsing

Method	On invalid input
TryParse(ReadOnlySpan<byte> utf8, out AdaUrlHandle? url)	Returns false, url is null
TryParse(ReadOnlySpan<byte> utf8, ReadOnlySpan<byte> baseUrl, out AdaUrlHandle? url)	Returns false
TryParse(ReadOnlySpan<char> input, out AdaUrlHandle? url)	Returns false, also for a lone surrogate
Parse(ReadOnlySpan<byte> utf8)	Throws FormatException

public sealed class Endpoint : IDisposable
{
    private readonly AdaUrlHandle _url;

    public Endpoint(string address) => _url = AdaUrlHandle.Parse(Encoding.UTF8.GetBytes(address));

    public string Host => Encoding.UTF8.GetString(_url.GetHostname());

    public void Dispose() => _url.Dispose();
}

Members

Getters are methods rather than properties, and return borrowed spans. A span stays valid while the handle is alive and not changed.

Member	Returns, for https://example.com:8080/a?x=1
GetHref()	https://example.com:8080/a?x=1
GetProtocol()	https:
GetHost()	example.com:8080
GetHostname()	example.com
GetPort()	8080
GetPathname()	/a
GetSearch()	?x=1
GetHash()	Empty
HasCredentials	false
HasPort	true
HasSearch	true
TryGetOrigin(Span<byte> destination, out int written)	https://example.com:8080, false if the buffer is too small
TrySetHost(ReadOnlySpan<byte>)	false if rejected. Invalidates earlier spans.
ToString()	The href as a string. Allocates.

This type exposes a subset of AdaUrl. For the full set of getters and setters, parse into an AdaUrl from GetHref() where you need them.

TrySetHost("example.org"u8) on the URL above gives https://example.org:8080/a?x=1: a host without a port keeps the existing port, as the WHATWG host setter requires.

Threading

Reads take a reference on the handle for the length of the call, so another thread disposing it cannot free the memory mid call. That does not keep a returned span alive afterwards. Mutation is not thread safe.