ccs.utils
Class Unsigned

java.lang.Object
  ccs.utils.Unsigned

public class Unsigned
extends java.lang.Object

When working with integers which you wish were unsigned, it's extraordinarily easy to foul up the type conversions and, say, inadvertently fill the high-order half with 1 bits. This class provides a collection of common conversion operations.

It also provides methods for handling "packed" representations of longs, and a stand-alone readFully method which doesn't really fit, but is needed by the packed-representation methods and is generally useful.

The compose / decompose methods each come in a base version and an "LE" version; the base version uses big-endian byte order (ie. most significant byte first, as you'd natuarally write it down) whereas the LE version uses little-endian byte order (least significant byte first). Where you get a choice, we recommend big-endian order; it's more natural and in Java you can't optimise either way so there's little to choose between them otherwise.

Field Summary

static long

MAXPACKED The maximum long which can be represented in "packed" form.

Constructor Summary

Unsigned()

Method Summary

static boolean	areEqual(byte[] b1, byte[] b2) Test two bytestrings for equality - same length, same contents.
static long	combine(int left, int right) convert 2 logically-unsigned ints into a long.
static int	compose(byte[] buf, int off) Compose an int from its bytes in big-endian byte order.
static int	composeLE(byte[] buf, int off) Compose an int from its bytes in little-endian byte order.
static long	composeLong(byte[] buf, int off) Compose a long from its bytes in big-endian byte order.
static long	composeLongLE(byte[] buf, int off) Compose a long from its bytes in little-endian byte order.
static void	decompose(int x, byte[] buf, int off) Decompose an int into its respective bytes in big-endian byte order.
static void	decomposeLE(int x, byte[] buf, int off) Decompose an int into its respective bytes in little-endian byte order.
static void	decomposeLong(long x, byte[] buf, int off) Decompose a long into its respective bytes in big-endian byte order.
static void	decomposeLongLE(long x, byte[] buf, int off) Decompose a long into its respective bytes in little-endian byte order.
static int	getPackedLength(long n) The number of bytes required to write the supplied long in "packed" format.
static int	highOrder(long x) Returns the high-order (left) half of a long, as an int.
static int	lowOrder(long x) Returns the low-order (right) half of a long, as an int.
static void	readFully(java.io.InputStream is, byte[] wad) Read the specified array fully, a la DataInput.
static void	readFully(java.io.InputStream is, byte[] wad, int off, int len) Read the specified subarray fully, a la DataInput.
static long	readPacked(java.io.InputStream is, byte[] temp) Read a packed long from a stream.
static java.lang.String	toString(byte[] wad) Return a readable representation of a medium-length bytestring, such as a hash.
static java.lang.String	toString(byte[] wad, int off, int len) Return a readable representation of a medium-length bytestring, such as a hash.
static void	writePacked(java.io.OutputStream os, long n, byte[] temp) Write a long onto a stream, in a simple, variable-length, "packed" format whose length depends on the size of the quantity being written.

Methods inherited from class java.lang.Object

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

Field Detail

MAXPACKED

public static final long MAXPACKED

The maximum long which can be represented in "packed" form.

See Also:

Constant Field Values

Constructor Detail

Unsigned

public Unsigned()

Method Detail

combine

public static long combine(int left,
                           int right)

convert 2 logically-unsigned ints into a long.

Parameters:

left - The left-hand (high-order) half

right - The right-hand (low-order) half

highOrder

public static int highOrder(long x)

Returns the high-order (left) half of a long, as an int.

lowOrder

public static int lowOrder(long x)

Returns the low-order (right) half of a long, as an int. This is actually a trivial cast, and you miay want to do it yourself for efficiency. This method is here in case you prefer consistency and / or don't want to think about it.

decompose

public static void decompose(int x,
                             byte[] buf,
                             int off)

Decompose an int into its respective bytes in big-endian byte order. The high-order byte is buf[off].

Parameters:

x - The source int.

buf - The target buffer.

off - The offset into buf.

decomposeLE

public static void decomposeLE(int x,
                               byte[] buf,
                               int off)

Decompose an int into its respective bytes in little-endian byte order. The high-order byte is buf[off+3].

Parameters:

x - The source int.

buf - The target buffer.

off - The offset into buf.

decomposeLong

public static void decomposeLong(long x,
                                 byte[] buf,
                                 int off)

Decompose a long into its respective bytes in big-endian byte order. The high-order byte is buf[off].

Parameters:

x - The source long.

buf - The target buffer.

off - The offset into buf.

decomposeLongLE

public static void decomposeLongLE(long x,
                                   byte[] buf,
                                   int off)

Decompose a long into its respective bytes in little-endian byte order. The high-order byte is buf[off+7].

Parameters:

x - The source long.

buf - The target buffer.

off - The offset into buf.

compose

public static int compose(byte[] buf,
                          int off)

Compose an int from its bytes in big-endian byte order. The high-order byte is buf[off].

Parameters:

buf - The target buffer.

off - The offset into buf.

Returns:

The int.

composeLE

public static int composeLE(byte[] buf,
                            int off)

Compose an int from its bytes in little-endian byte order. The high-order byte is buf[off+3].

Parameters:

buf - The target buffer.

off - The offset into buf.

Returns:

The int.

composeLong

public static long composeLong(byte[] buf,
                               int off)

Compose a long from its bytes in big-endian byte order. The high-order byte is buf[off].

Parameters:

buf - The target buffer.

off - The offset into buf.

Returns:

The long.

composeLongLE

public static long composeLongLE(byte[] buf,
                                 int off)

Compose a long from its bytes in little-endian byte order. The high-order byte is buf[off+7].

Parameters:

buf - The target buffer.

off - The offset into buf.

Returns:

The long.

readFully

public static void readFully(java.io.InputStream is,
                             byte[] wad,
                             int off,
                             int len)
                      throws java.io.IOException

Read the specified subarray fully, a la DataInput. Useful when you don't want to create a DataInputStream just for this function.

Parameters:

is - The stream to read from.

wad - The array to read into.

off - Offset to start from

len - Number of bytes to read.

Throws:

java.io.EOFException - if the stream ends before the array has been read.

java.io.IOException

readFully

public static void readFully(java.io.InputStream is,
                             byte[] wad)
                      throws java.io.IOException

Read the specified array fully, a la DataInput. Useful when you don't want to create a DataInputStream just for this function.

Parameters:

is - The stream to read from.

wad - The array to read into.

Throws:

java.io.IOException

getPackedLength

public static int getPackedLength(long n)

The number of bytes required to write the supplied long in "packed" format.

Parameters:

n - The long in question; 0 <= n <= 0x3FFFFFFFFFFFFFFFL.

Returns:

The number of bytes required.

writePacked

public static void writePacked(java.io.OutputStream os,
                               long n,
                               byte[] temp)
                        throws java.io.IOException

Write a long onto a stream, in a simple, variable-length, "packed" format whose length depends on the size of the quantity being written. Shorter quantities - ints, shorts, even bytes - are stored with reasonable efficiency.

Parameters:

os - The stream to write to.

n - The long to write; 0 <= n <= 0x3FFFFFFFFFFFFFFFL.

temp - An array at least 8 bytes long to be used as scratch space.

Throws:

java.io.IOException - If os does.

readPacked

public static long readPacked(java.io.InputStream is,
                              byte[] temp)
                       throws java.io.IOException

Read a packed long from a stream.

Parameters:

is - The stream to read from.

temp - An array at least 8 bytes long to be used as scratch space.

Returns:

The long.

Throws:

java.io.EOFException - If the stream ends before the full value can be retreived.

java.io.IOException

toString

public static java.lang.String toString(byte[] wad)

Return a readable representation of a medium-length bytestring, such as a hash. Only accepts even-length inputs.

Parameters:

wad - The bytestring to convert

Returns:

A reasonably legible version.

toString

public static java.lang.String toString(byte[] wad,
                                        int off,
                                        int len)

Return a readable representation of a medium-length bytestring, such as a hash. Only accepts even-length inputs.

Parameters:

wad - The bytestring to convert

off - The offset in wad at which to start.

len - Number of bytes of wad to use.

Returns:

A reasonably legible version.

areEqual

public static boolean areEqual(byte[] b1,
                               byte[] b2)

Test two bytestrings for equality - same length, same contents.