mil.navy.nps.util
Class UnsignedByte

java.lang.Object
  java.lang.Number
      mil.navy.nps.util.UnsignedByte

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable, SerializationInterface

public class UnsignedByte

extends java.lang.Number

implements SerializationInterface, java.lang.Cloneable

Version:

1.0

Author:

Don McGregor (http://www.npsnet.org/~mcgredo)

Location:

http://www.web3D.org/WorkingGroups/vrtp/mil/navy/nps/dis/UnsignedByte.java

Summary:

This class implements a 8-bit unsigned integer, which Java doesn't natively handle.

Explanation:

An 8-bit unsigned int, which Java doesn't natively handle. So we have to wrap this object around the data. When serialized, this will be written out as an 8-bit quantity.

Note that you can't retrieve the value of this as a byte, simply because a negative value for an unsigned byte (as the signed value 242 would be) is invalid, and can't be represented. So we have to promote the bloody thing to an int.

Hmmmmm....should the internal representation be a short or a byte? I vote for byte, since it requires less storage in memory, and we might have a lot of these floating about. But we're constantly promoting it to an int or short anyway...

This implementation works by exploiting the characteristics of how numbers are stored internally. Just about all systems, except for a few obsolete machines, use "two's-complement" format for storing integer values. A signed byte will have this sequence as more and more bits are flipped on:

0,1,2,3....125,126,127,-128,-127,-127,...-1

The values roll over from (2^7)-1 to -(2^7) at the midpoint. Adding one to 127 will result in -128, adding two results in -127, etc. We can fake up unsigned bytes by exploiting this behavior. The maximum an unsigned byte can represent is 255 (2^8 - 1) so we can translate between a negative value and its unsigned positive representation with this formula:

255 + _data + 1

which means that -128 is mapped to 128, -126 to 129, and so on.

This implements the Cloneable interface, which means that when we clone() something we can do a bitwise field copy (shallow copy). This needs to change if we ever have any actual objects contained in this class.

History:

04Oct96 /Don McGregor /New

06Oct96 /Don McGregor /changed name to UnsignedByte, added testing methods, placed in package mil.navy.nps.dis

10Mar97 /Don McGregor /changes for javadoc

8Dec97 /Ronan Fauglas /changes for documentation templates + complements in documentation

References:

DIS-Java-VRML Working Group: http://www.web3D.org/WorkingGroups/vrtp/dis-java-vrml/

See Also:

UnsignedShort, UnsignedInt, SerializationInterface, Serialized Form

Field Summary

static short

MAX_UNSIGNED_BYTE_VALUE

Constructor Summary

UnsignedByte()
Contructs a new UnsignedByte object and intializes its value to 0.

UnsignedByte(byte pData)
Constructs an UnsignedByte object from a signed byte, throws an exception if the paraneter is out of range.

UnsignedByte(int pData)
Constructs an UnsignedByte object from an int, throws an exception if the parameter is out of range.

UnsignedByte(short pData)
Constructs an UnsignedByte object from a short, throws an exception if the parameter is out of range.

Method Summary

java.lang.Object	clone() Makes a deep copy of the current UnsignedByte object.
void	debugTest() Of debugging interest only.
void	deSerialize(java.io.DataInputStream pInputStream) Reads an UnsignedByte in from DIS format.
double	doubleValue() Returns the current value of this object as a double float, after conversion.
float	floatValue() Returns a the current value of this object as a float, after conversion.
int	intValue() Returns the current value of this object as an int, after conversion.
long	longValue() Returns the current value of this object as a long, after conversion.
void	serialize(java.io.DataOutputStream pOutputStream) Writes out an UnsignedByte to an output stream.
java.lang.String	toString() Returns a String object representing this UnsignedByte value.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_UNSIGNED_BYTE_VALUE

public static final short MAX_UNSIGNED_BYTE_VALUE

See Also:

Constant Field Values

Constructor Detail

UnsignedByte

public UnsignedByte()

Contructs a new UnsignedByte object and intializes its value to 0.

UnsignedByte

public UnsignedByte(byte pData)

Constructs an UnsignedByte object from a signed byte, throws an exception if the paraneter is out of range.

Parameters:

pData - >=0

Throws:

java.lang.RuntimeException - if pData is out of range

UnsignedByte

public UnsignedByte(short pData)

Constructs an UnsignedByte object from a short, throws an exception if the parameter is out of range.

Parameters:

pData - >=0, <=MAX_UNSIGNED_BYTE_VALUE

Throws:

java.lang.RuntimeException - if the parameter is out of range

UnsignedByte

public UnsignedByte(int pData)

Constructs an UnsignedByte object from an int, throws an exception if the parameter is out of range.

Parameters:

pData - >=0, <=MAX_UNSIGNED_BYTE_VALUE

Throws:

java.lang.RuntimeException - if pData is out of range

Method Detail

doubleValue

public double doubleValue()

Returns the current value of this object as a double float, after conversion.

Returns:

the current value of this object as a double float

floatValue

public float floatValue()

Returns a the current value of this object as a float, after conversion.

Returns:

the current value of this object as a float

intValue

public int intValue()

Returns the current value of this object as an int, after conversion.

Returns:

the current value of this object as an int

longValue

public long longValue()

Returns the current value of this object as a long, after conversion.

Returns:

the current value of this object as a long

serialize

public void serialize(java.io.DataOutputStream pOutputStream)

Writes out an UnsignedByte to an output stream.

Specified by:

serialize in interface SerializationInterface

Throws:

a - runtime Exception if an IOException occurs.

See Also:

SerializationInterface

deSerialize

public void deSerialize(java.io.DataInputStream pInputStream)

Reads an UnsignedByte in from DIS format.

Specified by:

deSerialize in interface SerializationInterface

Throws:

java.lang.RuntimeException - if an IOException occurs.

See Also:

SerializationInterface

toString

public java.lang.String toString()

Returns a String object representing this UnsignedByte value.

Returns:

a string representation of the value of this object in base 10.

debugTest

public void debugTest()

Of debugging interest only. You shouldn't have to use this method.

clone

public java.lang.Object clone()

Makes a deep copy of the current UnsignedByte object.

Returns:

the cloned object.

Throws:

java.lang.RuntimeException - if cloning fails