silk.text.idna.

When to use#

Use Idna.toAscii to turn a domain name that a person typed, such as Bücher.example, into the ASCII form that DNS and URLs use (xn--bcher-kva.example). Use Idna.toUnicode to show an ASCII domain name to a person. Use Punycode for the label encoding alone.

Details#

Processing is nontransitional: ß, ς, U+200C, and U+200D stay as they are. IdnaOptions selects the optional checks of UTS #46 section 4. The mapping table is from Unicode 18.0.0, and normalization uses the NFC data of silk.text.unicode.

Examples#

Convert a domain name to ASCII#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.text.string { String }
import silk.text.idna { Idna, IdnaOptions }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut output = String.make()
  let valid = run Idna.toAscii("Bücher.example", IdnaOptions.lenient(), &mut output)
    |> Effect.provideMut<Allocator>(&mut allocator)
  if !valid || String.view(&output) != "xn--bcher-kva.example" {
    return 1
  }
  return 0
}

Import as Idna with import silk.text.idna { Idna }.

Public declarations: 3.

IdnaOptions#

pub struct IdnaOptions

The optional checks of UTS #46 processing.

Details#

Each field turns on one check of UTS #46 section 4. A domain name that fails a check that is on is not valid.

Field checkHyphens#

pub checkHyphens: bool

Reject labels that start or end with -, or that have -- in positions 3 and 4.

Field checkBidi#

pub checkBidi: bool

Apply the bidirectional rule of RFC 5893 to each label of a domain name that has right-to-left characters.

Field checkJoiners#

pub checkJoiners: bool

Apply the CONTEXTJ rules of RFC 5892 to U+200C and U+200D.

Field useStd3AsciiRules#

pub useStd3AsciiRules: bool

Allow only a-z, 0-9, and - as ASCII characters in a label.

Field verifyDnsLength#

pub verifyDnsLength: bool

Reject empty labels, labels longer than 63 bytes, and names longer than 253 bytes.

Implementation Copy for IdnaOptions#

impl Copy for IdnaOptions

Implementation IdnaOptions#

impl IdnaOptions

Associated function lenient#

pub fn lenient() -> IdnaOptions

Returns the options of the URL Standard's domain to ASCII: bidi and joiner checks on, and the hyphen, STD3, and DNS length checks off.

Associated function strict#

pub fn strict() -> IdnaOptions

Returns the options for a host name that DNS must accept: all checks on.

Idna#

pub struct Idna

Functions that convert domain names with UTS #46 processing.

Implementation Idna#

impl Idna

Associated function toAscii#

pub effect fn toAscii(domain: string, options: IdnaOptions, output: &mut String) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Appends the ASCII form of domain to output, and returns whether domain is valid.

Details#

It maps, normalizes, and checks domain, then encodes each label that has non-ASCII characters as xn-- and Punycode. The options select the optional checks. When the result is false, output holds the converted text, which must not be used as a domain name.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function toUnicode#

pub effect fn toUnicode(domain: string, options: IdnaOptions, output: &mut String) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Appends the Unicode form of domain to output, and returns whether domain is valid.

Details#

It maps, normalizes, and checks domain, and decodes each xn-- label. A label that does not decode stays as it is. The options select the optional checks. Even when the result is false, output holds the converted text, as UTS #46 ToUnicode specifies.

Errors#

• OutOfMemoryError if the Allocator fails.

Punycode#

pub struct Punycode

Functions that encode and decode Punycode (RFC 3492), the label encoding of IDNA.

Implementation Punycode#

impl Punycode

Associated function decode#

pub effect fn decode(text: &[u8], output: &mut List<u32>) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Decodes the Punycode text, without the xn-- prefix, and appends the code points to output. Returns false if text is not valid Punycode; output then holds a part of the result.

Details#

Letters can be uppercase or lowercase. A result that is not a Unicode scalar value is not valid.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function encode#

pub effect fn encode(points: &[u32], output: &mut String) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Encodes points as Punycode, without the xn-- prefix, and appends it to output.

Details#

Digits are lowercase letters and 0-9. Each value must be a Unicode scalar value.

Errors#

• OutOfMemoryError if the Allocator fails.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.