RFR: 8283892: Compress and expand bits [v4]

[Alan Bateman]

On Thu, 7 Apr 2022 18:23:50 GMT, Paul Sandoz <psandoz at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/Integer.java line 1781:
>> 
>>> 1779:      * All the upper remaining bits of the compressed value are set
>>> 1780:      * to zero.
>>> 1781:      *
>> 
>> Following Alan's comment, I suggest the following examples:
>> 
>> 
>>   compress(0x9ABCDEF, 0x0F0F0FF) == 0xACEF
>>   compress(x, 1<<n) == (x>>n & 1)
>>   compress(x, -1<<n) == x >>> n
>>   compress(m, m) == (m==-1||m==0)? m : (1<<bitCount(m))-1
>>   compress(x, m) == compress(x & m, m)
>>   compress(expand(x, m), m) == x & compress(m, m)
>>   (compress(x, m) >>> n) & 1 == /*the bit of x corresponding to the nth set bit in m*/
>> 
>> 
>> …In two places.  Similarly, examples for expand:
>> 
>> 
>>   expand(0x9ABCDEF, 0x0F0F0FF) == 0xC0D0EF
>>   expand(x, 1<<n) == (x&1) << n
>>   expand(x, -1<<n) == x << n
>>   expand(-1, m) == m
>>   expand(x, m) == expand(x, m) & m
>>   expand(compress(x, m), m) == x & m
>>   expand(1<<n, m) == /*the nth set bit in m, as a mask in place; cf. highest/lowestOneBit*/
>> 
>> 
>> (Please double check these examples!)
>
> Examples added in latest commit.

I see you've added a comment on each example too, I think this really helpers readers to see how they can be used.

The class description of both Integer and Long have an implementation note (they pre-date @implNote) referencing Hacker's Delight. We could potentially expand the list of methods mentioned but it's not strictly necessary are they are just examples.

-------------

PR: https://git.openjdk.java.net/jdk/pull/8115