Numbers
Utility functions for working with integer/float tokens.
PHP 7.4 introduced numeric literal separators which break number tokenization in older PHP versions. PHPCS backfills this since PHPCS 3.5.3/4.
However, if an external standard intends to support PHPCS < 3.5.4 and PHP < 7.4, working with number tokens has suddenly become a challenge.
The functions in this class have been put in place to ease that pain and it is
strongly recommended to always use these functions when sniffing for and examining the
contents of T_LNUMBER or T_DNUMBER tokens.
Table of Contents
| REGEX_DECIMAL_INT | Regex to determine whether the contents of an arbitrary string represents a decimal integer. | '`^(?:0|[1-9][0-9]*)$`D' |
|---|---|---|
| REGEX_OCTAL_INT | Regex to determine whether the contents of an arbitrary string represents an octal integer. | '`^0[0-7]+$`D' |
| REGEX_BINARY_INT | Regex to determine whether the contents of an arbitrary string represents a binary integer. | '`^0b[0-1]+$`iD' |
| REGEX_HEX_INT | Regex to determine whether the contents of an arbitrary string represents a hexidecimal integer. | '`^0x[0-9A-F]+$`iD' |
| REGEX_FLOAT | Regex to determine whether the contents of an arbitrary string represents a float. | '` ^(?: (?: (?: (?P<LNUM>[0-9]+) | (?P<DNUM>([0-9]*\\.(?P>LNUM)|(?P>LNUM)\\.[0-9]*)) ) [e][+-]?(?P>LNUM) ) | (?P>DNUM) | (?:0|[1-9][0-9]*) )$ `ixD' |
| REGEX_NUMLIT_STRING | Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence. | '`^((?<![\\.e])_[0-9][0-9e\\.]*)+$`iD' |
| REGEX_HEX_NUMLIT_STRING | Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a hexidecimal numeric literal sequence. | '`^((?<!\\.)_[0-9A-F]*)+$`iD' |
| UNSUPPORTED_PHPCS_VERSION | PHPCS versions in which the backfill for PHP 7.4 numeric literal separators is broken. | '3.5.3' |
| $numericLiteralAcceptedTokens | Valid tokens which could be part of a numeric literal sequence in PHP < 7.4. | array |
| getCompleteNumber() | Helper function to deal with numeric literals, potentially with underscore separators. | array |
| getDecimalValue() | Get the decimal number value of a numeric string. | string|bool |
| isDecimalInt() | Verify whether the contents of an arbitrary string represents a decimal integer. | bool |
| isHexidecimalInt() | Verify whether the contents of an arbitrary string represents a hexidecimal integer. | bool |
| isBinaryInt() | Verify whether the contents of an arbitrary string represents a binary integer. | bool |
| isOctalInt() | Verify whether the contents of an arbitrary string represents an octal integer. | bool |
| isFloat() | Verify whether the contents of an arbitrary string represents a floating point number. | bool |
Constants
REGEX_DECIMAL_INT
Regex to determine whether the contents of an arbitrary string represents a decimal integer.
string
$REGEX_DECIMAL_INT
= '`^(?:0|[1-9][0-9]*)$`D'
REGEX_OCTAL_INT
Regex to determine whether the contents of an arbitrary string represents an octal integer.
string
$REGEX_OCTAL_INT
= '`^0[0-7]+$`D'
REGEX_BINARY_INT
Regex to determine whether the contents of an arbitrary string represents a binary integer.
string
$REGEX_BINARY_INT
= '`^0b[0-1]+$`iD'
REGEX_HEX_INT
Regex to determine whether the contents of an arbitrary string represents a hexidecimal integer.
string
$REGEX_HEX_INT
= '`^0x[0-9A-F]+$`iD'
REGEX_FLOAT
Regex to determine whether the contents of an arbitrary string represents a float.
string
$REGEX_FLOAT
= '`
^(?:
(?:
(?:
(?P<LNUM>[0-9]+)
|
(?P<DNUM>([0-9]*\\.(?P>LNUM)|(?P>LNUM)\\.[0-9]*))
)
[e][+-]?(?P>LNUM)
)
|
(?P>DNUM)
|
(?:0|[1-9][0-9]*)
)$
`ixD'
REGEX_NUMLIT_STRING
Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.
string
$REGEX_NUMLIT_STRING
= '`^((?<![\\.e])_[0-9][0-9e\\.]*)+$`iD'
REGEX_HEX_NUMLIT_STRING
Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a hexidecimal numeric literal sequence.
string
$REGEX_HEX_NUMLIT_STRING
= '`^((?<!\\.)_[0-9A-F]*)+$`iD'
UNSUPPORTED_PHPCS_VERSION
PHPCS versions in which the backfill for PHP 7.4 numeric literal separators is broken.
string
$UNSUPPORTED_PHPCS_VERSION
= '3.5.3'
Properties
$numericLiteralAcceptedTokens
Valid tokens which could be part of a numeric literal sequence in PHP < 7.4.
private
static array
$numericLiteralAcceptedTokens
= [\T_LNUMBER => true, \T_DNUMBER => true, \T_STRING => true]
Methods
getCompleteNumber()
Helper function to deal with numeric literals, potentially with underscore separators.
public
static getCompleteNumber(
$phpcsFile :
File
, $stackPtr :
int
)
: array
PHP < 7.4 does not tokenize numeric literals containing underscores correctly. As of PHPCS 3.5.3, PHPCS contains a back-fill, but this backfill was buggy in the initial implementation. A fix for this broken backfill is included in PHPCS 3.5.4.
Either way, this function provides a backfill for all PHPCS/PHP combinations where PHP 7.4 numbers with underscore separators are tokenized incorrectly - with the exception of PHPCS 3.5.3 as the buggyness of the original backfill implementation makes it impossible to provide reliable results.
Parameters
- $phpcsFile : File
The file being scanned.
- $stackPtr : int
The position of a T_LNUMBER or T_DNUMBER token.
Tags
Return values
array —An array with the following information about the number:
- 'orig_content' string The (potentially concatenated) original content of the tokens;
- 'content' string The (potentially concatenated) content, underscore(s) removed;
- 'code' int The token code of the number, either T_LNUMBER or T_DNUMBER.
- 'type' string The token type, either 'T_LNUMBER' or 'T_DNUMBER'.
- 'decimal' string The decimal value of the number;
- 'last_token' int The stackPtr to the last token which was part of the number; This will be the same as the original stackPtr if it is not a PHP 7.4 number with underscores.
getDecimalValue()
Get the decimal number value of a numeric string.
public
static getDecimalValue(
$string :
string
)
: string|bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary token content string.
Tags
Return values
string|bool —Decimal number as a string or false if the passed parameter was not a numeric string. Note: floating point numbers with exponent will not be expanded, but returned as-is.
isDecimalInt()
Verify whether the contents of an arbitrary string represents a decimal integer.
public
static isDecimalInt(
$string :
string
)
: bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary string.
Tags
Return values
boolisHexidecimalInt()
Verify whether the contents of an arbitrary string represents a hexidecimal integer.
public
static isHexidecimalInt(
$string :
string
)
: bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary string.
Tags
Return values
boolisBinaryInt()
Verify whether the contents of an arbitrary string represents a binary integer.
public
static isBinaryInt(
$string :
string
)
: bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary string.
Tags
Return values
boolisOctalInt()
Verify whether the contents of an arbitrary string represents an octal integer.
public
static isOctalInt(
$string :
string
)
: bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary string.
Tags
Return values
boolisFloat()
Verify whether the contents of an arbitrary string represents a floating point number.
public
static isFloat(
$string :
string
)
: bool
Takes PHP 7.4 numeric literal separators in numbers into account.
Parameters
- $string : string
Arbitrary string.