Summary

Clarify the specification of ByteBuffer.alignmentOffset(), primarily with respect to the stated identities.

Problem

The identities given for the return value of ByteBuffer.alignmentOffset() were not strictly accurate when the return value was greater than the supplied index.

Solution

Modify the specification so that it is accurate with respect to the identities.

Specification

Modify the main paragraph of the specification of ByteBuffer.alignmentOffset() to be as follows (see attached webrev for normative content):

The return value is non-negative in the range of 0 (inclusive) up to unitSize (exclusive), with zero 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 if the latter is not greater than index, or be incremented by the unit size minus the return value. Therefore given

 int value = alignmentOffset(index, unitSize)

then the identities

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

and

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

must hold.