package Torello.CSS;

import Torello.Java.Additional.ByRef;

import java.util.Vector;
import java.util.stream.IntStream;
import java.util.function.Consumer;
import java.math.BigDecimal;

/**
 * CSS-Tokenizer {@code Number}-Literal & {@code Number}-Token Class.
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="CSS_TOK")
public class Num extends CSSToken
    implements CharSequence, java.io.Serializable, Comparable<CharSequence>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Public & Final Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Though Java's {@code BigDecimal} may be an "overly ambitious" means of representing
     * CSS-Extracted Number-Literals, for now, this is how it is going to work.  After the
     * {@code 'javadoc'} stuff is done, maybe I'll change it to {@code java.lang.Number} or
     * something else.
     * 
     * <BR /><BR />Yes, a {@code "2em"} or {@code "10px"} would be saved as a BigDecimal
     * {@code 2} and {@code 10}.  The upside is that Java {@code double} and {@code integer}
     * primitives are easily extracted using {@code java.math.BigDecimal}'s exported methods.
     */
    public final BigDecimal number;

    /**
     * The parser will return true if the parsed Number-Literal had neither a "Decimal Part",
     * nor an "Exponent Part".  If either of these were present, then this {@code boolean} will
     * contain {@code FALSE}.
     * 
     * <BR /><BR />Note that even though something like {@code 5e2} - <I>which is actually just the
     * integer {@code 500}</I> - were parsed, this {@code boolean} would still evaluate to 
     * {@code FALSE}.
     */
    public final boolean integerOrNumber;

    /**
     * This shall contain one of three values: {@code '+', '-'} or ASCII {@code 0}.  If the parsed
     * Number-Literal began with a sign-character, then the appropriate sign-character will be
     * stored.  If the Number-Literal had no sign-character, then a {@code 0} is stored.
     */
    public final char signChar;


    // ********************************************************************************************
    // ********************************************************************************************
    // Private Constructor, API "is" and "if" Methods
    // ********************************************************************************************
    // ********************************************************************************************


    private Num(
            final int[]         css,
            final int           sPos,
            final int           ePos,
            final BigDecimal    number,
            final boolean       integerOrNumber,
            final char          signChar
        )
    {
        super(css, sPos, ePos);

        this.number             = number;
        this.integerOrNumber    = integerOrNumber;
        this.signChar           = signChar;
    }

    Num(
            final int[] css,
            final int   sPos,
            final int   ePos,
            final Num   n
        )
    { this(css, sPos, ePos, n.number, n.integerOrNumber, n.signChar); }

    @Override 
    public final boolean isNum() { return true; }

    @Override
    public final Num ifNum() { return this; }


    // ********************************************************************************************
    // ********************************************************************************************
    // User's Constructor: a static "build" method
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-TOK=Num DATA-P=numStr>
     * <EMBED CLASS='external-html' DATA-FILE-ID=BUILD_DESC>
     * @param numStr <EMBED CLASS='external-html' DATA-FILE-ID=BUILD_PARAM>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=BUILD_RET>
     * @throws TokenizeException <EMBED CLASS='external-html' DATA-FILE-ID=BUILD_TOK_EX>
     */
    @SuppressWarnings("unchecked")
    public static Num build(final String numStr)
    { return (Num) CSSToken.build(numStr, INPUT_CHECKER, Num::consume); }

    private static final CSSToken.InputChecker INPUT_CHECKER = (int[] css) ->
    {
        if (css.length < 1) throw new TokenizeException(Num.class);

        if (! Num.is(css, 0)) throw new TokenizeException
            ("String-text beginning does not constitute a valid CSS Number-Token");
    };


    // ********************************************************************************************
    // ********************************************************************************************
    // Tokenizer's "is" Method(s)
    // ********************************************************************************************
    // ********************************************************************************************


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Copied from:
    // https://drafts.csswg.org/css-syntax-3/#check-if-three-code-points-would-start-a-number
    // March 2024
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // 4.3.10. Check if three code points would start a number
    // 
    // This section describes how to check if three code points would start a number. The algorithm
    // described here can be called explicitly with three code points, or can be called with the
    // input stream itself. In the latter case, the three code points in question are the current
    // input code point and the next two input code points, in that order.
    // 
    // NOTE: This algorithm will not consume any additional code points.
    // 
    // Look at the first code point:
    // 
    // ** U+002B PLUS SIGN (+)
    // ** U+002D HYPHEN-MINUS (-)
    //      ==> 1) If the second code point is a digit, return true.
    //          2) Otherwise, if the second code point is a U+002E FULL STOP (.) and the third code
    //          point is a digit, return true.
    //          3) Otherwise, return false.
    // 
    // ** U+002E FULL STOP (.)
    //      ==> If the second code point is a digit, return true. Otherwise, return false.
    // 
    // ** digit
    //      ==> Return true.
    // 
    // ** anything else
    //      ==> Return false.
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * Checks whether or not the next token to consume is a number token, or number-subclass token.
     * 
     * <EMBED CLASS=defs DATA-TOK=Number-Literal
     *      DATA-URL=check-if-three-code-points-would-start-a-number DATA-OP=Check>
     * <EMBED CLASS=external-html DATA-FILE-ID=COPIED_CSS_WG>
     * <EMBED CLASS=external-html DATA-FILE-ID=CHECK_NUMBER_3CP>
     * @param css CSS-{@code String} as an array of code-points.
     * @param sPos The array-index where the tokenizer is to consume its next token
     * @return {@code TRUE} if and only if the next token in the array is a number
     */
    public static boolean is(int[] css, final int sPos)
    {
        final int c1 = ((sPos+0) < css.length) ? css[sPos+0] : 0;
        final int c2 = ((sPos+1) < css.length) ? css[sPos+1] : 0;
        final int c3 = ((sPos+2) < css.length) ? css[sPos+2] : 0;

        // U+002B PLUS SIGN (+)  **OR**  U+002D HYPHEN-MINUS (-)
        if ((c1 == '+') || (c1 == '-'))
        {
            // 1) If the second code point is a digit, return true.
            if ((c2 >= '0') && (c2 <= '9')) return true;

            // 2) Otherwise, if the second code point is a U+002E FULL STOP (.) and the third code
            //    point is a digit, return true.

            if ((c2 == '.') && (c3 >= '0') && (c3 <= '9'))  return true;

            // 3) Otherwise, return false.
            return false; 
        }

        // U+002E FULL STOP (.)
        // If the second code point is a digit, return true. Otherwise, return false.

        if (c1 == '.') return ((c2 >= '0') && (c2 <= '9'));

        // digit ==> Return true.
        if ((c1 >= '0') && (c1 <= '9')) return true;

        // anything else ==> Return false.
        return false;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // CONSUME
    // ********************************************************************************************
    // ********************************************************************************************


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Copied from:
    // https://drafts.csswg.org/css-syntax-3/#consume-a-numeric-token
    // March 27, 2024
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // 4.3.3. Consume a numeric token
    // 
    // This section describes how to consume a numeric token from a stream of code points. It
    // returns either a <number-token>, <percentage-token>, or <dimension-token>.
    // 
    // Consume a number and let number be the result.
    // 
    // If the next 3 input code points would start an ident sequence, then:
    // 
    // Create a <dimension-token> with the same value, type flag, and sign character as number, and
    // a unit set initially to the empty string.
    // 
    // Consume an ident sequence. Set the <dimension-token>’s unit to the returned value.
    // 
    // Return the <dimension-token>.
    // 
    // Otherwise, if the next input code point is U+0025 PERCENTAGE SIGN (%), consume it.
    // Create a <percentage-token> with the same value and sign character as number, and return it.
    //
    // Otherwise, create a <number-token> with the same value, type flag, and sign character as
    // number, and return it.
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * This is a tokenizer method which <B>"consumes"</B> the next {@code Number}-Token (or 
     * Number-Token Subclass) from the input Code-Point Array.
     * 
     * <EMBED CLASS=defs DATA-TOK=Numeric-Token DATA-URL=consume-a-numeric-token
     *  DATA-OP=Consume>
     * <EMBED CLASS=external-html DATA-FILE-ID=COPIED_CSS_WG>
     * <EMBED CLASS=external-html DATA-FILE-ID=NUMERIC_TOKEN>
     */
    protected static void consume(                              // When invoked from 'CSSTokenizer'
            final int[]                     css,                // C, int[] css
            final ByRef<Integer>            POS,                // P, array-pos loop-variable
            final Consumer<CSSToken>        returnParsedToken,  // T, Vector<CSSToken>.add
            final Consumer<TokenizeError>   errorEncountered    // E, Vector<TokenizeError>.add
        )
    {
        ByRef<Num> num = new ByRef<>();

        final int numEndPos = consumeNumber(css, POS.f, num);

        // If the next 3 input code points would start an ident sequence, then:
        if (Identifier.startsIdentSequence(css, numEndPos))
            Dimension.consume(css, POS, returnParsedToken, numEndPos, num.f);

        // Otherwise, if the next input code point is U+0025 PERCENTAGE SIGN (%), consume it.
        // Create a <percentage-token> with the same value and sign character as number, and return
        // it.

        else if ((numEndPos < css.length) && (css[numEndPos] == '%'))
        {
            returnParsedToken.accept(new Percentage(css, POS.f, numEndPos + 1, num.f));
            POS.f = numEndPos + 1;
        }

        // Otherwise, create a <number-token> with the same value, type flag, and sign character as
        // number, and return it.

        else
        {
            returnParsedToken.accept(num.f);
            POS.f = numEndPos;
        }
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Copied from:
    // https://drafts.csswg.org/css-syntax-3/#consume-a-number
    // March 27, 2024
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // 4.3.13. Consume a number
    // 
    // This section describes how to consume a number from a stream of code points. It returns a
    // numeric value, a string type which is either "integer" or "number", and an optional sign
    // character which is either "+", "-", or missing.
    // 
    // NOTE: This algorithm does not do the verification of the first few code points that are
    // necessary to ensure a number can be obtained from the stream. Ensure that the stream starts
    // with a number before calling this algorithm.
    // 
    // Execute the following steps in order:
    // 
    // 1) Let type be the string "integer". Let number part and exponent part be the empty string.
    // 
    // 2) If the next input code point is U+002B PLUS SIGN (+) or U+002D HYPHEN-MINUS (-), consume
    //    it. Append it to number part and set sign character to it.
    // 
    // 3) While the next input code point is a digit, consume it and append it to number part.
    // 
    // 4) If the next 2 input code points are U+002E FULL STOP (.) followed by a digit, then:
    //      1) Consume the next input code point and append it to number part.
    //      2) While the next input code point is a digit, consume it and append it to number part.
    //      3) Set type to "number".
    // 
    // 5) If the next 2 or 3 input code points are:
    //      * U+0045 LATIN CAPITAL LETTER E (E)
    //      * or U+0065 LATIN SMALL LETTER E (e).
    //
    //      optionally followed by:
    //      * U+002D HYPHEN-MINUS (-)
    //      * or U+002B PLUS SIGN (+),
    // 
    //      followed by a digit, then:
    //
    //      1) Consume the next input code point.
    //      2) If the next input code point is "+" or "-", consume it and append to exponent part
    //      3) While the next input code point is a digit, consume it and append it to exponent part.
    //      4) Set type to "number".
    //
    // 6) Let value be the result of interpreting number part as a base-10 number.
    //
    //      If exponent part is non-empty, interpret it as a base-10 integer, then raise 10 to the
    //      power of the result, multiply it by value, and set value to that result.
    // 
    // 7) Return value, type, and sign character.
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // I had to create this helper/data record ever since removing a portion of the "consumeNumber"
    // method to a second helper-method called "finishConsumeNumber".  Then / afterwards, in order
    // to pass all of the data needed to do the "Finish Consuming a Number" code, I just went
    // ahead and built this cute little "CNumRecord" - IN ORDER TO EASILY COPY THE RELEVANT 
    // VARIABLES TO THE "finishConsumeNumber" method.
    // 
    // This "CNumRecord" really wouldn't even hurt a fly.  Leave it alone, it only exists to split
    // up "consumeNumber" into two methods, while still having access to all the variables that are
    // fields inside this class.
    //
    // The reason that "consumeNumber", sort-of, "spilled over" into a second-method is because the
    // part that was put into the second-method is actually invoked from three different places
    // within the first...  You get that, right?

    private static class CNumRecord
    {
        final int           sPos;
        final int[]         css;
        final char          signChar;
        final ByRef<Num>    outNum;

        final IntStream.Builder numberPart    = IntStream.builder();
        final IntStream.Builder expPart       = IntStream.builder();

        private CNumRecord(
                final int[]         css,
                final int           sPos,
                final ByRef<Num>    outNum,
                final char          signChar
            )
        {
            this.css        = css;
            this.sPos       = sPos;
            this.signChar   = signChar;
            this.outNum     = outNum;
        }
    }

    /**
     * This is a tokenizer method which <B>"consumes"</B> the next {@code Number}-Literal from the
     * input Code-Point Array.
     * 
     * <EMBED CLASS=defs DATA-TOK=Number-Literal DATA-URL=consume-a-number DATA-OP=Consume>
     * <EMBED CLASS=external-html DATA-FILE-ID=COPIED_CSS_WG>
     * <EMBED CLASS=external-html DATA-FILE-ID=NUMBER>
     * <EMBED CLASS=external-html DATA-FILE-ID=NUMBER_TOK_SVG>
     */
    protected static int consumeNumber(
            final int[]         css,
            final int           sPos,
            final ByRef<Num>    outNum
        )
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 1) INITIALIZATION: 
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // a. Let type be the string "integer".
        // b. Let number part and exponent part be the empty string.

        boolean integerOrNumber = true;
        int     pos             = sPos;
        int     c               = css[pos++];


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 2) SIGN: If the next input code point is U+002B PLUS SIGN (+) or U+002D HYPHEN-MINUS (-)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // Consume it. Append it to number part and set sign character to it.
        //
        // Note that the 'Initializations' part (Step 1) spills over into step 2. The actual
        // little configuration-record that I had to eventually write isn't instantiated until
        // right here, in this if-branch.
        //
        // Remember that 'CNumRecord' sort of just stands for "Consume-Number-Record".

        final CNumRecord r;

        if ((c == '+') || (c == '-'))
        {
            // Instantiates a "Consume-Number-Record" with the Sign-Character set to +/-
            r = new CNumRecord(css, sPos, outNum, (char) c);

            r.numberPart.accept(c);

            c = css[pos++]; // No need to check for IOOB, this method is package-private, and
                            // it is only called if this contains a valid-number
                            // There is no valid number that is only a '+' or '-'
        }

        // This initializes a "Consume-Number-Record" with an empty Sign-Character
        else r = new CNumRecord(css, sPos, outNum, (char) 0);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 3) NUMBER: While the next input-cp is a digit, consume it and append it to number part
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        while ((c >= '0') && (c <= '9'))
        {
            r.numberPart.accept(c);

            if (pos < css.length)   c = css[pos++];
            else                    return finishConsumeNumber(r, pos, true);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 4) DECIMAL: If the next 2 input-cp's are U+002E FULL STOP (.) followed by a digit:
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // 1) Consume the next input code point and append it to number part.
        // 2) While the next input code point is a digit, consume it and append it to number part.
        // 3) Set type to "number".

        if (c == '.')
        {
            integerOrNumber = false;

            if ((pos < css.length) && Character.isDigit(css[pos]))
            {
                r.numberPart.accept('.'); // The '.' (dot / full-stop)
                c = css[pos++];

                // This 'while-loop' was EXACTLY BLOCK-COPIED from the one directly above
                while ((c >= '0') && (c <= '9'))
                {
                    r.numberPart.accept(c);
        
                    if (pos < css.length)   c = css[pos++];
                    else                    return finishConsumeNumber(r, pos, false);
                }
            }

            // The following 'else' branch is for cases such as "10. Chapter 5" (Where the '.' is
            // not part of the number)
            // 
            // Note that since 'pos' is currently pointing at the character after the '.' (or it is
            // pointing at css.length), '1' MUST BE SUBTRACTED FROM 'pos'

            else return finishConsumeNumber(r, pos - 1, true);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 5) EXPONENT: If the next 2 or 3 input code points are:  (This part sucks and is ugly)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // * U+0045 LATIN CAPITAL LETTER E (E)
        // * or U+0065 LATIN SMALL LETTER E (e).
        //
        // optionally followed by:
        // * U+002D HYPHEN-MINUS (-)
        // * or U+002B PLUS SIGN (+),
        // 
        // followed by a digit, then:
        //
        // 1) Consume the next input code point.
        // 2) If the next input code point is "+" or "-", consume it and append to exponent part
        // 3) While the next input code point is a digit, consume it and append it to exponent part.
        // 4) Set type to "number".

        if ((c != 'e') && (c != 'E'))

            // For this case, we have to "back the pointer up" by 1 place - a.k.a. pass "pos - 1"
            // This is because 'pos' is currently pointing to TWO CHARACTERS AFTER THE LAST NUMBER

            return finishConsumeNumber(r, pos - 1, integerOrNumber);

        // NOTE: From this point foward, 'c' IS GUARANTEED TO HOLD AN 'e' OR AN 'E'.
        //       This is very-likely (but not guaranteed) to be an "Exponent-Part"
        //
        // If the 'e' or 'E' happend to be an extranneous letter (for instance as in 5em), where
        // the 'e' was the first letter of the dimension-identifier "em", then that situation is
        // handled at the very end (on the last line) of this method.  In that particular situation
        // THIS WOULD NOT BE AN EXPONENT
        // 
        // The particular 'if-branch' (which is directly below) handles the case where there is an
        // 'e' or 'E', followed by AT LEAST ONE DIGIT.  If that has happend, then THIS IS
        // GUARANTEED TO BE AN EXPONENT.

        /*
        Don't delete this.  If there is any confusion, this is the only way to have even a
        prayer of understanding what all of these cute-little "++" even are.

        System.out.println(
            "c=" + ((char) c) + ", " +
            "pos=" + pos + ", " +
            "css[" + (pos) + "]=" + ((char) css[pos]) + ", " +
            (((pos+1) < css.length) ? ("css[" + (pos) + "]=" + ((char) css[pos])) : "")
        );
        */

        if (    (pos < css.length)
            &&  Character.isDigit(css[pos])
        )
        {
            r.expPart.accept(c);            // The letter 'e' or 'E'
            r.expPart.accept(css[pos++]);   // The first Digit of the Exponent

            // This type of coding is so different than anything I have done.  You just don't ever
            // mess with this type of stuff on a regular-basis.  It's exactly the type of code that
            // you would think is really easy and common.  Unfortunately, it is extremely uncommon
            // because once a parser has been written, you never have to go back and write one
            // again.
            // 
            // TESTING HELPS A LOT.  Everything is an "off-by-one error" in this Parser.  There are
            // SO MANY MICRO-VARIANTS TO WORRY ABOUT!  What if the CSS-String ends at the end of
            // this number?  Obviously that won't happen much, but if it does, the whole program
            // crashes.  What if a User is actually intending to use Scientific-Notation in his
            // css?  Obviously that's even less common, but if you don't get it right, the whole
            // program crashes.
            //
            // What if they are using Scientific-Notation with a Percentage?
            // As in: "+1e-3%"  Sound ridiculous?  CSS accepts that, so this code has to handle it

            while (pos < css.length)
            {
                if (Character.isDigit(c = css[pos++]))  r.expPart.accept(c);
                else                                    { pos--; break; }
            }

            return finishConsumeNumber(r, pos, false);
        }

        // This 'if-branch' handles the case where there was an 'e' or 'E', followed by a '+' or
        // '-' sign, followed by any digit.  THIS IS ALSO A CASE WHERE THERE **IS** AN EXPONENT

        if (    ((pos + 1) < css.length)
            &&  ((css[pos] == '+') || (css[pos] == '-'))
            &&  Character.isDigit(css[pos + 1])
        )
        {
            r.expPart.accept(c);            // The letter 'e' or 'E'
            r.expPart.accept(css[pos++]);   // The Sign Character for the Exponent
            r.expPart.accept(css[pos++]);   // The first Digit of the Exponent

            // This loop was block copied from the one directly above.  See that loop for a little
            // background information.

            while (pos < css.length)
            {
                if (Character.isDigit(c = css[pos++]))  r.expPart.accept(c);
                else                                    { pos--; break; }
            }

            return finishConsumeNumber(r, pos, false);
        }

        // This line of code will **ONLY** be reached if there was an 'e' or 'E' character that 
        // wasn't actually followed by a number.  Again the most common example whereby this line
        // would be reached are things such as "5em", where the 'e' turns out not to be an 
        // exponent-character, but rather the first letter in the "Dimension-String" "em"
        // (which, actually stands for "emphemeral unit", and means the current font-size)

        return finishConsumeNumber(r, pos - 1, integerOrNumber);
    }

    // Helper method for the above method
    private static int finishConsumeNumber(
            final CNumRecord    r,
            final int           pos,
            final boolean       integerOrNumber
        )
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 6) Let value be the result of interpreting number part as a base-10 number.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // If exponent part is non-empty, interpret it as a base-10 integer, then raise 10 to the
        // power of the result, multiply it by value, and set value to that result.

        final int[] numArr = r.numberPart.build().toArray();
        final int[] expArr = r.expPart.build().toArray();

        final String numStr = new String(numArr, 0, numArr.length);
        final String expStr = new String(expArr, 0, expArr.length);

        final String bdStr = numStr + expStr;

        /*
        It is true that a "CSS Parser" or a "CSS Tokenizer" isn't that difficult to write.  The
        catch is that this type of code is stuff that you just never write very often.  As such,
        observing this and debugging this isn't that fun.  Please don't delete this comment.  It is
        the only way to figure out the tiny-mistakes that can be made in "Num.consume"
        */

        /*
        System.out.println(
            "\tr.sPos:          " + r.sPos + '\n' +
            "\tpos:             " + pos + '\n' +
            "\tbdStr:           " + bdStr + '\n' +
            "\tnumStr:          " + numStr + '\n' +
            "\texpStr:          " + expStr + '\n' +
            "\tintegerOrNumber: " + integerOrNumber
        );
        */

        final BigDecimal bd = new BigDecimal(bdStr);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 7) Return value, type, and sign character.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        r.outNum.f = new Num(r.css, r.sPos, pos, bd, integerOrNumber, r.signChar);
        return pos;
    }
}