Clarify the specification of
ByteBuffer.alignmentOffset(), primarily with respect to the stated identities.
The identities given for the return value of
ByteBuffer.alignmentOffset() were not strictly accurate when the return value was greater than the supplied index.
Modify the specification so that it is accurate with respect to the identities.
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
alignmentOffset(index + (unitSize - value), unitSize) == 0