124 lines
3.8 KiB
PHP
124 lines
3.8 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace Pdp;
|
|
|
|
use Iterator;
|
|
use IteratorAggregate;
|
|
use Stringable;
|
|
|
|
/**
|
|
* @see https://tools.ietf.org/html/rfc1034#section-3.5
|
|
* @see https://tools.ietf.org/html/rfc1123#section-2.1
|
|
* @see https://tools.ietf.org/html/rfc5890
|
|
*
|
|
* @extends IteratorAggregate<string>
|
|
*/
|
|
interface DomainName extends Host, IteratorAggregate
|
|
{
|
|
/**
|
|
* Tells whether the current domain is in its ascii form.
|
|
*/
|
|
public function isAscii(): bool;
|
|
|
|
/**
|
|
* Retrieves a single domain label.
|
|
*
|
|
* If $key is non-negative, the returned value will be the label at $key position from the start.
|
|
* If $key is negative, the returned value will be the label at $key position from the end.
|
|
*
|
|
* If no label is found the submitted $key the returned value will be null.
|
|
*
|
|
* @param int $key the label offset
|
|
*/
|
|
public function label(int $key): ?string;
|
|
|
|
/**
|
|
* Returns the object labels.
|
|
*
|
|
* @return list<string>
|
|
*/
|
|
public function labels(): array;
|
|
|
|
/**
|
|
* Returns the associated key for each label.
|
|
*
|
|
* If a value is specified only the keys associated with
|
|
* the given value will be returned
|
|
*
|
|
* @return list<int>
|
|
*/
|
|
public function keys(?string $label = null): array;
|
|
|
|
/**
|
|
* The external iterator iterates over the DomainInterface labels
|
|
* from the right-most label to the left-most label.
|
|
*
|
|
* @return Iterator<string>
|
|
*/
|
|
public function getIterator(): Iterator;
|
|
|
|
/**
|
|
* Prepends a label to the domain.
|
|
*
|
|
* @see ::withLabel
|
|
*/
|
|
public function prepend(DomainNameProvider|Host|Stringable|string|int|null $label): self;
|
|
|
|
/**
|
|
* Appends a label to the domain.
|
|
*
|
|
* @see ::withLabel
|
|
*/
|
|
public function append(DomainNameProvider|Host|Stringable|string|int|null $label): self;
|
|
|
|
/**
|
|
* Returns an instance with the specified label added at the specified key.
|
|
*
|
|
* This method MUST retain the state of the current instance, and return
|
|
* an instance that contains the new label
|
|
*
|
|
* If $key is non-negative, the added label will be the label at $key position from the start.
|
|
* If $key is negative, the added label will be the label at $key position from the end.
|
|
*
|
|
* @param DomainNameProvider|Host|Stringable|string|int|null $label a domain label
|
|
*
|
|
* @throws CannotProcessHost If the key is out of bounds
|
|
* @throws CannotProcessHost If the label is converted to the NULL value
|
|
*/
|
|
public function withLabel(int $key, DomainNameProvider|Host|Stringable|string|int|null $label): self;
|
|
|
|
/**
|
|
* Returns an instance with the label at the specified key removed.
|
|
*
|
|
* This method MUST retain the state of the current instance, and return
|
|
* an instance without the specified label
|
|
*
|
|
* If $key is non-negative, the removed label will be the label at $key position from the start.
|
|
* If $key is negative, the removed label will be the label at $key position from the end.
|
|
*
|
|
*
|
|
* @throws CannotProcessHost If the key is out of bounds
|
|
*/
|
|
public function withoutLabel(int ...$keys): self;
|
|
|
|
/**
|
|
* Returns an instance with all labels removed.
|
|
*
|
|
* This method MUST retain the state of the current instance, and return
|
|
* an instance that contains no label
|
|
*/
|
|
public function clear(): self;
|
|
|
|
/**
|
|
* Extracts a slice of $length elements starting at position $offset from the Collection.
|
|
*
|
|
* This method MUST retain the state of the current instance, and return
|
|
* an instance that contains the selected slice.
|
|
*
|
|
* If $length is null it returns all elements from $offset to the end of the Domain.
|
|
*/
|
|
public function slice(int $offset, ?int $length = null): self;
|
|
}
|