FastDoubleParser (Artisynth API documentation)

java.lang.Object
- maspack.util.FastDoubleParser

```
public class FastDoubleParser
extends java.lang.Object
```
Class containing code from Werner Randelshofer's FastDoubleParser package, which is a Java port of Daniel Lemire's fast_float project. It can parse of double precision numbers up to 4 times faster than Double.parseDouble().
Licensing: MIT License
Copyright (c) 2024 Werner Randelshofer, Switzerland.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Some portions of the code have been derived from other projects. All these projects require that we include a copyright notice, and some require that we also include some text of their license file.
fast_double_parser, Copyright (c) 2022 Daniel Lemire. BSL License. https://github.com/lemire/fast_double_parser https://github.com/lemire/fast_double_parser/blob/07d9189a8fb815fe800cb15ca022e7a07093236e/LICENSE.BSL (The file 'thirdparty-LICENSE' is included in the sources and classes Jar files that are released by this project - as is required by that license.)
fast_float, Copyright (c) 2021 The fast_float authors. MIT License. https://github.com/fastfloat/fast_float https://github.com/fastfloat/fast_float/blob/cc1e01e9eee74128e48d51488a6b1df4a767a810/LICENSE-MIT (The file 'thirdparty-LICENSE' is included in the sources and classes Jar files that are released by this project - as is required by that license.)

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DOUBLE_EXPONENT_BIAS` Bias used in the exponent of a double.
`static int`	`DOUBLE_SIGNIFICAND_WIDTH` The number of bits in the significand, including the implicit bit.
`static java.lang.String`	`ILLEGAL_OFFSET_OR_ILLEGAL_LENGTH` Message text for the `IllegalArgumentException` that is thrown when offset or length are illegal
`static int`	`MAX_REQUIRED_DIGITS`
`static long`	`MINIMAL_NINETEEN_DIGIT_INTEGER` This is the smallest non-negative number that has 19 decimal digits.
`static java.lang.String`	`SYNTAX_ERROR` Message text for the `NumberFormatException` that is thrown when the syntax is illegal.
`static long`	`SYNTAX_ERROR_BITS` Uses the unused mantissa of a NaN value to encode a syntax error.

Constructor Summary

Constructors
Constructor and Description

FastDoubleParser()

Constructors
Constructor and Description
`FastDoubleParser()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static double`	`parseDouble(java.lang.CharSequence str)` Convenience method for calling `parseDouble(CharSequence, int, int)`.
`static double`	`parseDouble(java.lang.CharSequence str, int offset, int length)` Parses a `FloatingPointLiteral` from a `CharSequence` and converts it into a `double` value.
`long`	`parseFloatingPointLiteral(java.lang.CharSequence str, int offset, int length)` Parses a `FloatingPointLiteral` production with optional leading and trailing white space.
`static double`	`tryDecFloatToDoubleTruncated(boolean isNegative, long significand, int exponent, boolean isSignificandTruncated, int exponentOfTruncatedSignificand)` Tries to compute `significand * 10^exponent` exactly using a fast algorithm; and if `isNegative` is true, negate the result; the significand can be truncated.
`static long`	`tryToParseEightHexDigits(java.lang.CharSequence str, int offset)` Tries to parse eight digits at once using the 'SIMD within a register technique' (SWAR).
`static long`	`tryToParseEightHexDigitsUtf16(long first, long second)` Tries to parse eight hex digits from two longs using the 'SIMD within a register technique' (SWAR).
`static long`	`tryToParseEightHexDigitsUtf8(long chunk)` Tries to parse eight digits from a long using the 'SIMD within a register technique' (SWAR).

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DOUBLE_EXPONENT_BIAS
```
public static final int DOUBLE_EXPONENT_BIAS
```
    Bias used in the exponent of a double.
    
    See Also:
    
    Constant Field Values
  - DOUBLE_SIGNIFICAND_WIDTH
```
public static final int DOUBLE_SIGNIFICAND_WIDTH
```
    The number of bits in the significand, including the implicit bit.
    
    See Also:
    
    Constant Field Values
  - MAX_REQUIRED_DIGITS
```
public static final int MAX_REQUIRED_DIGITS
```
    See Also:
    
    Constant Field Values
  - MINIMAL_NINETEEN_DIGIT_INTEGER
```
public static final long MINIMAL_NINETEEN_DIGIT_INTEGER
```
    This is the smallest non-negative number that has 19 decimal digits.
    
    See Also:
    
    Constant Field Values
  - SYNTAX_ERROR
```
public static final java.lang.String SYNTAX_ERROR
```
    Message text for the NumberFormatException that is thrown when the syntax is illegal.
    
    See Also:
    
    Constant Field Values
  - SYNTAX_ERROR_BITS
```
public static final long SYNTAX_ERROR_BITS
```
    Uses the unused mantissa of a NaN value to encode a syntax error.
    
    See Also:
    
    Constant Field Values
  - ILLEGAL_OFFSET_OR_ILLEGAL_LENGTH
```
public static final java.lang.String ILLEGAL_OFFSET_OR_ILLEGAL_LENGTH
```
    Message text for the IllegalArgumentException that is thrown when offset or length are illegal
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - FastDoubleParser
```
public FastDoubleParser()
```
- Method Detail
  - parseDouble
```
public static double parseDouble(java.lang.CharSequence str)
                          throws java.lang.NumberFormatException
```
    Convenience method for calling parseDouble(CharSequence, int, int).
    
    Parameters:
    
    str - the string to be parsed
    
    Returns:
    
    the parsed value
    
    Throws:
    
    java.lang.NullPointerException - if the string is null
    
    java.lang.NumberFormatException - if the string can not be parsed successfully
  - parseDouble
```
public static double parseDouble(java.lang.CharSequence str,
                                 int offset,
                                 int length)
                          throws java.lang.NumberFormatException
```
    Parses a FloatingPointLiteral from a CharSequence and converts it into a double value.
    
    Parameters:
    
    str - the string to be parsed
    
    offset - the start offset of the FloatingPointLiteral in str
    
    length - the length of FloatingPointLiteral in str
    
    Returns:
    
    the parsed value
    
    Throws:
    
    java.lang.NullPointerException - if the string is null
    
    java.lang.IllegalArgumentException - if offset or length are illegal
    
    java.lang.NumberFormatException - if the string can not be parsed successfully
  - parseFloatingPointLiteral
```
public final long parseFloatingPointLiteral(java.lang.CharSequence str,
                                            int offset,
                                            int length)
```
    Parses a FloatingPointLiteral production with optional leading and trailing white space.
    
    FloatingPointLiteralWithWhiteSpace:
    
    [WhiteSpace] FloatingPointLiteral [WhiteSpace]
    
    Parameters:
    
    str - a string containing a FloatingPointLiteralWithWhiteSpace
    
    offset - start offset of FloatingPointLiteralWithWhiteSpace in str
    
    length - length of FloatingPointLiteralWithWhiteSpace in str
    
    Returns:
    
    the bit pattern of the parsed value, if the input is legal; otherwise, -1L.
  - tryDecFloatToDoubleTruncated
```
public static double tryDecFloatToDoubleTruncated(boolean isNegative,
                                                  long significand,
                                                  int exponent,
                                                  boolean isSignificandTruncated,
                                                  int exponentOfTruncatedSignificand)
```
    Tries to compute significand * 10^exponent exactly using a fast algorithm; and if isNegative is true, negate the result; the significand can be truncated.
    
    Parameters:
    
    isNegative - true if the sign is negative
    
    significand - the significand
    
    exponent - the exponent number (the power)
    
    isSignificandTruncated - true if significand has been truncated
    
    exponentOfTruncatedSignificand - the exponent number of the truncated significand
    
    Returns:
    
    the double value, or Double.NaN if the fast path failed.
  - tryToParseEightHexDigits
```
public static long tryToParseEightHexDigits(java.lang.CharSequence str,
                                            int offset)
```
    Tries to parse eight digits at once using the 'SIMD within a register technique' (SWAR).
    
    Parameters:
    
    str - a character sequence
    
    offset - the index of the first character in the character sequence
    
    Returns:
    
    the parsed digits or -1
  - tryToParseEightHexDigitsUtf16
```
public static long tryToParseEightHexDigitsUtf16(long first,
                                                 long second)
```
    Tries to parse eight hex digits from two longs using the 'SIMD within a register technique' (SWAR).
```
 char[] chars = ...;
 long first  = (long) chars[0] << 48
             | (long) chars[1] << 32
             | (long) chars[2] << 16
             | (long) chars[3];

 long second = (long) chars[4] << 48
             | (long) chars[5] << 32
             | (long) chars[6] << 16
             | (long) chars[7];
 
```
    Parameters:
    
    first - contains 4 utf-16 characters in big endian order
    
    second - contains 4 utf-16 characters in big endian order
    
    Returns:
    
    the parsed number, returns a negative value if the two longs do not contain 8 hex digits
  - tryToParseEightHexDigitsUtf8
```
public static long tryToParseEightHexDigitsUtf8(long chunk)
```
    Tries to parse eight digits from a long using the 'SIMD within a register technique' (SWAR).
    
    Parameters:
    
    chunk - contains 8 ascii characters in big endian order
    
    Returns:
    
    the parsed number, returns a negative value if value does not contain 8 digits

Class FastDoubleParser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DOUBLE_EXPONENT_BIAS

DOUBLE_SIGNIFICAND_WIDTH

MAX_REQUIRED_DIGITS

MINIMAL_NINETEEN_DIGIT_INTEGER

SYNTAX_ERROR

SYNTAX_ERROR_BITS

ILLEGAL_OFFSET_OR_ILLEGAL_LENGTH

Constructor Detail

FastDoubleParser

Method Detail

parseDouble

parseDouble

parseFloatingPointLiteral

tryDecFloatToDoubleTruncated

tryToParseEightHexDigits

tryToParseEightHexDigitsUtf16

tryToParseEightHexDigitsUtf8