The need for parsing large numbers in a game is fairly limited. As such, in regards to parsing numbers from strings DBN has focused on doing the necessary things well, has eschewed complexities that very few would use, and sought to add value that many may find themselves using.

As such, number parsing in DBN is mostly limited to parsing the output from the Invariant (Decimal and Hexadecimal) formatters. This allows numbers to be easily serialized for transmission or encoding into save files. It's also handy to be able to parse a literal string from code into an FBigInteger.

But read on for a surprise feature that allows easy definition of interesting sequences of digits!

Parsing functionality is provided by UBigIntegerParser.

Focus on performance

In their main path of execution, both the Decimal and Hexadecimal parsing routines provide the minimum necessary to parse a number output from the respective Invariant formatter in the most efficient manner possible. The number parsing remains in native types for as long as feasible (19 digits at a time for decimal, 8 digits at a time for hexadecimal) and then is committed to the resulting FBigInteger.

Ironically, this very method of caching up to 18 (flushed on the 19th) decimal digits at a time is what enables the magic of the Digit Sequencer.

As a slight relaxation of strict invariant processing, digits a thru f for hexadecimal may be specified in either upper or lower case at very little cost to performance (uppercase per invariant formatting is slightly faster).

Digit Sequencer

Decimal number parsing has a "hidden" feature that allows the generation of interesting sequences of digits using relatively few characters. This functionality is free performance-wise, in that well-formed invariant decimal numbers will never get evaulated by the parser code that handles the Digit Sequencer.

In a decimal string parsed by UBigIntegerParser, a colon charactrer ":" begins a repeat command, which repeats the preceding block of up to 18 digits, possibly modifying it with each repeat iteration.

After a repeat command start, a number (in theory up to 100M-1 but in practice limited by memory and processing speed for numbers that large) specifies how many times the sequence should be repeated.

Following this number there may be an optional arithmetic operator (see below) and a second number, which will be applied to the repeating block of digits each iteration, while keeping the block of digits the same length.

A semicolon at any point terminates the repeat command and resumes processing, and can also be used to mark the beginning of a sequence of digits to repeat (by forcing the cached digits to be flushed to the result).

Warning: If you attempt to repeat more than 18 digits at a time, the results are undefined (unofficially, you will only repeat the number of digits since the last flush to the resulting FBigInteger).

Arithmetic Operators for digit sequencing:

+ - add
- - subtract
< - decimal rotate left
> - decimal rotate right (more to come) (extend/remove digits, digit swizzles, ?)

Digit Sequencing Examples

Note: Spaces have been inserted into resulting numbers below for clarity on how the digits relate to the input sequences)

12345:5 → 12345 12345 12345 12345 12345

12345:7+11111;00000 → 12345 23456 34567 45678 56789 67900 79011 00000

12345:5+11111;00000 → 12345 23456 34567 45678 56789 00000

66666;12345:5<1;00000 → 66666 12345 23451 34512 45123 51234 00000

66666;12345:5>1;00000 → 66666 12345 51234 45123 34512 23451 00000

23;42:3;99:20-11 → 23 42 42 42 99 88 77 66 55 44 33 22 11 00 89 78 67 56 45 34 23 12 01 90