nom.tam.util
Class ByteFormatter

java.lang.Object
  extended by 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.


Constructor Summary
ByteFormatter()
           
 
Method Summary
 int alignFill(byte[] buffer, int offset, int len)
          Fill the buffer with blanks to align a field.
 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 array
 int 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.
 void setAlign(boolean val)
          Set the alignment flag.
 void setSimpleRange(double min, double max)
          Set the range of real numbers that will be formatted in non-scientific notation, i.e., .00001 rather than 1.0e-5.
 void setTruncateOnOverflow(boolean val)
          Set the truncation behavior.
 void setTruncationFill(char val)
          Set the truncation fill character.
 void setTruncationThrow(boolean throwException)
          Should truncations cause a truncation overflow?
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ByteFormatter

public ByteFormatter()
Method Detail

setTruncateOnOverflow

public void setTruncateOnOverflow(boolean val)
Set the truncation behavior.

Parameters:
val - If set to true (the default) then do not exceed the requested length. If a number cannot be sensibly formatted, the truncation fill character may be inserted.

setTruncationThrow

public void setTruncationThrow(boolean throwException)
Should truncations cause a truncation overflow?


setTruncationFill

public void setTruncationFill(char val)
Set the truncation fill character.

Parameters:
val - The character to be used in subsequent truncations.

setAlign

public void setAlign(boolean val)
Set the alignment flag.

Parameters:
val - Should numbers be right aligned?

setSimpleRange

public void setSimpleRange(double min,
                           double max)
Set the range of real numbers that will be formatted in non-scientific notation, i.e., .00001 rather than 1.0e-5. The sign of the number is ignored.

Parameters:
min - The minimum value for non-scientific notation.
max - The maximum value for non-scientific notation.

format

public int format(int val,
                  byte[] array)
           throws TruncationException
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.
Throws:
TruncationException

format

public int format(int val,
                  byte[] buf,
                  int off,
                  int len)
           throws TruncationException
Format an int into an existing array.

Parameters:
val - Integer to be formatted
buf - Buffer in which result is to be stored
off - Offset within buffer
len - Maximum length of integer
Returns:
offset of next unused character in input buffer.
Throws:
TruncationException

format

public int format(long val,
                  byte[] array)
           throws TruncationException
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.
Throws:
TruncationException

format

public int format(long val,
                  byte[] buf,
                  int off,
                  int len)
           throws TruncationException
Format a long into an existing array.

Parameters:
val - Long to be formatted
buf - Buffer in which result is to be stored
off - Offset within buffer
len - Maximum length of integer
Returns:
offset of next unused character in input buffer.
Throws:
TruncationException

format

public int format(boolean val,
                  byte[] array)
Format a boolean into an existing array.


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 formatted
array - 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(java.lang.String val,
                  byte[] array)
Insert a string at the beginning of an array


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.

format

public int format(float val,
                  byte[] array)
           throws TruncationException
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.
Throws:
TruncationException

format

public int format(float val,
                  byte[] buf,
                  int off,
                  int len)
           throws TruncationException
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 formatted
buf - Buffer in which result is to be stored
off - Offset within buffer
len - Maximum length of field
Returns:
Offset of next character in buffer.
Throws:
TruncationException

format

public int format(double val,
                  byte[] array)
           throws TruncationException
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.
Throws:
TruncationException

format

public int format(double val,
                  byte[] buf,
                  int off,
                  int len)
           throws TruncationException
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 formatted
buf - Buffer in which result is to be stored
off - Offset within buffer
len - Maximum length of integer
Returns:
offset of next unused character in input buffer.
Throws:
TruncationException

alignFill

public int alignFill(byte[] buffer,
                     int offset,
                     int len)
Fill the buffer with blanks to align a field.