Summary

Modify the specification of java.nio.ByteBuffer.alignmentOffset to be more clear about the meaning of the value it calculates.

Problem

java.nio.ByteBuffer.alignmentOffset is unclear that a returned value of zero means that the supplied index is aligned with the unit size and about the significance of a non-zero return value.

Solution

Revise the method specification to be clear about the meaning of the value it calculates.

Specification

See also the attached webrev.

Old Specification

Returns the memory address, pointing to the byte at the given index, modulus the given unit size.

A return value greater than zero indicates the address of the byte at the index is misaligned for the unit size, and the value's quantity indicates how much the index should be rounded up or down to locate a byte at an aligned address. Otherwise, a value of 0 indicates that the address of the byte at the index is aligned for the unit size.

New Specification

Returns the memory address, pointing to the byte at the given index, modulo the given unit size.

The return value is non-negative, with 0 indicating that the address of the byte at the index is aligned for the unit size, and a positive value that the address is misaligned for the unit size. If the address of the byte at the index is misaligned, the return value represents how much the index should be adjusted to locate a byte at an aligned address. Specifically, the index should either be decremented by the return value, or incremented by the unit size minus the return value. Therefore given

 int value = alignmentOffset(index, unitSize)

then the identities

 alignmentOffset(index - value, unitSize) == 0

and

 alignmentOffset(index + (unitSize - value), unitSize) == 0

must hold.