|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--fmtflt
The fmtflt
class provides an extended set of
floating-point formatting functions to fill a serious gap in the
offerings of the Java libraries: namely, the inability to control
field width, sign, digit grouping, precision, exponential vs. fixed
notation, and justification in numeric output.
This class file contains a built-in validation suite, easily run in most UNIX-like Java implementations like this:
javac fmtflt.java && java fmtflt && diff okay/fmtflt.lst -or, better, as part of a larger validation suite:
make check
These functions require the companion extmath
and
fmtint
classes, plus the standard
java.lang.Float
, java.lang.Double
,
java.lang.Math
, and java.lang.String
classes from JDK 1.0 or later. None of the functions used are
deprecated in any of the Java levels 1.0, 1.1, 1.2, 1.3, or 1.4.
These functions are modelled on the Fortran 66/77/90/95/HPF
Fw[.d]
, Dw.d[Ee]
, Ew.d[Ee]
,
and Gw.d[Ee]
FORMAT
items, and the
corresponding C/C++ printf()
%w[.d]f
,
%w[.d]g
, and %w[.d]e
format items, with
additional inspiration from the Ada programming language.
However, unlike Fortran, whose punched-card legacy views column
alignment of greater importance than correct output, filling fields
with asterisks when they are too short to contain the numeric value,
in these functions, field widths automatically expand to contain
the value (just as format items in the C printf()
family do).
Output values are rounded to nearest: rounding occurs if the first omitted digit is 5 or greater.
Signed zero, NaN, and signed Infinity are all recognized and supported. Sadly, standard Java classes in implementations before JDK 1.4 cannot input NaN and Infinity, even though they can output those values. All Java implementations that I have tested handle signed zero correctly.
These functions make it much easier to translate existing Fortran and C/C++ code into Java: compare these statements:
write (6,'(f14.3, 2x, e15.4, 2x, g15.4)') x, y, z (void)printf("%14.3f %15.4e 15.4g\n", x, y, z) System.out.println(fmtflt.F(x,14,3) + " " + fmtflt.E(y,15.4) + " " + fmtflt.G(z,15.4));
Limitations: These functions build upon the
fmtinit.convertLong()
functions, and thus, the number of
figures that can be output is limited to scaled numbers that can be
represented as Java 64-bit long
integers. While this
is sufficient for Java 32-bit float
and 64-bit
double
data types, it does limit the fractional digit
field widths to at most 17 decimal digits. Requests for more digits
will be silently reduced to that limit. This restriction could be
lifted in the future by fancier scaling, or use of multiple-precision
arithmetic, or reimplementation of the digit conversion in
floating-point arithmetic, but it is unlikely to be of practical
significance for most numerical applications, and particularly for
the translation of existing numerical Fortran, C, or C++ code to
Java.
Constructor Summary | |
fmtflt()
|
Method Summary | |
static java.lang.String |
convertDouble(double number,
int width,
int fractional_digits)
|
static java.lang.String |
convertDouble(double number,
int width,
int fractional_digits,
int exponent_digits)
|
static java.lang.String |
convertDouble(double number,
int width,
int fractional_digits,
int exponent_digits,
boolean require_sign)
|
static java.lang.String |
convertDouble(double number,
int width,
int fractional_digits,
int exponent_digits,
boolean require_sign,
char leading_pad,
char separator,
int ngroup)
Convert number to a decimal string representation. |
static java.lang.String |
convertFloat(float number,
int width,
int fractional_digits)
|
static java.lang.String |
convertFloat(float number,
int width,
int fractional_digits,
int exponent_digits)
|
static java.lang.String |
convertFloat(float number,
int width,
int fractional_digits,
int exponent_digits,
boolean require_sign)
|
static java.lang.String |
convertFloat(float number,
int width,
int fractional_digits,
int exponent_digits,
boolean require_sign,
char leading_pad,
char separator,
int ngroup)
Convert number to a decimal string representation. |
static java.lang.String |
E(double number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and a 3-digit exponent field. |
static java.lang.String |
E(double number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 decimal places,
and a 3-digit exponent field. |
static java.lang.String |
E(double number,
int width,
int fractional_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and a 3-digit exponent field. |
static java.lang.String |
E(double number,
int width,
int fractional_digits,
int exponent_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits digits. |
static java.lang.String |
E(double number,
int width,
int fractional_digits,
int exponent_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits digits, grouping digits into
ngroup digits, separated by an underscore. |
static java.lang.String |
E(float number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and a 3-digit exponent field. |
static java.lang.String |
E(float number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 decimal places,
and a 3-digit exponent field. |
static java.lang.String |
E(float number,
int width,
int fractional_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and a 3-digit exponent field. |
static java.lang.String |
E(float number,
int width,
int fractional_digits,
int exponent_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits digits. |
static java.lang.String |
E(float number,
int width,
int fractional_digits,
int exponent_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits digits, grouping digits into
ngroup digits, separated by an underscore. |
static java.lang.String |
F(double number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and no exponent field. |
static java.lang.String |
F(double number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 decimal places,
and no exponent field. |
static java.lang.String |
F(double number,
int width,
int fractional_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and no exponent field. |
static java.lang.String |
F(double number,
int width,
int fractional_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and no exponent field, grouping digits into
ngroup digits, separated by an underscore. |
static java.lang.String |
F(float number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and no exponent field. |
static java.lang.String |
F(float number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 decimal places,
and no exponent field. |
static java.lang.String |
F(float number,
int width,
int fractional_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and no exponent field. |
static java.lang.String |
F(float number,
int width,
int fractional_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with fractional_digits
decimal places, and no exponent field, grouping digits into
ngroup digits, separated by an underscore. |
static java.lang.String |
G(double number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 total digits. |
static java.lang.String |
G(double number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 total digits. |
static java.lang.String |
G(double number,
int width,
int total_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
digits. |
static java.lang.String |
G(double number,
int width,
int total_digits,
int exponent_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
total digits. |
static java.lang.String |
G(double number,
int width,
int total_digits,
int exponent_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
total digits, grouping digits into ngroup digits,
separated by an underscore. |
static java.lang.String |
G(float number)
Convert number to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 total digits. |
static java.lang.String |
G(float number,
int width)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with a default of 6 total digits. |
static java.lang.String |
G(float number,
int width,
int total_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
digits. |
static java.lang.String |
G(float number,
int width,
int total_digits,
int exponent_digits)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
total digits. |
static java.lang.String |
G(float number,
int width,
int total_digits,
int exponent_digits,
int ngroup)
Convert number to an optionally-signed decimal string
representation right-justified in a field of at least
width characters, with total_digits
total digits, grouping digits into ngroup digits,
separated by an underscore. |
static void |
main(java.lang.String[] args)
Run a test suite of the public functions in this class. |
static java.lang.String |
unseparate(java.lang.String s)
Return a copy of s with all underscore separator
characters removed. |
static java.lang.String |
unseparate(java.lang.String s,
char separator)
Return a copy of s with all separator
characters removed. |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Constructor Detail |
public fmtflt()
Method Detail |
public static java.lang.String convertDouble(double number, int width, int fractional_digits, int exponent_digits, boolean require_sign, char leading_pad, char separator, int ngroup)
number
to a decimal string representation.
This function serves as the core of several much-simpler-to-use
functions that provide for conversion of binary double-precision
floating-point values to string representations.
The string will be contained in a field of at least
width
characters, with fractional_digits
digits after the decimal point.
The number of digits in the exponent field is
exponent_digits
. If that value is zero, the
exponent field is omitted, and fixed formatting (e.g., 1.234) is
used instead.
The field is filled, if needed, on the left with
leading_pad
characters, and a sign which is
mandatory if require_sign
is true, and otherwise
supplied only if the number is negative.
Digits in the integer and fractional part are optionally separated
by separator
(typically, the culture-neutral
underscore, or culture-dependent comma) in groups of
ngroup
digits, counting from the right. Grouping is
suppressed if ngroup
<= 0.
Simpler-to-use functions of the same name, but with fewer arguments, are available: the first three arguments are mandatory, but you may omit trailing arguments after the last one needed.
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.require_sign
- true
if a leading sign is required, else false
.leading_pad
- Character used to fill leading empty positions.separator
- Character used to separate digits for readability.ngroup
- Number of digits between separator characters.public static java.lang.String convertDouble(double number, int width, int fractional_digits)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String convertDouble(double number, int width, int fractional_digits, int exponent_digits)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.public static java.lang.String convertDouble(double number, int width, int fractional_digits, int exponent_digits, boolean require_sign)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.require_sign
- true
if a leading sign is required, else false
.public static java.lang.String convertFloat(float number, int width, int fractional_digits, int exponent_digits, boolean require_sign, char leading_pad, char separator, int ngroup)
number
to a decimal string representation.
This function serves as the core of several much-simpler-to-use
functions that provide for conversion of binary single-precision
floating-point values to string representations.
The string will be contained in a field of at least
width
characters, with fractional_digits
digits after the decimal point.
The number of digits in the exponent field is
exponent_digits
. If that value is zero, the
exponent field is omitted, and fixed formatting (e.g., 1.234) is
used instead.
The field is filled, if needed, on the left with
leading_pad
characters, and a sign which is
mandatory if require_sign
is true, and otherwise
supplied only if the number is negative.
Digits in the integer and fractional part are optionally separated
by separator
(typically, the culture-neutral
underscore, or culture-dependent comma) in groups of
ngroup
digits, counting from the right. Grouping is
suppressed if ngroup
<= 0.
Simpler-to-use functions of the same name, but with fewer arguments, are available: the first three arguments are mandatory, but you may omit trailing arguments after the last one needed.
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.require_sign
- true
if a leading sign is required, else false
.leading_pad
- Character used to fill leading empty positions.separator
- Character used to separate digits for readability.ngroup
- Number of digits between separator characters.public static java.lang.String convertFloat(float number, int width, int fractional_digits)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String convertFloat(float number, int width, int fractional_digits, int exponent_digits)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.public static java.lang.String convertFloat(float number, int width, int fractional_digits, int exponent_digits, boolean require_sign)
number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.require_sign
- true
if a leading sign is required, else false
.public static java.lang.String E(double number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and a 3-digit exponent field.number
- Number to be converted.public static java.lang.String E(double number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 decimal places,
and a 3-digit exponent field.number
- Number to be converted.width
- Width of returned string.public static java.lang.String E(double number, int width, int fractional_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and a 3-digit exponent field.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String E(double number, int width, int fractional_digits, int exponent_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits
digits.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.public static java.lang.String E(double number, int width, int fractional_digits, int exponent_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits
digits, grouping digits into
ngroup
digits, separated by an underscore.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.ngroup
- Number of digits between separator characters.public static java.lang.String F(double number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and no exponent field.number
- Number to be converted.public static java.lang.String F(double number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 decimal places,
and no exponent field.number
- Number to be converted.width
- Width of returned string.public static java.lang.String F(double number, int width, int fractional_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and no exponent field.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String F(double number, int width, int fractional_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and no exponent field, grouping digits into
ngroup
digits, separated by an underscore.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.ngroup
- Number of digits between separator characters.public static java.lang.String G(double number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 total digits. A 3-digit exponent field is provided
only if the number cannot be displayed with the same digit count
in a suitable F-type format.number
- Number to be converted.public static java.lang.String G(double number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 total digits.
A 3-digit exponent field is provided only if the number cannot
be displayed with the same digit count in a suitable F-type
format.number
- Number to be converted.width
- Width of returned string.public static java.lang.String G(double number, int width, int total_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
digits. A 3-digit exponent field is provided only if the number
cannot be displayed with the same digit count in a suitable
F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.public static java.lang.String G(double number, int width, int total_digits, int exponent_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
total digits. A 3-digit exponent field is provided only if the
number cannot be displayed with the same digit count in a
suitable F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.exponent_digits
- Number of exponent digits.public static java.lang.String G(double number, int width, int total_digits, int exponent_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
total digits, grouping digits into ngroup
digits,
separated by an underscore. An exponent field of
exponent_digits
digits is provided only if the
number cannot be displayed with the same digit count in a
suitable F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.exponent_digits
- Number of exponent digits.ngroup
- Number of digits between separator characters.public static java.lang.String E(float number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and a 3-digit exponent field.number
- Number to be converted.public static java.lang.String E(float number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 decimal places,
and a 3-digit exponent field.number
- Number to be converted.width
- Width of returned string.public static java.lang.String E(float number, int width, int fractional_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and a 3-digit exponent field.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String E(float number, int width, int fractional_digits, int exponent_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits
digits.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.public static java.lang.String E(float number, int width, int fractional_digits, int exponent_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and an exponent field of
exponent_digits
digits, grouping digits into
ngroup
digits, separated by an underscore.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.exponent_digits
- Number of exponent digits.ngroup
- Number of digits between separator characters.public static java.lang.String F(float number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 decimal places, and no exponent field.number
- Number to be converted.public static java.lang.String F(float number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 decimal places,
and no exponent field.number
- Number to be converted.width
- Width of returned string.public static java.lang.String F(float number, int width, int fractional_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and no exponent field.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.public static java.lang.String F(float number, int width, int fractional_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with fractional_digits
decimal places, and no exponent field, grouping digits into
ngroup
digits, separated by an underscore.number
- Number to be converted.width
- Width of returned string.fractional_digits
- Number of fractional digits.ngroup
- Number of digits between separator characters.public static java.lang.String G(float number)
number
to an optionally-signed decimal string
representation right-justified in a field of minimal width, with a
default of 6 total digits. A 3-digit exponent field is provided
only if the number cannot be displayed with the same digit count
in a suitable F-type format.number
- Number to be converted.public static java.lang.String G(float number, int width)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with a default of 6 total digits.
A 3-digit exponent field is provided only if the number cannot
be displayed with the same digit count in a suitable F-type
format.number
- Number to be converted.width
- Width of returned string.public static java.lang.String G(float number, int width, int total_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
digits. A 3-digit exponent field is provided only if the number
cannot be displayed with the same digit count in a suitable
F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.public static java.lang.String G(float number, int width, int total_digits, int exponent_digits)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
total digits. A 3-digit exponent field is provided only if the
number cannot be displayed with the same digit count in a
suitable F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.exponent_digits
- Number of exponent digits.public static java.lang.String G(float number, int width, int total_digits, int exponent_digits, int ngroup)
number
to an optionally-signed decimal string
representation right-justified in a field of at least
width
characters, with total_digits
total digits, grouping digits into ngroup
digits,
separated by an underscore. An exponent field of
exponent_digits
digits is provided only if the
number cannot be displayed with the same digit count in a
suitable F-type format.
If total_digits
is less than or equal to zero, it
is reset to the default of 6.
number
- Number to be converted.width
- Width of returned string.total_digits
- Total number of digits.exponent_digits
- Number of exponent digits.ngroup
- Number of digits between separator characters.public static java.lang.String unseparate(java.lang.String s, char separator)
s
with all separator
characters removed.
This function can be used to reduce numeric strings made more
readable by the insertion of separators to something that Java
class library functions can parse.s
- Input string.separator
- Separator character.s
with separator characters removed.public static java.lang.String unseparate(java.lang.String s)
s
with all underscore separator
characters removed.
This function can be used to reduce numeric strings made more
readable by the insertion of separators to something that Java
class library functions can parse.s
- Input string.s
with underscore separator
characters removed.public static void main(java.lang.String[] args)
args[]
- Command-line arguments (ignored).
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |