org.hermit.utils
Class CharFormatter

java.lang.Object
  extended by org.hermit.utils.CharFormatter

public class CharFormatter
extends java.lang.Object

Utilities for quickly formatting numbers into character buffers, without memory allocations. These routines are much faster than using String.format, and can be used to avoid GC.

Author:
Ian Cameron Smith

Method Summary
static void blank(char[] buf, int off, int field)
          Fill a field of a given width with spaces.
static void formatChar(char[] buf, int off, char val, int field, boolean right)
          Format a single character into a fixed-width field.
static int formatDegMin(char[] buf, int off, double angle)
          Format an angle for user display in degrees and minutes.
static int formatDegMin(char[] buf, int off, double angle, char pos, char neg, boolean space)
          Format an angle as a string in the format "W171°15.165'".
static void formatFloat(char[] buf, int off, double val, int field, int frac)
          Format a floating-point value into a fixed-width field, with sign.
static void formatFloat(char[] buf, int off, double val, int field, int frac, boolean signed)
          Format a floating-point value into a fixed-width field.
static void formatHex(char[] buf, int off, int val, int field)
          Format an unsigned integer into a fixed-width field in hexadecimal.
static void formatInt(char[] buf, int off, int val, int field, boolean signed)
          Format an integer right-aligned into a fixed-width field.
static void formatInt(char[] buf, int off, int val, int field, boolean signed, boolean lz)
          Format an integer right-aligned into a fixed-width field.
static void formatIntLeft(char[] buf, int off, int val, int field, boolean signed)
          Format an integer left-aligned into a fixed-width field.
static int formatLatLon(char[] buf, int off, double lat, double lon, boolean space)
          Format a latitude and longitude for user display in degrees and minutes.
static void formatString(char[] buf, int off, java.lang.String val, int field)
          Format a string left-aligned into a fixed-width field.
static void formatString(char[] buf, int off, java.lang.String val, int field, boolean right)
          Format a string into a fixed-width field.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

blank

public static final void blank(char[] buf,
                               int off,
                               int field)
Fill a field of a given width with spaces.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
field - Width of the field to blank. -1 means use all available space.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatString

public static final void formatString(char[] buf,
                                      int off,
                                      java.lang.String val,
                                      int field)
Format a string left-aligned into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatString

public static final void formatString(char[] buf,
                                      int off,
                                      java.lang.String val,
                                      int field,
                                      boolean right)
Format a string into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
right - Iff true, format the text right-aligned; else left-aligned.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatChar

public static final void formatChar(char[] buf,
                                    int off,
                                    char val,
                                    int field,
                                    boolean right)
Format a single character into a fixed-width field. The remainder is filled with spaces. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
right - Iff true, format the text right-aligned; else left-aligned.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatInt

public static final void formatInt(char[] buf,
                                   int off,
                                   int val,
                                   int field,
                                   boolean signed)
Format an integer right-aligned into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space. The value will be padded on the left with spaces if smaller than the field.
signed - Iff true, add a sign character, space for positive, '-' for negative. This takes up one place in the given field width.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.
java.lang.IllegalArgumentException - Negative value given and signed == false.

formatInt

public static final void formatInt(char[] buf,
                                   int off,
                                   int val,
                                   int field,
                                   boolean signed,
                                   boolean lz)
Format an integer right-aligned into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
signed - Iff true, add a sign character, space for positive, '-' for negative. This takes up one place in the given field width.
lz - Iff true, pad with leading zeros; otherwise, pad on the left with spaces.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.
java.lang.IllegalArgumentException - Negative value given and signed == false.

formatIntLeft

public static final void formatIntLeft(char[] buf,
                                       int off,
                                       int val,
                                       int field,
                                       boolean signed)
Format an integer left-aligned into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space. If the value is smaller than the field, pads on the right with space.
signed - Iff true, add a sign character, space for positive, '-' for negative. This takes up one place in the given field width, so positive values will have a space on the left. Iff false, no space is taken for the sign; values must be positive, and will begin in the first position.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.
java.lang.IllegalArgumentException - Negative value given and signed == false.

formatHex

public static final void formatHex(char[] buf,
                                   int off,
                                   int val,
                                   int field)
Format an unsigned integer into a fixed-width field in hexadecimal. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatFloat

public static final void formatFloat(char[] buf,
                                     int off,
                                     double val,
                                     int field,
                                     int frac)
Format a floating-point value into a fixed-width field, with sign. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
frac - Number of digits after the decimal.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.
java.lang.IllegalArgumentException - Negative value given and signed == false.

formatFloat

public static final void formatFloat(char[] buf,
                                     int off,
                                     double val,
                                     int field,
                                     int frac,
                                     boolean signed)
Format a floating-point value into a fixed-width field. MUCH faster than String.format.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
val - The value to format.
field - Width of the field to format in. -1 means use all available space.
frac - Number of digits after the decimal.
signed - Iff true, add a sign character, space for positive, '-' for negative. This takes up one place in the given field width.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.
java.lang.IllegalArgumentException - Negative value given and signed == false.

formatDegMin

public static int formatDegMin(char[] buf,
                               int off,
                               double angle)
Format an angle for user display in degrees and minutes. Negative angles are formatted with a "-" sign, as in "-171°15.165'". Place the result in the supplied buffer.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
angle - The angle to format.
Returns:
Number of characters written.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatDegMin

public static int formatDegMin(char[] buf,
                               int off,
                               double angle,
                               char pos,
                               char neg,
                               boolean space)
Format an angle as a string in the format "W171°15.165'". Place the result in the supplied buffer.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
angle - The angle to format.
pos - Sign character to use if positive.
neg - Sign character to use if negative.
space - If true, leave a space after the sign and degrees. Otherwise pack them.
Returns:
Number of characters written.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.

formatLatLon

public static int formatLatLon(char[] buf,
                               int off,
                               double lat,
                               double lon,
                               boolean space)
Format a latitude and longitude for user display in degrees and minutes. Place the result in the supplied buffer.

Parameters:
buf - Buffer to place the result in.
off - Offset within buf to start writing at.
lat - The latitude.
lon - The longitude.
space - If true, leave a space after the sign and degrees. Otherwise pack them.
Returns:
Number of characters written.
Throws:
java.lang.ArrayIndexOutOfBoundsException - Buffer is too small.