Class fmtint

java.lang.Object
  |
  +--fmtint

public class fmtint
extends java.lang.Object

The fmtint class provides an extended set of integer formatting functions to fill a serious gap in the offerings of the Java libraries: namely, the inability to control field width, sign, digit grouping, 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 fmtint.java && java fmtint > fmtint.lst && diff okay/fmtint.lst fmtint.lst
 
or, better, as part of a larger validation suite:
    make check
 

These functions require only the standard 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.

Although functions are provided only for the long datatype, Java's widening rules for integer datatypes will automatically promote int, short, char, and byte datatypes to long in calls to these functions.

These functions are modelled on the Fortran 66/77/90/95/HPF Bw[.d], Iw[.d], Ow[.d], and Zw[.d] FORMAT items, with extensions for Ada-style based-integer literals (e.g., 16#ffff_ffff#), and support for left-, center-, and right-justification of strings in fields of arbitrary width.

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).

These functions make it much easier to translate existing Fortran and C/C++ code into Java: compare these statements:

        write (6,'(i14.3,2x, ''0b'', b0, 2x, ''0x'', z8.8)') i, j, k
        (void)printf("%14d  %x  0x%8.8x\n", i, j, k)
        System.out.println(fmtint.I(i,14,3) +
                           "  0b" + fmtint.B(j,0) +
                           "  0x" + fmtint.Z(k,8,8));
 

Since:
JDK1.0
Version:
1.00, [01-Jun-2002]
Author:
Nelson H. F. Beebe, Department of Mathematics, University of Utah, Salt Lake City, UT 84112-0090, USA

Constructor Summary
fmtint()
           
 
Method Summary
static java.lang.String B(long number)
          Convert number to an unsigned binary string representation right-justified in a field of minimal width.
static java.lang.String B(long number, int width)
          Convert number to an unsigned binary string representation right-justified in a field of at least width characters.
static java.lang.String B(long number, int width, int min_digits)
          Convert number to an unsigned binary string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String B(long number, int width, int min_digits, int ngroup)
          Convert number to an unsigned binary string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
static java.lang.String centerJustify(java.lang.String s, int pad_len)
          Return a copy of s centered, with blank padding if necessary, in a string of length pad_len characters.
static java.lang.String convertLong(long number)
           
static java.lang.String convertLong(long number, int base)
           
static java.lang.String convertLong(long number, int base, int width)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits, boolean require_sign)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits, boolean require_sign, boolean is_unsigned)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits, boolean require_sign, boolean is_unsigned, boolean is_ada_style)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits, boolean require_sign, boolean is_unsigned, boolean is_ada_style, char leading_pad, char separator, int ngroup)
           
static java.lang.String convertLong(long number, int base, int width, int min_digits, boolean require_sign, boolean is_unsigned, boolean is_ada_style, char leading_pad, char separator, int ngroup, int nphantom, int dot_after, boolean have_carry)
          Convert number to a string representation in the specified base.
static java.lang.String I(long number)
          Convert number to an optionally-signed decimal string representation right-justified in a field of minimum width.
static java.lang.String I(long number, int width)
          Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters.
static java.lang.String I(long number, int width, int min_digits)
          Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String I(long number, int width, int min_digits, int ngroup)
          Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
static java.lang.String leftJustify(java.lang.String s, int pad_len)
          Return a copy of s left justified, with blank padding on the right if necessary, in a string of length pad_len characters.
static void main(java.lang.String[] args)
          Run a test suite of the public functions in this class.
static java.lang.String O(long number)
          Convert number to an unsigned octal string representation right-justified in a field of minimal width.
static java.lang.String O(long number, int width)
          Convert number to an unsigned octal string representation right-justified in a field of at least width characters.
static java.lang.String O(long number, int width, int min_digits)
          Convert number to an unsigned octal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String O(long number, int width, int min_digits, int ngroup)
          Convert number to an unsigned octal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
static java.lang.String R(long number)
          Convert number to a string in base 10 right-justified in a field of minimal width.
static java.lang.String R(long number, int base)
          Convert number to a string in base base right-justified in a field of minimal width.
static java.lang.String R(long number, int base, int width)
          Convert number to a string in base base right-justified in a field of at least width characters.
static java.lang.String R(long number, int base, int width, int min_digits)
          Convert number to a string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String R(long number, int base, int width, int min_digits, int ngroup)
          Convert number to an string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
static java.lang.String rightJustify(java.lang.String s, int pad_len)
          Return a copy of s right justified, with blank padding on the left if necessary, in a string of length pad_len characters.
static java.lang.String S(long number)
          Convert number to a signed (if negative) Ada-style string in base 10 right-justified in a field of minimal width.
static java.lang.String S(long number, int base)
          Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of minimal width.
static java.lang.String S(long number, int base, int width)
          Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters.
static java.lang.String S(long number, int base, int width, int min_digits)
          Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String S(long number, int base, int width, int min_digits, int ngroup)
          Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
static java.lang.String Z(long number)
          Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters.
static java.lang.String Z(long number, int width)
          Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters.
static java.lang.String Z(long number, int width, int min_digits)
          Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
static java.lang.String Z(long number, int width, int min_digits, int ngroup)
          Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

fmtint

public fmtint()
Method Detail

centerJustify

public static java.lang.String centerJustify(java.lang.String s,
                                             int pad_len)
Return a copy of s centered, with blank padding if necessary, in a string of length pad_len characters.
Parameters:
s - String to be centered.
pad_len - Length of output string.
Returns:
The centered string.

leftJustify

public static java.lang.String leftJustify(java.lang.String s,
                                           int pad_len)
Return a copy of s left justified, with blank padding on the right if necessary, in a string of length pad_len characters.
Parameters:
s - String to be left justified.
pad_len - Length of output string.
Returns:
The left-justified string.

rightJustify

public static java.lang.String rightJustify(java.lang.String s,
                                            int pad_len)
Return a copy of s right justified, with blank padding on the left if necessary, in a string of length pad_len characters.
Parameters:
s - String to be right justified.
pad_len - Length of output string.
Returns:
The right-justified string.

B

public static java.lang.String B(long number)
Convert number to an unsigned binary string representation right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

B

public static java.lang.String B(long number,
                                 int width)
Convert number to an unsigned binary string representation right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
width - Width of returned string.
Returns:
String containing the converted number.

B

public static java.lang.String B(long number,
                                 int width,
                                 int min_digits)
Convert number to an unsigned binary string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

B

public static java.lang.String B(long number,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to an unsigned binary string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

I

public static java.lang.String I(long number)
Convert number to an optionally-signed decimal string representation right-justified in a field of minimum width.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

I

public static java.lang.String I(long number,
                                 int width)
Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
width - Width of returned string.
Returns:
String containing the converted number.

I

public static java.lang.String I(long number,
                                 int width,
                                 int min_digits)
Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

I

public static java.lang.String I(long number,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to an optionally-signed decimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

O

public static java.lang.String O(long number)
Convert number to an unsigned octal string representation right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

O

public static java.lang.String O(long number,
                                 int width)
Convert number to an unsigned octal string representation right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
width - Width of returned string.
Returns:
String containing the converted number.

O

public static java.lang.String O(long number,
                                 int width,
                                 int min_digits)
Convert number to an unsigned octal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

O

public static java.lang.String O(long number,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to an unsigned octal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

R

public static java.lang.String R(long number)
Convert number to a string in base 10 right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

R

public static java.lang.String R(long number,
                                 int base)
Convert number to a string in base base right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
base - Output number base.
Returns:
String containing the converted number.

R

public static java.lang.String R(long number,
                                 int base,
                                 int width)
Convert number to a string in base base right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
Returns:
String containing the converted number.

R

public static java.lang.String R(long number,
                                 int base,
                                 int width,
                                 int min_digits)
Convert number to a string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

R

public static java.lang.String R(long number,
                                 int base,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to an string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

S

public static java.lang.String S(long number)
Convert number to a signed (if negative) Ada-style string in base 10 right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

S

public static java.lang.String S(long number,
                                 int base)
Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of minimal width.
Parameters:
number - Number to be converted.
base - Output number base.
Returns:
String containing the converted number.

S

public static java.lang.String S(long number,
                                 int base,
                                 int width)
Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
Returns:
String containing the converted number.

S

public static java.lang.String S(long number,
                                 int base,
                                 int width,
                                 int min_digits)
Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

S

public static java.lang.String S(long number,
                                 int base,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to a signed (if negative) Ada-style string in base base right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits, grouping digits into ngroup digits from the right, separated by an underscore.
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

Z

public static java.lang.String Z(long number)
Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

Z

public static java.lang.String Z(long number,
                                 int width)
Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters.
Parameters:
number - Number to be converted.
width - Width of returned string.
Returns:
String containing the converted number.

Z

public static java.lang.String Z(long number,
                                 int width,
                                 int min_digits)
Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

Z

public static java.lang.String Z(long number,
                                 int width,
                                 int min_digits,
                                 int ngroup)
Convert number to an unsigned hexadecimal string representation right-justified in a field of at least width characters, with leading zeros if necessary to produce at least min_digits digits.
Parameters:
number - Number to be converted.
width - Width of returned string.
min_digits - Minimum number of digits required.
ngroup - Number of digits between separator characters.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits,
                                           boolean require_sign,
                                           boolean is_unsigned,
                                           boolean is_ada_style,
                                           char leading_pad,
                                           char separator,
                                           int ngroup,
                                           int nphantom,
                                           int dot_after,
                                           boolean have_carry)
Convert number to a string representation in the specified base. This function serves as the core of several much-simpler-to-use functions that provide for conversion of binary integer values to string representations.

The string will be contained in a field of at least width characters, and will have at least min_digits (with leading zeros if necessary).

If base is out of the range 2..36, then base = 10 is silently assumed.

The number is considered signed unless is_unsigned is true and, in addition, the base is a power of two (that is, 2, 4, 8, 16, or 32), in which case, if the number is negative, it is equivalent to that value + 264.

If is_ada_style is true, use the Ada numeric literal form base-in-decimal#<digits>#. Otherwise, the base is not recorded in the output string.

For example, in Ada style, 2#1111_1111_1111_1111# == 16#ffff# == 8#177_777# == 10#256# == 256.

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 are optionally separated by separator (typically, the culture-neutral underscore, or culture-dependent comma or period) in groups of ngroup digits, counting from the right. Grouping is suppressed if ngroup <= 0.

A variant with three additional final arguments is provided for use by the companion fmtflt class; for integer conversions, simply omit them. The additional arguments are:

nphantom is the number of phantom (unstored and invisible) digits to the right of the number for the purposes of digit grouping (normal value: 0).

dot_after is the number of digits from the right after which a decimal point is to be inserted (normal value: -1).

have_carry is true if there is a carry digit to propagate into the converted integer (normal value: false).

dot_after and have_carry are ignored if is_unsigned is true.

Simpler-to-use functions of the same name, but with fewer arguments, are available: the first argument is mandatory, but you may omit trailing arguments after the last one needed.

Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
require_sign - true if a leading sign is required, else false.
is_unsigned - true if the input number is treated as unsigned, else false.
is_ada_style - true if the output formatting is Ada style, 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.
nphantom - Number of phantom digits (for grouping control).
dot_after - Number of digits from the right to place a decimal point after.
have_carry - true if there is an input carry digit, else false.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number)
Parameters:
number - Number to be converted.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base)
Parameters:
number - Number to be converted.
base - Output number base.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits,
                                           boolean require_sign)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
require_sign - true if a leading sign is required, else false.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits,
                                           boolean require_sign,
                                           boolean is_unsigned)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
require_sign - true if a leading sign is required, else false.
is_unsigned - true if the input number is treated as unsigned, else false.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits,
                                           boolean require_sign,
                                           boolean is_unsigned,
                                           boolean is_ada_style)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
require_sign - true if a leading sign is required, else false.
is_unsigned - true if the input number is treated as unsigned, else false.
is_ada_style - true if the output formatting is Ada style, else false.
Returns:
String containing the converted number.

convertLong

public static java.lang.String convertLong(long number,
                                           int base,
                                           int width,
                                           int min_digits,
                                           boolean require_sign,
                                           boolean is_unsigned,
                                           boolean is_ada_style,
                                           char leading_pad,
                                           char separator,
                                           int ngroup)
Parameters:
number - Number to be converted.
base - Output number base.
width - Width of returned string.
min_digits - Minimum number of digits required.
require_sign - true if a leading sign is required, else false.
is_unsigned - true if the input number is treated as unsigned, else false.
is_ada_style - true if the output formatting is Ada style, 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.
Returns:
String containing the converted number.

main

public static void main(java.lang.String[] args)
Run a test suite of the public functions in this class.
Parameters:
args[] - Command-line arguments (ignored).