@ (c) 2020 Aaron Taylor <ataylor at subgeniuskitty dot com>
@ See LICENSE.txt file for copyright and license details.
#ifndef VVS_STDLIB_CONVERT
#define VVS_STDLIB_CONVERT
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Convert null-terminated ASCII string to integer.
@ Result is negative if leading character is a hyphen ('-').
@ Result is positive if leading character is a plus sign ('+') or number.
@ Excluding the sign, parsing halts on the first non-numeric ASCII character.
@ Since all possible return values are valid, this subroutine simply returns
@ zero if no parseable number was found. Any stronger validity checks are the
@ responsibility of the caller. Similarly, no overflow checks are performed.
@ In addition to returning the parsed integer, also returns a pointer to the
@ first character after the parsed integer.
@ pointer to first character <-- TOS
@ pointer to last parsed character <-- TOS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTSSSSN | Mark: 110000 (atoi)
@ Check the first character and create a 'sign' flag on the stack.
@ Update the pointer to point to the first numeric character.
SSSSSTSTTSTN | PUSH 45 (ASCII '-')
NTSSSTTSSSSSSSSSSSSN | BRZ > 00110000 00000000 (found_minus_sign)
SSSSSTSTSTTN | PUSH 43 (ASCII '+')
NTSSSTTSSSSSSSSSSSTN | BRZ > 00110000 00000001 (found_plus_sign)
NSNSSTTSSSSSSSSSSTSN | JMP > 00110000 00000010 (found_digit)
NSSVSSTTSSSSSSSSSSSTN | Mark: 00110000 00000001 (found_plus_sign)
NSSVSSTTSSSSSSSSSSTSN | Mark: 00110000 00000010 (found_digit)
SSSTN | PUSH +1 (sign_flag)
NSNSSTTSSSSSSSSSSTTN | JMP > 00110000 00000011 (done_with_sign_flag)
NSSVSSTTSSSSSSSSSSSSN | Mark: 00110000 00000000 (found_minus_sign)
SSTTN | PUSH -1 (sign_flag)
NSSVSSTTSSSSSSSSSSTTN | Mark: 00110000 00000011 (done_with_sign_flag)
@ Create an accumulator on the TOS.
SSSSN | PUSH 0 (accumulator)
@ Main loop examines string one character at a time, building result in accumulator.
@ TOS> accumulator, string_ptr, sign_flag
NSSVSSTTSSSSSSSSSTSSN | Mark: 00110000 00000100 (atoi:main_loop)
NSTTTSSN | JSR > 1100 (deepdup)
NSTTSSSSTN | JSR > 100001 (isdigit)
NTSSSTTSSSSSSSSSTSTN | BRZ > 00110000 00000101 (found_end_of_number)
SSSSSTTSSSSN | PUSH 48 (ASCII '0')
NSNSSTTSSSSSSSSSTSSN | JMP > 00110000 00000100 (atoi:main_loop)
@ TOS> character, accumulator, string_ptr, sign_flag
NSSVSSTTSSSSSSSSSTSTN | Mark: 00110000 00000101 (found_end_of_number)
NSTTSTTN | JSR > 1011 (stackrotatereverse)