Skip to content

classDomain

packages/sql-catalog/src/Core/Evaluation/Domain.php:23

final class Domain

Restricted visibility: declared "@visibility root". Code outside that scope must not name this declaration.

Every value an expression may take, over-approximated.

A domain is a bounded set of alternatives. Keeping the set means a query built from an enum-typed parameter is reported as the handful of statements it can actually be, instead of one statement with a gap. When the set would grow past the bound it is generalized into a single shape that still covers all of it, so the approximation only ever widens.

Constants§

public const MAX_TERMS = 12

How many alternatives a domain keeps before generalizing them into one shape.

Properties§

public list<Term> $terms

public bool $widened

public bool $combined = false

Methods§

public static function of(Term $term): self

The domain holding exactly one alternative.

Parameters

$term Term

Returns

self

Test cases 95

Called from 39

Calls 1

new self line 49

public static function literal(string|int|float|bool|null $value): self

The domain holding one resolved scalar.

Parameters

$value string|int|float|bool|null

Returns

self

Test cases 325

Called from 120

Calls 2

static-call Domain::of() line 57
new LiteralTerm line 57

public static function opaque(TypeShape $type, Origin $origin, ?string $expression = null): self

The domain of values known only by type and origin.

Parameters

`$type`	`TypeShape`
`$origin`	`Origin`
`$expression`	`?string`

Returns

self

Test cases 18

Called from 70

Calls 2

static-call Domain::of() line 65
new OpaqueTerm line 65

public static function unknown(?string $expression = null): self

The domain of a value nothing is known about.

Parameters

$expression ?string

Returns

self

Test cases 55

Called from 41

Calls 2

static-call Domain::of() line 73
static-call OpaqueTerm::unresolved() line 73

public static function fromTerms(
    list<Term> $terms,
    bool $widened = false,
    bool $combined = false,
): self

The domain built from a set of alternatives, deduplicated and bounded.

Parameters

`$terms`	`list<Term>`
`$widened`	`bool`
`$combined`	`bool`

Returns

self

Test cases 19

Called from 16

Calls 7

function-call array_values line 87
static-call Domain::unknown() line 90
function-call count line 92
class-const Domain::MAX_TERMS() line 92
new self line 93
static-call Domain::generalize() line 96
class-const Origin::Branch() line 96

public static function generalize(list<Term> $terms, Origin $origin): Term

The single term that covers every given alternative.

Parameters

`$terms`	`list<Term>`
`$origin`	`Origin`

Returns

Term

Test cases 1

DomainTest::testGeneralizeCoversEveryAlternative calls

Called from 2

Calls 3

new PatternTerm line 111
method-call TextGeneralization::mergeAll() line 111
new TextGeneralization line 111

public function union(self $other): self

The domain admitting every value either domain admits.

Parameters

$other self

Returns

self

Calls 2

static-call Domain::fromTerms() line 119
function-call array_merge line 120

public function concat(self $other): self

The domain of the strings produced by writing this domain then the other.

Pairing two sides that each hold several alternatives produces every combination of them, and nothing here can tell which combinations the program can actually reach. The result is marked as combined so that a report can say the alternatives may be wider than the code allows.

Parameters

$other self

Returns

self

Calls 3

static-call Domain::asTerm() line 139
function-call count line 142
static-call Domain::fromTerms() line 144

public function select(self $keys, ?string $expression = null): ?self

The elements the keys select from this domain's arrays, or null when that is not known.

A resolved key reads the element written under it; a key that did not resolve reads whatever element the array holds. Every alternative here must be an array and every resolved key must find its element, so a lookup never resolves to a value the array does not hold. Keys paired from parts that vary independently select elements that are paired the same way, so the result stays marked as combined.

Parameters

`$keys`	`self`
`$expression`	`?string`

Returns

?self

Calls 2

class-const Origin::Unresolved() line 167
static-call Domain::fromTerms() line 177

public static function asTerm(TextPattern $pattern): Term

The term standing for a pattern, collapsed to a literal when fully resolved.

Parameters

$pattern TextPattern

Returns

Term

Test cases 2

Called from 2

Calls 3

method-call TextPattern::text() line 185
new PatternTerm line 187
new LiteralTerm line 187

public function collapse(Origin $origin): self

The domain narrowed to a single shape covering all of its alternatives.

Parameters

$origin Origin

Returns

self

Calls 3

function-call count line 195
new self line 199
static-call Domain::generalize() line 199

public function soleLiteral(): ?LiteralTerm

The one resolved scalar this domain holds, or null when it holds anything else.

Returns

?LiteralTerm

Test cases 23

Called from 2

Calls 1

function-call count line 207

public function soleArray(): ?ArrayTerm

The one array this domain holds, or null when it holds anything else.

Returns

?ArrayTerm

Called from 7

Calls 1

function-call count line 217

public function soleObject(): ?ObjectTerm

The one object this domain holds, or null when it holds anything else.

Returns

?ObjectTerm

Called from 10

Calls 1

function-call count line 227

public function withVariable(string $variable): self

Labels opaque alternatives with the PHP variable read at their use site.

Provenance, resolved fragments, comparison signatures and domain flags remain unchanged; the name is only an annotation for report readers.

Parameters

$variable string

Returns

self

Calls 4

function-call array_filter line 240
new self line 244
function-call array_map line 245
new OpaqueTerm line 247

public function patterns(): list<TextPattern>

The alternatives written as string patterns.

Returns

list<TextPattern>

Test cases 1

DeriverTest::testSolveGivesOneSolutionPerBranchWithCorrelatedValues calls

public function isExact(): bool

Whether every alternative resolves to an exact string.

Returns

bool

public function type(): TypeShape

The static type covering every alternative.

Returns

TypeShape

Called from 5

public function signature(): string

A canonical string used to compare domains.

Returns

string

Test cases 4

Called from 3

Calls 2

function-call sort line 310
function-call implode line 312

public function equals(self $other): bool

Whether the two domains describe the same set of values.

Parameters

$other self

Returns

bool

Calls 2

method-call Domain::signature() line 320
method-call self::signature() line 320

Private surface 2§

Implementation details, listed for orientation only.

private ?string $signature = null

private function __construct(
    public list<Term> $terms,
    public bool $widened,
    public bool $combined = false,
)

Test cases 403§

Test cases that cover or call this symbol, from the coverage report and from the analyzed test sources.

Dedicated tests 32

Other tests reaching this symbol 371

Relations§

Static calls 280

Method calls 26

Type declarations 116