com.internationalnetwork.lang
Class Nybble

Object
  extended by Number
      extended by com.internationalnetwork.lang.Nybble
All Implemented Interfaces:
java.io.Serializable, Comparable

public final class Nybble
extends Number
implements Comparable

Instances of class Nybble represent primitive byte values because this is the smallest primitive available that can accomodate a nybble.

A nybble is a 4-bit value that can be represented entirely with any single hexadecimal digit (there are 16 unique digits in the hexadecimal numbering system).  Hexadecimal number are typically represented in pairs (or multiples of pairs) of hexadecimal digits.

Note:  The hexadecimal digits are:  0123456789ABCDEF

Additionally, this class provides various helper functions and variables useful in dealing with nybbles.

See Also:
Serialized Form

Field Summary
static byte MAX_VALUE
          A constant holding the maximum value a nybble can represent; 7 (or 23 -1).
static byte MIN_VALUE
          A constant holding the minimum value a nybble can represent; -8 (or -23).
static int SIZE
          The number of bits needed to represent a nybble.
static Class TYPE
          The primitive type byte is represented by this Class object because Java doesn't include a primitive type for nybble.
static String VERSION
          Version number of this Package (read-only).
 
Constructor Summary
Nybble(byte value)
          Create a Nybble object representing the value of the byte argument.
Nybble(int value)
          Create a Nybble object representing the value of the int argument.
Nybble(String s)
          Create a Nybble object representing the parsed value of the String argument.
 
Method Summary
 byte byteValue()
          Return the value of this Nybble as a byte.
static byte coerce(byte value)
          Strips off excess bits (the sign will be preserved), if any, and returns the remaining nybble presented as a byte.
static int coerce(int value)
          Strips off excess bits (the sign will be preserved), if any, and returns the remaining nybble presented as an integer.
 int compareTo(Nybble n)
          Compare two Nybbles numerically by comparing their nybble values.
 int compareTo(Object o)
          Behaves like compareTo(Nybble) unless the Object is not a Nybble.
static Nybble decode(String s)
          Convert the specified String into a Byte.
 double doubleValue()
          Return the value of this Nybble as a double.
 boolean equals(Object obj)
          Returns true if obj is an instance of Nybble and represents the same nybble value.
 float floatValue()
          Return the value of this Nybble as a float.
 int hashCode()
          Return a hashcode representing this Object.
 int intValue()
          Return the value of this Nybble as an integer.
 long longValue()
          Return the value of this Nybble as a long integer.
static byte parseNybble(String s)
          Converts the specified String into a nybble, presented as a byte because Java doesn't have a primitive nybble type.
static byte parseNybble(String s, int radix)
          Converts the specified String into a nybble, presented as a byte because Java doesn't have a primitive nybble type, using the specified radix (base).
 short shortValue()
          Return the value of this Nybble as a short.
 String toString()
          Converts the Nybble value to a String and assumes a radix of 10.
static String toString(byte nybble)
          Converts the nybble to a String and assumes a radix of 10.
static Nybble valueOf(String s)
          Creates a new Nybble object using the String and assuming a radix of 10.
static Nybble valueOf(String s, int radix)
          Creates a new Nybble object using the String and specified radix (base).
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

MAX_VALUE

public static final byte MAX_VALUE
A constant holding the maximum value a nybble can represent; 7 (or 23 -1).

See Also:
Constant Field Values

MIN_VALUE

public static final byte MIN_VALUE
A constant holding the minimum value a nybble can represent; -8 (or -23).

See Also:
Constant Field Values

SIZE

public static final int SIZE
The number of bits needed to represent a nybble.

See Also:
Constant Field Values

TYPE

public static final Class TYPE
The primitive type byte is represented by this Class object because Java doesn't include a primitive type for nybble.


VERSION

public static final String VERSION
Version number of this Package (read-only).

See Also:
Constant Field Values
Constructor Detail

Nybble

public Nybble(byte value)
Create a Nybble object representing the value of the byte argument.

Parameters:
value - the value to use
Throws:
NumberFormatException - if value is out of range

Nybble

public Nybble(int value)
Create a Nybble object representing the value of the int argument.

Parameters:
value - the value to use
Throws:
NumberFormatException - if value is out of range

Nybble

public Nybble(String s)
Create a Nybble object representing the parsed value of the String argument. If the value is out of range, or can't be parsed, then an exception will be thrown.

Parameters:
s - the string to convert
Throws:
NumberFormatException - if the string does not contain a Nybble
See Also:
valueOf(String)
Method Detail

byteValue

public byte byteValue()
Return the value of this Nybble as a byte.

Overrides:
byteValue in class Number
Returns:
the byte value

coerce

public static byte coerce(byte value)
Strips off excess bits (the sign will be preserved), if any, and returns the remaining nybble presented as a byte.

Parameters:
value - The byte value
Returns:
the nybble represented as a byte

coerce

public static int coerce(int value)
Strips off excess bits (the sign will be preserved), if any, and returns the remaining nybble presented as an integer.

Parameters:
value - The integer value
Returns:
the nybble represented as an integer

compareTo

public int compareTo(Nybble n)
Compare two Nybbles numerically by comparing their nybble values. The result is positive if the first is greater, negative if the second is greater, and 0 if the two are equal.

Parameters:
n - the Nybble to compare
Returns:
the comparison

compareTo

public int compareTo(Object o)
Behaves like compareTo(Nybble) unless the Object is not a Nybble. The result is positive if the first is greater, negative if the second is greater, and 0 if the two are equal.

Specified by:
compareTo in interface Comparable
Parameters:
o - the Object to compare
Returns:
the comparison
Throws:
ClassCastException - if the argument is not a Nybble

decode

public static Nybble decode(String s)
Convert the specified String into a Byte. The String may represent decimal, hexadecimal, or octal numbers.

The extended BNF grammar is as follows:

    DecodableString:
         ( [ - ] DecimalNumber )
       | ( [ - ] ( 0x | 0X
                 | # ) { HexDigit }+ )
       | ( [ - ] 0 { OctalDigit } )
    DecimalNumber:
           DecimalDigit except '0' { DecimalDigit }
    DecimalDigit:
           Character.digit(d, 10) has value 0 to 9
    OctalDigit:
           Character.digit(d, 8) has value 0 to 7
    DecimalDigit:
           Character.digit(d, 16) has value 0 to 15
    
Finally, the value must be in the range MIN_VALUE to MAX_VALUE, or an exception is thrown.

Parameters:
s - the String to interpret
Returns:
the value of the String as a Nybble represented as a Byte because Java doesn't have a primitive nybble type
Throws:
NumberFormatException - if s cannot be parsed as a nybble
NullPointerException - if s is null
See Also:
Integer.decode(String)

doubleValue

public double doubleValue()
Return the value of this Nybble as a double.

Specified by:
doubleValue in class Number
Returns:
the double value

equals

public boolean equals(Object obj)
Returns true if obj is an instance of Nybble and represents the same nybble value.

Overrides:
equals in class Object
Parameters:
obj - the object to compare
Returns:
whether these Objects are semantically equal

floatValue

public float floatValue()
Return the value of this Nybble as a float.

Specified by:
floatValue in class Number
Returns:
the float value

hashCode

public int hashCode()
Return a hashcode representing this Object. Nybble's hash code is simply its value.

Overrides:
hashCode in class Object
Returns:
this Object's hash code

intValue

public int intValue()
Return the value of this Nybble as an integer.

Specified by:
intValue in class Number
Returns:
the int value

longValue

public long longValue()
Return the value of this Nybble as a long integer.

Specified by:
longValue in class Number
Returns:
the long integer value

parseNybble

public static byte parseNybble(String s)
Converts the specified String into a nybble, presented as a byte because Java doesn't have a primitive nybble type. This function assumes a radix of 10.

Parameters:
s - the String to convert
Returns:
the String argument converted to a nybble, represented as a byte
Throws:
NumberFormatException - if s cannot be parsed as a nybble

parseNybble

public static byte parseNybble(String s,
                               int radix)
Converts the specified String into a nybble, presented as a byte because Java doesn't have a primitive nybble type, using the specified radix (base). The string must not be null or empty. It may begin with an optional minus sign ("-"), which will negate the answer, provided that there are also valid digits. Each digit is parsed as if by Character.digit(d, radix), and must be in the range 0 to radix - 1. Finally, the result must be within MIN_VALUE to MAX_VALUE, inclusive. Unlike Double.parseDouble, you may not have a leading plus sign ("+").

Parameters:
s - the String to convert
radix - the radix (base) to use in the conversion
Returns:
the String argument converted to a nybble, represented as a byte
Throws:
NumberFormatException - if s cannot be parsed as a nybble

shortValue

public short shortValue()
Return the value of this Nybble as a short.

Overrides:
shortValue in class Number
Returns:
the short integer value

toString

public String toString()
Converts the Nybble value to a String and assumes a radix of 10.

Overrides:
toString in class Object
Returns:
the String representation of this Nybble.
See Also:
Integer.toString()

toString

public static String toString(byte nybble)
Converts the nybble to a String and assumes a radix of 10.

Parameters:
nybble - the byte representing a nybble to convert to String
Returns:
the String representation of the argument
Throws:
NumberFormatException - if value is out of range

valueOf

public static Nybble valueOf(String s)
Creates a new Nybble object using the String and assuming a radix of 10.

Parameters:
s - the String to convert
Returns:
the new Nybble
Throws:
NumberFormatException - if s cannot be parsed as a nybble
See Also:
Nybble(String), parseNybble(String, int)

valueOf

public static Nybble valueOf(String s,
                             int radix)
Creates a new Nybble object using the String and specified radix (base).

Parameters:
s - the String to convert
radix - the radix (base) to convert with
Returns:
the new Nybble
Throws:
NumberFormatException - if s cannot be parsed as a nybble
See Also:
parseNybble(String, int)