Core Function StrToToul

StrToul( <variable>, <count>, <base>, <start> )

Description

Parses the string interpreting its content as an integral number of the specified base, which is returned as a UInt64 value. If count is not null (even 0 counts as not being null), the function also sets the value of count variable number of characters the return value will give.

The function first discards as many whitespace characters as necessary until the first non-whitespace character is found. Then, starting from this character, takes as many characters as possible that are valid following a syntax that depends on the base parameter, and interprets them as a numerical value. Finally, the number of characters found in the decimal is returned to the count variable (unless the variable is null).

If the value of base is zero, the syntax expected is similar to that of integer constants, which is formed by a succession of:

   An optional sign character (+ or -)

   An optional prefix indicating octal or hexadecimal base ("0" or "0x"/"0X" respectively)

   A sequence of decimal digits (if no base prefix was specified) or either octal or hexadecimal digits if a specific prefix is present

If the base value is between 2 and 36, the format expected for the integral number is a succession of any of the valid digits and/or letters needed to represent integers of the specified radix (starting from '0' and up to 'z'/'Z' for radix 36). The sequence may optionally be preceded by a sign (either + or -) and, if base is 16, an optional "0x" or "0X" prefix.

If the first sequence of non-whitespace characters in str is not a valid integral number as defined above, or if no such sequence exists because either str is empty or it contains only whitespace characters, no conversion is performed.

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.

Default: null

Warning even if you place a variable in this slot it is possible it may get modified its recommended to give this parameter a NULL and nothing else if you do not wish to use it.

base

Optional; The base of the number to look for

Default: 0

start

Optional; Start position to begin searching from.

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

Default: 0

Return Value

On success, the function returns the converted integral number as a UInt64 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 = StrToul( "777Hello" );
say $var; // Prints: 777

Example of getting how many characters were extracted from the string

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

Example of using base parameter to convert a hex number to an UInt64

$count = 0;
$var = StrToul( "411C88Hello", $count, 16 );
say $var; // Prints: 4267144
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 = StrToul( "111 Hello 777 hmmm", null, 0, 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 = StrToul( "Hello 777 h789", null, 0, -3 );
say $var; // Prints: 789