Numbers extension¶
Extensions\Numbers\Numbers loads automatically through Numbers.extension.json and
provides integer(), binary(), octal(), hexadecimal(), octet() and float().
Static and scoped calls start expressions; chained calls append numeric parsers.
These factories return matched text, preserving its exact spelling and byte spans.
Their typed counterparts return PHP numeric values through a lazy, cached projection.
| Text factory | Typed factory | Value type |
|---|---|---|
integer() |
integerValue() |
int |
binary() |
binaryValue() |
int |
octal() |
octalValue() |
int |
hexadecimal() |
hexadecimalValue() |
int |
octet() |
octetValue() |
int |
float() |
floatValue() |
float |
Typed factories accept the same options, including strict: false. They use the
value already validated during recognition, so custom alphabets, case scopes and
integer limits do not require a second conversion. rawText() and syntax-tree
spans retain the original spelling. Native Float rounding and underflow still apply.
Chained typed factories append parsers and retain ordinary sequence semantics;
use a standalone typed factory or explicit value selection when its value is wanted.
use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Extensions\Numbers\SignPolicy as S;
$number = C::float(minimum: null, sign: S::OPTIONAL);
$number->parse('+1.25e-2')->value(); // '+1.25e-2'
$number->map('floatval')->parse('+1.25e-2')->value(); // 0.0125
C::integer(sign: S::REQUIRED)->parse('+12')->value(); // '+12'
C::hexadecimalValue()->parse('ff')->value(); // 255
C::floatValue()->parse('1.25e2')->value(); // 125.0
Direct parsers are Extensions\Numbers\Parser\IntegerNumber and
Extensions\Numbers\Parser\FloatNumber. PHP reserves Float as a class name.
Direct typed parsers are IntegerValue and FloatValue in the same namespace;
they inherit the corresponding text parser's constructor options.
The former Extensions\Integers provider and parser namespace were renamed to
Numbers without compatibility aliases. Existing integer factory arguments remain
valid; the default sign policy preserves the previous behavior, and strict is
the final optional argument.
The Integer parser class is now named IntegerNumber. Update direct class imports
and references to IntegerNumber::DIGITS; the integer() factory is unchanged.
The former Numbers\Parser\Integer class has no compatibility alias.
Integer representations¶
integer(minimum: 0, maximum: null, base: 10, allowLeadingZeros: false,
digits: IntegerNumber::DIGITS, sign: S::MINUS_ONLY, strict: false) supports custom UTF-8 alphabets,
case policies, bounded values and PHP integer overflow checking. The standard
alphabet supports bases 2–36. Binary, octal and hexadecimal factories select bases
2, 8 and 16; octet selects decimal bounds 0–255. Their leading-zero and sign
options follow the same rules.
Floating-point representations¶
float(minimum: 0.0, maximum: null, allowLeadingZeros: false,
allowExponent: true, sign: S::MINUS_ONLY, allowWholeNumbers: true, strict: false) accepts ASCII decimal forms such as
12, 12.5, .5, 12. and 1.2e-3. Both e and E are accepted regardless
of case policy. Exponent digits may have leading zeros, and their optional +
or - sign is independent of the leading sign policy.
Set allowExponent: false for decimal notation alone. matchPrefix('1e3') then
recognizes 1, while complete parse('1e3') fails on the remaining text. Without
leading-zero permission, 0.5 is valid but 00.5 is not a complete match.
No locale-specific separators, alternate bases, digit separators or textual
INF/NaN values are supported.
Set allowWholeNumbers: false to require a decimal point or an enabled exponent.
This rejects bare 12 while accepting 12.0, .5, 12. and 1e3. It controls
spelling, not whether the represented value is mathematically a whole number.
With exponents disabled as well, a decimal point is required and 1e3 has no
matching prefix. Bounds fallback uses the same restriction:
C::float(maximum: 2, allowWholeNumbers: false)->matchPrefix('12.5') fails rather
than returning 1. The default remains true for existing grammars.
Range checking uses native PHP floats and their usual precision. Bounds must be finite or null and ordered. Overflowing candidates are rejected; nonzero values that underflow to native zero are permitted when the bounds include zero. This does not change the returned source text or promise exact decimal arithmetic.
Both parsers try shorter complete numeric prefixes when a candidate is outside
the bounds or overflows. For example, C::float(maximum: 2)->matchPrefix('12.5')
recognizes 1, while complete parsing fails. Shortened Float candidates must still
be complete numbers; a dangling exponent or sign is never consumed.
Leading signs¶
| Policy | Accepted leading sign |
|---|---|
MINUS_ONLY (default) |
None or - |
OPTIONAL |
None, +, or - |
REQUIRED |
+ or - |
FORBIDDEN |
None |
Signs control spelling independently of bounds. Negative numbers need a lower
bound that permits them, such as minimum: null.
Signed zero requires allowLeadingZeros: true for every policy that allows the
sign. This includes +0, -0, -0.0 and -.0e3; -0.5 has a nonzero
significand and is unaffected. A tiny nonzero significand that underflows is also
unaffected. With leading zeros disabled, REQUIRED consequently rejects zero.
Integer alphabets always exclude -. They also exclude + under OPTIONAL and
REQUIRED to avoid ambiguity with the leading sign. Under MINUS_ONLY or FORBIDDEN,
+ may still be an explicitly configured digit.
Optional strict matching¶
Append strict: true to a text or typed numeric factory to reject an invalid
numeric candidate instead of retrying shorter prefixes. The default is false,
preserving existing grammars. Strict matching does not require end-of-input:
C::integer(maximum: 255)->matchPrefix('256')->value(); // '25'
C::integer(maximum: 255, strict: true)->matchPrefix('256')->success; // false
C::integerValue(strict: true)->matchPrefix('12kg')->value(); // 12
Integer candidates include the active digit alphabet and ASCII digits. Strict
binary 102, octal 178, and forbidden leading zeros fail. Characters outside
that candidate remain boundaries, so integer 12.5 can still match 12.
Float treats a following ASCII digit, decimal point, or e/E as numeric
continuation. Strict 01.5, 1e+, 1.2.3, and overflow fail. With exponents
disabled, strict 1e3 also fails. An e/E suffix such as 12em is consequently
not an unrelated unit boundary. Bounds and all sign/whole-number options still
apply, and no shorter candidate is tried. Native underflow remains permitted.
Other suffixes and delimiters remain available to the enclosing grammar:
12kg, 12,, and 12+3 can match the numeric prefix. Exponent signs belong to
the Float token; other signs can delimit a subsequent expression. Complete
parse() continues to reject any remaining text.
Recognition, bounds and guards remain pure. Mappings are lazy and cached, and effects require explicit commit. Both parsers use the existing snapshot, source, diagnostic and work-limit contracts. Float, like IntegerNumber, uses the session's shared regex subject and may materialize a complete file subject.
Run php docs/examples/numbers.php for checked examples.