Class ByteFormatter
- java.lang.Object
-
- nom.tam.util.ByteFormatter
-
public final class ByteFormatter extends java.lang.Object
This class provides mechanisms for efficiently formatting numbers and Strings. Data is appended to existing byte arrays. Note that the formatting of real or double values may differ slightly (in the last bit) from the standard Java packages since this routines are optimized for speed rather than accuracy.The methods in this class create no objects.
If a number cannot fit into the requested space the truncateOnOverlow flag controls whether the formatter will attempt to append it using the available length in the output (a la C or Perl style formats). If this flag is set, or if the number cannot fit into space left in the buffer it is 'truncated' and the requested space is filled with a truncation fill character. A TruncationException may be thrown if the truncationThrow flag is set.
This class does not explicitly support separate methods for formatting reals in exponential notation. Real numbers near one are by default formatted in decimal notation while numbers with large (or very negative) exponents are formatted in exponential notation. By setting the limits at which these transitions take place the user can force either exponential or decimal notation.
-
-
Field Summary
Fields Modifier and Type Field Description private static double
DEFAULT_SIMPLE_MAX
Maximum magnitude to print in non-scientific notation.private static double
DEFAULT_SIMPLE_MIN
Minimum magnitude to print in non-scientific notation.private static byte[]
DIGITS
Digits.private static long
DOUBLE_EXPONENT_BIT_MASK
private static int
DOUBLE_EXPONENT_EXCESS
private static long
DOUBLE_EXPONENT_NORMALIZE_BIT
The hidden bit in normalized double numbers.private static int
DOUBLE_MIN_EXPONENT
Used to check if double is normalizedprivate static int
DOUBLE_SHIFT_BASE
private static int
DOUBLE_SHIFT_LIMIT
private static long
DOUBLE_VALUE_BIT_MASK
private static int
FLOAT_EXPONENT_BIT_MASK
private static int
FLOAT_EXPONENT_EXCESS
private static int
FLOAT_EXPONENT_NORMALIZE_BIT
The hidden bit in normalized floating point numbers.private static int
FLOAT_MIN_EXPONENT
Used to check if float is normalizedprivate static int
FLOAT_SHIFT_BASE
private static int
FLOAT_SHIFT_LIMIT
private static int
FLOAT_VALUE_BIT_MASK
private static double
I_LOG_10
static java.lang.String
INFINITY
private static long
LONG_TO_INT_MODULO
private static int
MAX_LONG_LENGTH
private static int
MAXIMUM_SINGLE_DIGIT_INTEGER
The maximum single digit integer.private static int
MAXIMUM_TWO_DIGIT_INTEGER
The maximum two digit integer.static java.lang.String
NEGATIVE_INFINITY
static java.lang.String
NOT_A_NUMBER
private static int
NUMBER_BASE
The underlying number base used in this class.private static double[]
NUMBER_BASE_POWERS
Powers of 10.private byte[]
tbuf1
Internal buffers used in formatting fieldsprivate byte[]
tbuf2
private static int
TEMP_BUFFER_SIZE
private static byte
TRUNCATION_FILL
What do we use to fill when we cannot print the number?Default is often used in Fortran.private static int
ZERO_POW
What index of tenpow is 10^0
-
Constructor Summary
Constructors Constructor Description ByteFormatter()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private int
combineReal(double val, byte[] buf, int off, int len, byte[] mant, int lmant, int shift)
This method formats a double given a decimal mantissa and exponent information.int
format(boolean val, byte[] array)
Format a boolean into an existing array.int
format(boolean val, byte[] array, int off, int len)
Format a boolean into an existing arrayint
format(double val, byte[] array)
Format a double into an array.int
format(double val, byte[] buf, int off, int len)
Format a double into an existing character array.int
format(float val, byte[] array)
Format a float into an array.int
format(float val, byte[] buf, int off, int len)
Format a float into an existing byteacter array.int
format(int val, byte[] array)
Format an int into an array.int
format(int val, byte[] buf, int off, int len)
Format an int into an existing array.int
format(long val, byte[] array)
Format a long into an array.int
format(long val, byte[] buf, int off, int len)
Format a long into an existing array.int
format(java.lang.String val, byte[] array)
Insert a string at the beginning of an array.int
format(java.lang.String val, byte[] array, int off, int len)
Insert a String into an existing character array.private int
mantissa(byte[] mant, int lmant, int exp, boolean simple, byte[] buf, int off, int len)
Write the mantissa of the number.private void
truncationFiller(byte[] buffer, int offset, int length)
Fill the buffer with truncation characters.
-
-
-
Field Detail
-
NOT_A_NUMBER
public static final java.lang.String NOT_A_NUMBER
- See Also:
- Constant Field Values
-
INFINITY
public static final java.lang.String INFINITY
- See Also:
- Constant Field Values
-
NEGATIVE_INFINITY
public static final java.lang.String NEGATIVE_INFINITY
- See Also:
- Constant Field Values
-
DEFAULT_SIMPLE_MAX
private static final double DEFAULT_SIMPLE_MAX
Maximum magnitude to print in non-scientific notation.- See Also:
- Constant Field Values
-
DEFAULT_SIMPLE_MIN
private static final double DEFAULT_SIMPLE_MIN
Minimum magnitude to print in non-scientific notation.- See Also:
- Constant Field Values
-
DIGITS
private static final byte[] DIGITS
Digits. We could handle other bases by extending or truncating this list and changing the division by 10 (and it's factors) at various locations.
-
DOUBLE_EXPONENT_BIT_MASK
private static final long DOUBLE_EXPONENT_BIT_MASK
- See Also:
- Constant Field Values
-
DOUBLE_EXPONENT_EXCESS
private static final int DOUBLE_EXPONENT_EXCESS
- See Also:
- Constant Field Values
-
DOUBLE_EXPONENT_NORMALIZE_BIT
private static final long DOUBLE_EXPONENT_NORMALIZE_BIT
The hidden bit in normalized double numbers.- See Also:
- Constant Field Values
-
DOUBLE_MIN_EXPONENT
private static final int DOUBLE_MIN_EXPONENT
Used to check if double is normalized- See Also:
- Constant Field Values
-
DOUBLE_SHIFT_BASE
private static final int DOUBLE_SHIFT_BASE
- See Also:
- Constant Field Values
-
DOUBLE_SHIFT_LIMIT
private static final int DOUBLE_SHIFT_LIMIT
- See Also:
- Constant Field Values
-
DOUBLE_VALUE_BIT_MASK
private static final long DOUBLE_VALUE_BIT_MASK
- See Also:
- Constant Field Values
-
FLOAT_EXPONENT_BIT_MASK
private static final int FLOAT_EXPONENT_BIT_MASK
- See Also:
- Constant Field Values
-
FLOAT_EXPONENT_EXCESS
private static final int FLOAT_EXPONENT_EXCESS
- See Also:
- Constant Field Values
-
FLOAT_EXPONENT_NORMALIZE_BIT
private static final int FLOAT_EXPONENT_NORMALIZE_BIT
The hidden bit in normalized floating point numbers.- See Also:
- Constant Field Values
-
FLOAT_MIN_EXPONENT
private static final int FLOAT_MIN_EXPONENT
Used to check if float is normalized- See Also:
- Constant Field Values
-
FLOAT_SHIFT_BASE
private static final int FLOAT_SHIFT_BASE
- See Also:
- Constant Field Values
-
FLOAT_SHIFT_LIMIT
private static final int FLOAT_SHIFT_LIMIT
- See Also:
- Constant Field Values
-
FLOAT_VALUE_BIT_MASK
private static final int FLOAT_VALUE_BIT_MASK
- See Also:
- Constant Field Values
-
I_LOG_10
private static final double I_LOG_10
-
LONG_TO_INT_MODULO
private static final long LONG_TO_INT_MODULO
- See Also:
- Constant Field Values
-
MAX_LONG_LENGTH
private static final int MAX_LONG_LENGTH
- See Also:
- Constant Field Values
-
MAXIMUM_SINGLE_DIGIT_INTEGER
private static final int MAXIMUM_SINGLE_DIGIT_INTEGER
The maximum single digit integer. Special case handling when rounding up and when incrementing the exponent.- See Also:
- Constant Field Values
-
MAXIMUM_TWO_DIGIT_INTEGER
private static final int MAXIMUM_TWO_DIGIT_INTEGER
The maximum two digit integer. When we increment an exponent of this value, the exponent gets longer. Don't need to worry about 999 since exponents can't be that big.- See Also:
- Constant Field Values
-
TEMP_BUFFER_SIZE
private static final int TEMP_BUFFER_SIZE
- See Also:
- Constant Field Values
-
NUMBER_BASE
private static final int NUMBER_BASE
The underlying number base used in this class.- See Also:
- Constant Field Values
-
NUMBER_BASE_POWERS
private static final double[] NUMBER_BASE_POWERS
Powers of 10. We over extend on both sides. These should perhaps be tabulated rather than computed though it may be faster to calculate them than to read in the extra bytes in the class file.
-
TRUNCATION_FILL
private static final byte TRUNCATION_FILL
What do we use to fill when we cannot print the number?Default is often used in Fortran.- See Also:
- Constant Field Values
-
ZERO_POW
private static final int ZERO_POW
What index of tenpow is 10^0
-
tbuf1
private final byte[] tbuf1
Internal buffers used in formatting fields
-
tbuf2
private final byte[] tbuf2
-
-
Method Detail
-
combineReal
private int combineReal(double val, byte[] buf, int off, int len, byte[] mant, int lmant, int shift)
This method formats a double given a decimal mantissa and exponent information.- Parameters:
val
- The original numberbuf
- Output bufferoff
- Offset into bufferlen
- Maximum number of characters to use in buffer.mant
- A decimal mantissa for the number.lmant
- The number of characters in the mantissashift
- The exponent of the power of 10 that we shifted val to get the given mantissa.- Returns:
- Offset of next available character in buffer. @ * if the value was truncated
-
format
public int format(boolean val, byte[] array)
Format a boolean into an existing array.- Parameters:
val
- value to writearray
- the array to fill- Returns:
- Offset of next available character in buffer.
-
format
public int format(boolean val, byte[] array, int off, int len)
Format a boolean into an existing array- Parameters:
val
- The boolean to be formattedarray
- The buffer in which to format the data.off
- The starting offset within the buffer.len
- The maximum number of characters to use use in formatting the number.- Returns:
- Offset of next available character in buffer.
-
format
public int format(double val, byte[] array)
Format a double into an array.- Parameters:
val
- The double to be formatted.array
- The array in which to place the result.- Returns:
- The number of characters used. @ * if the value was truncated
-
format
public int format(double val, byte[] buf, int off, int len)
Format a double into an existing character array.This is hard to do exactly right... The JDK code does stuff with rational arithmetic and so forth. We use a much simpler algorithm which may give an answer off in the lowest order bit. Since this is pure Java, it should still be consistent from machine to machine.
Recall that the binary representation of the double is of the form d = 0.bbbbbbbb x 2n where there are up to 53 binary digits in the binary fraction (including the assumed leading 1 bit for normalized numbers). We find a value m such that 10m d is between 253 and 263. This product will be exactly convertible to a long with no loss of precision. Getting the decimal representation for that is trivial (see formatLong). This is a decimal mantissa and we have an exponent (-m). All we have to do is manipulate the decimal point to where we want to see it. Errors can arise due to roundoff in the scaling multiplication, but should be no more than a single bit.
- Parameters:
val
- Double to be formattedbuf
- Buffer in which result is to be storedoff
- Offset within bufferlen
- Maximum length of integer- Returns:
- offset of next unused character in input buffer. @ * if the value was truncated
-
format
public int format(float val, byte[] array)
Format a float into an array.- Parameters:
val
- The float to be formatted.array
- The array in which to place the result.- Returns:
- The number of characters used. @ * if the value was truncated
-
format
public int format(float val, byte[] buf, int off, int len)
Format a float into an existing byteacter array.This is hard to do exactly right... The JDK code does stuff with rational arithmetic and so forth. We use a much simpler algorithm which may give an answer off in the lowest order bit. Since this is pure Java, it should still be consistent from machine to machine.
Recall that the binary representation of the float is of the form d = 0.bbbbbbbb x 2n where there are up to 24 binary digits in the binary fraction (including the assumed leading 1 bit for normalized numbers). We find a value m such that 10m d is between 224 and 232. This product will be exactly convertible to an int with no loss of precision. Getting the decimal representation for that is trivial (see formatInteger). This is a decimal mantissa and we have an exponent ( -m). All we have to do is manipulate the decimal point to where we want to see it. Errors can arise due to roundoff in the scaling multiplication, but should be very small.
- Parameters:
val
- Float to be formattedbuf
- Buffer in which result is to be storedoff
- Offset within bufferlen
- Maximum length of field- Returns:
- Offset of next character in buffer. @ * if the value was truncated
-
format
public int format(int val, byte[] array)
Format an int into an array.- Parameters:
val
- The int to be formatted.array
- The array in which to place the result.- Returns:
- The number of characters used. @ * if the value was truncated
-
format
public int format(int val, byte[] buf, int off, int len)
Format an int into an existing array.- Parameters:
val
- Integer to be formattedbuf
- Buffer in which result is to be storedoff
- Offset within bufferlen
- Maximum length of integer- Returns:
- offset of next unused character in input buffer.
-
format
public int format(long val, byte[] array)
Format a long into an array.- Parameters:
val
- The long to be formatted.array
- The array in which to place the result.- Returns:
- The number of characters used. @ * if the value was truncated
-
format
public int format(long val, byte[] buf, int off, int len)
Format a long into an existing array.- Parameters:
val
- Long to be formattedbuf
- Buffer in which result is to be storedoff
- Offset within bufferlen
- Maximum length of integer- Returns:
- offset of next unused character in input buffer. @ * if the value was truncated
-
format
public int format(java.lang.String val, byte[] array)
Insert a string at the beginning of an array. * @return Offset of next available character in buffer.- Parameters:
val
- The string to be inserted. A null string will insert len spaces.array
- The buffer in which to insert the string.- Returns:
- Offset of next available character in buffer.
-
format
public int format(java.lang.String val, byte[] array, int off, int len)
Insert a String into an existing character array. If the String is longer than len, then only the the initial len characters will be inserted.- Parameters:
val
- The string to be inserted. A null string will insert len spaces.array
- The buffer in which to insert the string.off
- The starting offset to insert the string.len
- The maximum number of characters to insert.- Returns:
- Offset of next available character in buffer.
-
mantissa
private int mantissa(byte[] mant, int lmant, int exp, boolean simple, byte[] buf, int off, int len)
Write the mantissa of the number. This method addresses the subtleties involved in rounding numbers.
-
truncationFiller
private void truncationFiller(byte[] buffer, int offset, int length)
Fill the buffer with truncation characters. After filling the buffer, a TruncationException will be thrown if the appropriate flag is set.
-
-