Core Function Atol

Atol( <variable>, <count>, <start> )

Description

Convert string to Int64.

Parses the string interpreting its content as an integral number, which is returned as a value of type Int64.

The function first discards as many whitespace characters (as in isspace) as necessary until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many base-10 digits as possible, and interprets them as a numerical value.

The string can contain additional characters after those that form the integral number, which are ignored and have no effect on the behavior of this function.

If the first sequence of non-whitespace characters in string is not a valid integral number, or if no such sequence exists because either string is empty or it contains only whitespace characters, no conversion is performed and zero is returned.

Parameters

variable

A string beginning with the representation of a number.

(It does not need to fully be a number just begin with one)

count

Optional; If you supply a variable for this parameter it will be given the number of characters that the number is made up from out of the string.

See example.

start

Optional; Start position to begin searching the haystack from.

Can be negative this will cause it to start from haystack length - abs(start) instead.

Default: 0

Return Value

On success, the function returns the converted integral number as a Int64 value.

If no valid conversion could be performed, a zero value is returned.

Remarks

This is useful for when you wish to exact a number from a string even if the entire string is not suitable as a number and would normally return 0.

Using this you can extract the number you desire advance along the string using the count and continue.

Example

$var = atol( "777Hello" );
say $var; // Prints: 777

Example of getting how many characters were extracted from the string

$var = atol( "777Hello", $count );
say $var; // Prints: 777
say $count; // Prints: 3 // Since there were 3 chars in the number

Example of using start parameter

// Search begins at index 10 of the string so it is able to find a valid integer
$var = atol( "111 Hello 777 hmmm", null, 10 );
say $var; // Prints: 777

Example of using negative start parameter

// Search begins at index -3 (-3 turns out to be haystack length - abs(-3) of the string
// so it is able to find a valid floating-point
$var = atol( "Hello 777 h789", null, -3 );
say $var; // Prints: 789