LEVIATHAN v962456e · 962456eee1

Standard Library

class HeaderMap

An ordered collection of HTTP headers whose names are matched without regard to letter case.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Entries keep the order in which they were added, and the same name may appear more than once, as Set-Cookie does. Looking up content-type therefore finds a header added as Content-Type. HttpRequest.headers and HttpResponse.headers are header maps.

Examples

HeaderMap headers = HeaderMap();
headers.add("Content-Type", "text/html");
headers.add("Set-Cookie", "a=1").add("Set-Cookie", "b=2");
console.writeln(headers.length());
console.writeln(headers.first("content-type"));
console.writeln(headers.all("SET-COOKIE").length());
Run it ▶
3
text/html
2

Methods

add

add(string name, string value) -> HeaderMap

Appends a header, keeping any existing headers of the same name.

Parameters

name
The header name.
value
The header value.

Returns

This map, so calls can be chained.

Examples

Adding the same name twice keeps both

HeaderMap headers = HeaderMap();
headers.add("Set-Cookie", "a=1").add("Set-Cookie", "b=2");
console.writeln(headers.length());
Run it ▶
2

See also: set

all

all(string name) -> Array<string>

Returns the values of every header with this name, in the order they were added.

Parameters

name
The header name, matched ignoring letter case.

Returns

The matching values; empty when there are none.

Examples

HeaderMap headers = HeaderMap();
headers.add("Set-Cookie", "a=1").add("Host", "example.com").add("set-cookie", "b=2");
for (string v in headers.all("Set-Cookie")) {
    console.writeln(v);
}
Run it ▶
a=1
b=2

entries

entries() -> Array<Header>

Returns every header in the order it was added, duplicates included.

Returns

The headers as a list of Header values.

Examples

HeaderMap headers = HeaderMap();
headers.add("Host", "example.com").add("Accept", "text/html");
for (Header h in headers.entries()) {
    console.writeln("${h.name} = ${h.value}");
}
Run it ▶
Host = example.com
Accept = text/html

first

first(string name) -> string | None

Returns the value of the first header with this name, or None when there is none.

Parameters

name
The header name, matched ignoring letter case.

Returns

The first matching value, or None.

Examples

HeaderMap headers = HeaderMap();
headers.add("Host", "example.com");
console.writeln(headers.first("HOST"));
console.writeln(headers.first("accept"));
Run it ▶
example.com
None

See also: firstOr, all

firstOr

firstOr(string name, string dflt) -> string

Returns the value of the first header with this name, or a fallback when there is none.

It is the simplest way to read a header that has a sensible default, because the result is always a plain string.

Parameters

name
The header name, matched ignoring letter case.
dflt
The text to return when no header has that name.

Returns

The first matching value, or dflt.

Examples

HeaderMap headers = HeaderMap();
headers.add("Host", "example.com");
console.writeln(headers.firstOr("host", "unknown"));
console.writeln(headers.firstOr("accept", "unknown"));
Run it ▶
example.com
unknown

See also: first

has

has(string name) -> bool

Tells whether at least one header has this name, ignoring letter case.

Parameters

name
The header name to look for.

Returns

true if a header with that name exists.

Examples

HeaderMap headers = HeaderMap();
headers.add("Host", "example.com");
console.writeln(headers.has("host"));
console.writeln(headers.has("Accept"));
Run it ▶
true
false

length

length() -> int

Returns the number of headers, counting each repeated name separately.

Returns

The number of entries.

Examples

HeaderMap headers = HeaderMap();
headers.add("Set-Cookie", "a=1").add("Set-Cookie", "b=2");
console.writeln(headers.length());
Run it ▶
2

remove

remove(string name) -> HeaderMap

Removes every header with this name.

Nothing happens when there is no such header.

Parameters

name
The header name, matched ignoring letter case.

Returns

This map, so calls can be chained.

Examples

HeaderMap headers = HeaderMap();
headers.add("Set-Cookie", "a=1").add("Host", "example.com").add("set-cookie", "b=2");
headers.remove("SET-COOKIE");
console.writeln(headers.length());
console.writeln(headers.has("Set-Cookie"));
Run it ▶
1
false

render

render() -> string

Formats the headers as they appear on the wire.

Each header becomes Name: value followed by a carriage return and a newline. There is no blank line at the end, so you can append more headers or the separator yourself.

Returns

The header block as text.

Examples

HeaderMap headers = HeaderMap();
headers.add("Host", "example.com").add("Accept", "text/html");
console.writeln(headers.render().replace("\r\n", ";"));
Run it ▶
Host: example.com;Accept: text/html;

set

set(string name, string value) -> HeaderMap

Replaces every header of this name with a single new one.

Existing entries whose name matches, ignoring letter case, are removed, and the new header is appended at the end.

Parameters

name
The header name.
value
The new value.

Returns

This map, so calls can be chained.

Examples

HeaderMap headers = HeaderMap();
headers.add("Accept", "text/html").add("accept", "text/plain");
headers.set("ACCEPT", "application/json");
console.writeln(headers.length());
console.writeln(headers.first("accept"));
Run it ▶
1
application/json

See also: add

See also

  • Header — One HTTP header line: a name and its value.
  • HttpRequest — An HTTP request as seen by a server: the request line, the headers and the body.
  • HttpResponse — An HTTP response: a status code, headers and a body.