# URL

<a id="url"></a>

# URL

```cpp
#include <icy/http/url.h>

class URL
```

[Defined in src/http/include/icy/http/url.h:28](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L28)

An RFC 3986 based [URL](#url) parser. Constructors and assignment operators will throw a SyntaxException if the [URL](#url) is invalid.

## Friends

| Name | Description |
|------|-------------|
| [`operator<<`](#operator-209) `inline` |  |

---

<a id="operator-209"></a>

### operator<<

`inline`

```cpp
friend inline std::ostream & operator<<(std::ostream & stream, const URL & url)
```

[Defined in src/http/include/icy/http/url.h:163](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L163)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`URL`](#url-1)  | Creates an empty [URL](#url). |
|  | [`URL`](#url-2)  | Parses the [URL](#url) from a null-terminated string. |
|  | [`URL`](#url-3)  | Parses the [URL](#url) from a std::string. |
|  | [`URL`](#url-4)  | Constructs a [URL](#url) from scheme and authority components. |
|  | [`URL`](#url-5)  | Constructs a [URL](#url) from scheme, authority, and path+query+fragment. |
|  | [`URL`](#url-6)  | Constructs a [URL](#url) from individual components. |
|  | [`URL`](#url-7)  | Defaulted constructor. |
|  | [`~URL`](#url-8)  |  |
| [`URL`](#url) & | [`operator=`](#operator-210)  | Assigns a [URL](#url) from another [URL](#url) instance. |
| [`URL`](#url) & | [`operator=`](#operator-211)  | Assigns a [URL](#url) from a null-terminated string. |
| [`URL`](#url) & | [`operator=`](#operator-212)  | Assigns a [URL](#url) from a std::string. |
| `bool` | [`parse`](#parse-5)  | Parses and assigns a [URL](#url) from the given string view, resetting all components first. |
| `std::string` | [`scheme`](#scheme) `const` | Returns the [URL](#url) scheme (e.g. "http", "https", "ws"). Always lowercase. |
| `std::string` | [`userInfo`](#userinfo) `const` | Returns the user info component (e.g. "user:pass" from "http://user:pass@host/"). Returns an empty string if not present. |
| `std::string` | [`host`](#host-1) `const` | Returns the host component (e.g. "example.com"). Returns an empty string if not present. |
| `uint16_t` | [`port`](#port-1) `const` | Returns the port number. If no explicit port was in the [URL](#url), returns the default port for the scheme (80 for http, 443 for https), or 0 if the scheme is unknown. |
| `std::string` | [`authority`](#authority) `const` | Returns the authority component (`userinfo@host:port`). Only includes components that are present. |
| `std::string` | [`path`](#path-1) `const` | Returns the path component (e.g. "/index.html"). Returns an empty string if not present. |
| `std::string` | [`pathEtc`](#pathetc) `const` | Returns the path, query and fragment combined (e.g. "/path?q=1#frag"). |
| `std::string` | [`query`](#query) `const` | Returns the query string without the leading '?' (e.g. "key=value&foo=bar"). Returns an empty string if not present. |
| `std::string` | [`fragment`](#fragment) `const` | Returns the fragment identifier without the leading '#'. Returns an empty string if not present. |
| `bool` | [`hasSchema`](#hasschema) `const` | Returns true if the [URL](#url) has a scheme component. |
| `bool` | [`hasUserInfo`](#hasuserinfo) `const` | Returns true if the [URL](#url) has a user info component. |
| `bool` | [`hasHost`](#hashost) `const` | Returns true if the [URL](#url) has a host component. |
| `bool` | [`hasPort`](#hasport) `const` | Returns true if an explicit port was specified in the [URL](#url). |
| `bool` | [`hasPath`](#haspath) `const` | Returns true if the [URL](#url) has a path component. |
| `bool` | [`hasQuery`](#hasquery) `const` | Returns true if the [URL](#url) has a query component. |
| `bool` | [`hasFragment`](#hasfragment) `const` | Returns true if the [URL](#url) has a fragment component. |
| `bool` | [`valid`](#valid-1) `const` | Returns true if the [URL](#url) is non-empty and was successfully parsed. |
| `std::string` | [`str`](#str-7) `const` | Returns the original [URL](#url) string as parsed. |

---

<a id="url-1"></a>

### URL

```cpp
URL()
```

[Defined in src/http/include/icy/http/url.h:32](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L32)

Creates an empty [URL](#url).

---

<a id="url-2"></a>

### URL

```cpp
URL(const char * url)
```

[Defined in src/http/include/icy/http/url.h:36](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L36)

Parses the [URL](#url) from a null-terminated string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | `const char *` | Null-terminated [URL](#url) string to parse. |

---

<a id="url-3"></a>

### URL

```cpp
URL(const std::string & url)
```

[Defined in src/http/include/icy/http/url.h:40](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L40)

Parses the [URL](#url) from a std::string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | `const std::string &` | [URL](#url) string to parse. |

---

<a id="url-4"></a>

### URL

```cpp
URL(const std::string & scheme, const std::string & authority)
```

[Defined in src/http/include/icy/http/url.h:45](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L45)

Constructs a [URL](#url) from scheme and authority components.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheme` | `const std::string &` | [URL](#url) scheme (e.g. "http", "https"). |
| `authority` | `const std::string &` | Host and optional port (e.g. "example.com:8080"). |

---

<a id="url-5"></a>

### URL

```cpp
URL(const std::string & scheme, const std::string & authority, const std::string & pathEtc)
```

[Defined in src/http/include/icy/http/url.h:51](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L51)

Constructs a [URL](#url) from scheme, authority, and path+query+fragment.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheme` | `const std::string &` | [URL](#url) scheme (e.g. "http"). |
| `authority` | `const std::string &` | Host and optional port. |
| `pathEtc` | `const std::string &` | Path, query and fragment combined (e.g. "/path?q=1#frag"). |

---

<a id="url-6"></a>

### URL

```cpp
URL(const std::string & scheme, const std::string & authority, const std::string & path, const std::string & query, const std::string & fragment = "")
```

[Defined in src/http/include/icy/http/url.h:60](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L60)

Constructs a [URL](#url) from individual components.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `scheme` | `const std::string &` | [URL](#url) scheme (e.g. "http"). |
| `authority` | `const std::string &` | Host and optional port. |
| `path` | `const std::string &` | [URL](#url) path (e.g. "/index.html"). |
| `query` | `const std::string &` | Query string without leading '?' (e.g. "key=value"). |
| `fragment` | `const std::string &` | Fragment identifier without leading '#'. |

---

<a id="url-7"></a>

### URL

```cpp
URL(const URL &) = default
```

[Defined in src/http/include/icy/http/url.h:64](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L64)

Defaulted constructor.

---

<a id="url-8"></a>

### ~URL

```cpp
~URL()
```

[Defined in src/http/include/icy/http/url.h:65](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L65)

---

<a id="operator-210"></a>

### operator=

```cpp
URL & operator=(const URL & uri)
```

[Defined in src/http/include/icy/http/url.h:70](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L70)

Assigns a [URL](#url) from another [URL](#url) instance. 
#### Returns
Reference to this [URL](#url).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `uri` | const [`URL`](#url) & | Source [URL](#url) to copy from. |

---

<a id="operator-211"></a>

### operator=

```cpp
URL & operator=(const char * uri)
```

[Defined in src/http/include/icy/http/url.h:75](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L75)

Assigns a [URL](#url) from a null-terminated string. 
#### Returns
Reference to this [URL](#url).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `uri` | `const char *` | Null-terminated [URL](#url) string to parse. |

---

<a id="operator-212"></a>

### operator=

```cpp
URL & operator=(const std::string & uri)
```

[Defined in src/http/include/icy/http/url.h:80](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L80)

Assigns a [URL](#url) from a std::string. 
#### Returns
Reference to this [URL](#url).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `uri` | `const std::string &` | [URL](#url) string to parse. |

---

<a id="parse-5"></a>

### parse

```cpp
bool parse(std::string_view url, bool whiny = true)
```

[Defined in src/http/include/icy/http/url.h:86](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L86)

Parses and assigns a [URL](#url) from the given string view, resetting all components first. 
#### Returns
true if the [URL](#url) was parsed successfully; false if invalid and whiny is false.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | `std::string_view` | [URL](#url) string to parse. |
| `whiny` | `bool` | If true, throws std::runtime_error on an invalid [URL](#url); otherwise returns false. |

---

<a id="scheme"></a>

### scheme

`const`

```cpp
std::string scheme() const
```

[Defined in src/http/include/icy/http/url.h:102](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L102)

Returns the [URL](#url) scheme (e.g. "http", "https", "ws"). Always lowercase.

---

<a id="userinfo"></a>

### userInfo

`const`

```cpp
std::string userInfo() const
```

[Defined in src/http/include/icy/http/url.h:106](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L106)

Returns the user info component (e.g. "user:pass" from "http://user:pass@host/"). Returns an empty string if not present.

---

<a id="host-1"></a>

### host

`const`

```cpp
std::string host() const
```

[Defined in src/http/include/icy/http/url.h:110](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L110)

Returns the host component (e.g. "example.com"). Returns an empty string if not present.

---

<a id="port-1"></a>

### port

`const`

```cpp
uint16_t port() const
```

[Defined in src/http/include/icy/http/url.h:115](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L115)

Returns the port number. If no explicit port was in the [URL](#url), returns the default port for the scheme (80 for http, 443 for https), or 0 if the scheme is unknown.

---

<a id="authority"></a>

### authority

`const`

```cpp
std::string authority() const
```

[Defined in src/http/include/icy/http/url.h:119](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L119)

Returns the authority component (`userinfo@host:port`). Only includes components that are present.

---

<a id="path-1"></a>

### path

`const`

```cpp
std::string path() const
```

[Defined in src/http/include/icy/http/url.h:123](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L123)

Returns the path component (e.g. "/index.html"). Returns an empty string if not present.

---

<a id="pathetc"></a>

### pathEtc

`const`

```cpp
std::string pathEtc() const
```

[Defined in src/http/include/icy/http/url.h:126](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L126)

Returns the path, query and fragment combined (e.g. "/path?q=1#frag").

---

<a id="query"></a>

### query

`const`

```cpp
std::string query() const
```

[Defined in src/http/include/icy/http/url.h:130](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L130)

Returns the query string without the leading '?' (e.g. "key=value&foo=bar"). Returns an empty string if not present.

---

<a id="fragment"></a>

### fragment

`const`

```cpp
std::string fragment() const
```

[Defined in src/http/include/icy/http/url.h:134](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L134)

Returns the fragment identifier without the leading '#'. Returns an empty string if not present.

---

<a id="hasschema"></a>

### hasSchema

`const`

```cpp
bool hasSchema() const
```

[Defined in src/http/include/icy/http/url.h:137](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L137)

Returns true if the [URL](#url) has a scheme component.

---

<a id="hasuserinfo"></a>

### hasUserInfo

`const`

```cpp
bool hasUserInfo() const
```

[Defined in src/http/include/icy/http/url.h:140](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L140)

Returns true if the [URL](#url) has a user info component.

---

<a id="hashost"></a>

### hasHost

`const`

```cpp
bool hasHost() const
```

[Defined in src/http/include/icy/http/url.h:143](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L143)

Returns true if the [URL](#url) has a host component.

---

<a id="hasport"></a>

### hasPort

`const`

```cpp
bool hasPort() const
```

[Defined in src/http/include/icy/http/url.h:146](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L146)

Returns true if an explicit port was specified in the [URL](#url).

---

<a id="haspath"></a>

### hasPath

`const`

```cpp
bool hasPath() const
```

[Defined in src/http/include/icy/http/url.h:149](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L149)

Returns true if the [URL](#url) has a path component.

---

<a id="hasquery"></a>

### hasQuery

`const`

```cpp
bool hasQuery() const
```

[Defined in src/http/include/icy/http/url.h:152](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L152)

Returns true if the [URL](#url) has a query component.

---

<a id="hasfragment"></a>

### hasFragment

`const`

```cpp
bool hasFragment() const
```

[Defined in src/http/include/icy/http/url.h:155](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L155)

Returns true if the [URL](#url) has a fragment component.

---

<a id="valid-1"></a>

### valid

`const`

```cpp
bool valid() const
```

[Defined in src/http/include/icy/http/url.h:158](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L158)

Returns true if the [URL](#url) is non-empty and was successfully parsed.

---

<a id="str-7"></a>

### str

`const`

```cpp
std::string str() const
```

[Defined in src/http/include/icy/http/url.h:161](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L161)

Returns the original [URL](#url) string as parsed.

## Public Static Methods

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`encode`](#encode-21) `static` | Percent-encodes a string per RFC 3986, preserving unreserved characters (A-Z, a-z, 0-9, '-', '_', '.', '~'). Equivalent to JavaScript's encodeURIComponent(). |
| `std::string` | [`decode`](#decode-10) `static` | Decodes a percent-encoded string per RFC 3986. Equivalent to JavaScript's decodeURIComponent(). |

---

<a id="encode-21"></a>

### encode

`static`

```cpp
static std::string encode(std::string_view str)
```

[Defined in src/http/include/icy/http/url.h:92](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L92)

Percent-encodes a string per RFC 3986, preserving unreserved characters (A-Z, a-z, 0-9, '-', '_', '.', '~'). Equivalent to JavaScript's encodeURIComponent(). 
#### Returns
Percent-encoded string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `str` | `std::string_view` | Input string to encode. |

---

<a id="decode-10"></a>

### decode

`static`

```cpp
static std::string decode(std::string_view str)
```

[Defined in src/http/include/icy/http/url.h:98](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L98)

Decodes a percent-encoded string per RFC 3986. Equivalent to JavaScript's decodeURIComponent(). 
#### Returns
Decoded string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `str` | `std::string_view` | Percent-encoded input string. |

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`_buf`](#_buf)  |  |
| `std::string` | [`_scheme`](#_scheme)  |  |
| `std::string` | [`_userInfo`](#_userinfo)  |  |
| `std::string` | [`_host`](#_host)  |  |
| `uint16_t` | [`_port`](#_port)  |  |
| `std::string` | [`_path`](#_path-3)  |  |
| `std::string` | [`_query`](#_query)  |  |
| `std::string` | [`_fragment`](#_fragment)  |  |
| `bool` | [`_hasPort`](#_hasport)  |  |

---

<a id="_buf"></a>

### _buf

```cpp
std::string _buf
```

[Defined in src/http/include/icy/http/url.h:170](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L170)

---

<a id="_scheme"></a>

### _scheme

```cpp
std::string _scheme
```

[Defined in src/http/include/icy/http/url.h:171](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L171)

---

<a id="_userinfo"></a>

### _userInfo

```cpp
std::string _userInfo
```

[Defined in src/http/include/icy/http/url.h:172](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L172)

---

<a id="_host"></a>

### _host

```cpp
std::string _host
```

[Defined in src/http/include/icy/http/url.h:173](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L173)

---

<a id="_port"></a>

### _port

```cpp
uint16_t _port
```

[Defined in src/http/include/icy/http/url.h:174](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L174)

---

<a id="_path-3"></a>

### _path

```cpp
std::string _path
```

[Defined in src/http/include/icy/http/url.h:175](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L175)

---

<a id="_query"></a>

### _query

```cpp
std::string _query
```

[Defined in src/http/include/icy/http/url.h:176](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L176)

---

<a id="_fragment"></a>

### _fragment

```cpp
std::string _fragment
```

[Defined in src/http/include/icy/http/url.h:177](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L177)

---

<a id="_hasport"></a>

### _hasPort

```cpp
bool _hasPort
```

[Defined in src/http/include/icy/http/url.h:178](https://github.com/auscaster/icey/blob/main/src/http/include/icy/http/url.h#L178)