garydgregory commented on code in PR #1552: URL: https://github.com/apache/commons-lang/pull/1552#discussion_r2659808486
########## src/test/java/org/apache/commons/lang3/LongBitFieldTest.java: ########## @@ -0,0 +1,97 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3; + +import static org.junit.jupiter.api.Assertions.*; + +import org.junit.jupiter.api.Test; + +public class LongBitFieldTest { + + @Test + public void testGetValueAndRawValue() { + LongBitField field = new LongBitField(0xFF00L); // bits 8-15 + long holder = 0x1234L; + + // raw value: bits & mask + assertEquals(0x1200L, field.getRawValue(holder)); + // shifted value: shifted right to LSB + assertEquals(0x12L, field.getValue(holder)); + } + + @Test + public void testSetValue() { + LongBitField field = new LongBitField(0xFF00L); // bits 8-15 + long holder = 0x1200L; + long result = field.setValue(holder, 0x34L); // replace bits 8-15 with 0x34 + assertEquals(0x3400L, result); + } + + @Test + public void testSet() { + LongBitField field = new LongBitField(0x1000L); // bit 12 + long holder = 0x0000L; + long result = field.set(holder); + assertEquals(0x1000L, result); + } + + @Test + public void testSetBoolean() { + LongBitField field = new LongBitField(0x1000L); // bit 12 + long holder = 0x0000L; + Review Comment: Remove empty lines. ########## src/main/java/org/apache/commons/lang3/LongBitField.java: ########## @@ -0,0 +1,145 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Supports operations on bit-mapped fields for 64-bit values. Instances of this class can be + * used to store a flag or data within a {@code long}. + * + * <p>Each {@link LongBitField} is constructed with a mask value, which indicates + * the bits that will be used to store and retrieve the data for that field. + * For instance, the mask {@code 0xFFL} indicates the least-significant byte + * should be used to store the data.</p> + * + * <p>Using these {@link LongBitField} instances, a long value can encode multiple fields:</p> + * + * <pre> + * LongBitField low8 = new LongBitField(0xFFL); + * LongBitField mid8 = new LongBitField(0xFF00L); + * LongBitField high8 = new LongBitField(0xFF0000L); + * + * long value = 0L; + * value = low8.setValue(value, 0x12); + * value = mid8.setValue(value, 0x34); + * value = high8.setValue(value, 0x56); + * + * System.out.println(low8.getValue(value)); // 0x12 + * System.out.println(mid8.getValue(value)); // 0x34 + * System.out.println(high8.getValue(value)); // 0x56 + * </pre> + * + * @since 3.13 (example) Review Comment: This is wrong. ########## src/main/java/org/apache/commons/lang3/LongBitField.java: ########## @@ -0,0 +1,145 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Supports operations on bit-mapped fields for 64-bit values. Instances of this class can be + * used to store a flag or data within a {@code long}. + * + * <p>Each {@link LongBitField} is constructed with a mask value, which indicates + * the bits that will be used to store and retrieve the data for that field. + * For instance, the mask {@code 0xFFL} indicates the least-significant byte + * should be used to store the data.</p> + * + * <p>Using these {@link LongBitField} instances, a long value can encode multiple fields:</p> + * + * <pre> + * LongBitField low8 = new LongBitField(0xFFL); + * LongBitField mid8 = new LongBitField(0xFF00L); + * LongBitField high8 = new LongBitField(0xFF0000L); + * + * long value = 0L; + * value = low8.setValue(value, 0x12); + * value = mid8.setValue(value, 0x34); + * value = high8.setValue(value, 0x56); + * + * System.out.println(low8.getValue(value)); // 0x12 + * System.out.println(mid8.getValue(value)); // 0x34 + * System.out.println(high8.getValue(value)); // 0x56 + * </pre> + * + * @since 3.13 (example) + */ +public class LongBitField { + + private final long mask; + private final int shiftCount; + + /** + * Creates a LongBitField instance. + * + * @param mask the mask specifying which bits apply to this + * LongBitField. Bits that are set in this mask are the bits + * that this LongBitField operates on + */ + public LongBitField(final long mask) { + this.mask = mask; + this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask); + } + + /** + * Clears the bits. + * + * @param holder the long data containing the bits we're interested in + * @return the value of holder with the specified bits cleared (set to {@code 0}) + */ + public long clear(final long holder) { + return holder & ~mask; + } + + /** + * Obtains the value for the specified LongBitField, unshifted. + * + * @param holder the long data containing the bits + * @return the selected bits + */ + public long getRawValue(final long holder) { + return holder & mask; + } + + /** + * Obtains the value for the specified LongBitField, appropriately shifted right. + * + * @param holder the long data containing the bits + * @return the selected bits, shifted right appropriately + */ + public long getValue(final long holder) { + return getRawValue(holder) >> shiftCount; + } + + /** + * Tests whether all of the bits are set or not. + * + * @param holder the long data containing the bits + * @return {@code true} if all bits in the mask are set + */ + public boolean isAllSet(final long holder) { + return (holder & mask) == mask; + } + + /** + * Tests whether any bit in the field is set. + * + * @param holder the long data containing the bits + * @return {@code true} if any bit in the mask is set + */ + public boolean isSet(final long holder) { + return (holder & mask) != 0; + } + + /** + * Sets the bits. + * + * @param holder the long data containing the bits + * @return the value of holder with the specified bits set to {@code 1} + */ + public long set(final long holder) { + return holder | mask; + } + + /** + * Sets a boolean LongBitField. + * + * @param holder the long data containing the bits + * @param flag whether to set or clear the bits + * @return the value of holder with the specified bits set or cleared + */ + public long setBoolean(final long holder, final boolean flag) { + return flag ? set(holder) : clear(holder); + } + + /** + * Replaces the bits with new values. + * + * @param holder the long data containing the bits + * @param value the new value for the specified bits + * @return the value of holder with the bits from the value parameter replacing the old bits + */ + public long setValue(final long holder, final long value) { + return holder & ~mask | (value << shiftCount) & mask; + } +} Review Comment: The file must end in an empty line. ########## src/test/java/org/apache/commons/lang3/LongBitFieldTest.java: ########## @@ -0,0 +1,97 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3; + +import static org.junit.jupiter.api.Assertions.*; + +import org.junit.jupiter.api.Test; + +public class LongBitFieldTest { Review Comment: The class and test methods should not be public to follow JUnit 5 guidelines. ########## src/main/java/org/apache/commons/lang3/LongBitField.java: ########## @@ -0,0 +1,145 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Supports operations on bit-mapped fields for 64-bit values. Instances of this class can be + * used to store a flag or data within a {@code long}. + * + * <p>Each {@link LongBitField} is constructed with a mask value, which indicates + * the bits that will be used to store and retrieve the data for that field. + * For instance, the mask {@code 0xFFL} indicates the least-significant byte + * should be used to store the data.</p> + * + * <p>Using these {@link LongBitField} instances, a long value can encode multiple fields:</p> + * + * <pre> + * LongBitField low8 = new LongBitField(0xFFL); + * LongBitField mid8 = new LongBitField(0xFF00L); + * LongBitField high8 = new LongBitField(0xFF0000L); + * + * long value = 0L; + * value = low8.setValue(value, 0x12); + * value = mid8.setValue(value, 0x34); + * value = high8.setValue(value, 0x56); + * + * System.out.println(low8.getValue(value)); // 0x12 + * System.out.println(mid8.getValue(value)); // 0x34 + * System.out.println(high8.getValue(value)); // 0x56 + * </pre> + * + * @since 3.13 (example) + */ +public class LongBitField { + + private final long mask; + private final int shiftCount; + + /** + * Creates a LongBitField instance. + * + * @param mask the mask specifying which bits apply to this + * LongBitField. Bits that are set in this mask are the bits + * that this LongBitField operates on + */ + public LongBitField(final long mask) { + this.mask = mask; + this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask); + } + + /** + * Clears the bits. + * + * @param holder the long data containing the bits we're interested in + * @return the value of holder with the specified bits cleared (set to {@code 0}) + */ + public long clear(final long holder) { + return holder & ~mask; + } + + /** + * Obtains the value for the specified LongBitField, unshifted. + * + * @param holder the long data containing the bits + * @return the selected bits + */ + public long getRawValue(final long holder) { + return holder & mask; + } + + /** + * Obtains the value for the specified LongBitField, appropriately shifted right. + * + * @param holder the long data containing the bits + * @return the selected bits, shifted right appropriately + */ + public long getValue(final long holder) { + return getRawValue(holder) >> shiftCount; + } + + /** + * Tests whether all of the bits are set or not. + * + * @param holder the long data containing the bits + * @return {@code true} if all bits in the mask are set + */ + public boolean isAllSet(final long holder) { + return (holder & mask) == mask; + } + + /** + * Tests whether any bit in the field is set. + * + * @param holder the long data containing the bits + * @return {@code true} if any bit in the mask is set + */ + public boolean isSet(final long holder) { + return (holder & mask) != 0; + } + + /** + * Sets the bits. + * + * @param holder the long data containing the bits + * @return the value of holder with the specified bits set to {@code 1} + */ + public long set(final long holder) { + return holder | mask; + } + + /** + * Sets a boolean LongBitField. + * + * @param holder the long data containing the bits + * @param flag whether to set or clear the bits + * @return the value of holder with the specified bits set or cleared + */ + public long setBoolean(final long holder, final boolean flag) { + return flag ? set(holder) : clear(holder); + } + + /** + * Replaces the bits with new values. Review Comment: A setter "Sets..." ########## src/main/java/org/apache/commons/lang3/LongBitField.java: ########## @@ -0,0 +1,145 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Supports operations on bit-mapped fields for 64-bit values. Instances of this class can be + * used to store a flag or data within a {@code long}. + * + * <p>Each {@link LongBitField} is constructed with a mask value, which indicates + * the bits that will be used to store and retrieve the data for that field. + * For instance, the mask {@code 0xFFL} indicates the least-significant byte + * should be used to store the data.</p> + * + * <p>Using these {@link LongBitField} instances, a long value can encode multiple fields:</p> + * + * <pre> + * LongBitField low8 = new LongBitField(0xFFL); + * LongBitField mid8 = new LongBitField(0xFF00L); + * LongBitField high8 = new LongBitField(0xFF0000L); + * + * long value = 0L; + * value = low8.setValue(value, 0x12); + * value = mid8.setValue(value, 0x34); + * value = high8.setValue(value, 0x56); + * + * System.out.println(low8.getValue(value)); // 0x12 + * System.out.println(mid8.getValue(value)); // 0x34 + * System.out.println(high8.getValue(value)); // 0x56 + * </pre> + * + * @since 3.13 (example) + */ +public class LongBitField { + + private final long mask; + private final int shiftCount; + + /** + * Creates a LongBitField instance. + * + * @param mask the mask specifying which bits apply to this + * LongBitField. Bits that are set in this mask are the bits + * that this LongBitField operates on + */ + public LongBitField(final long mask) { + this.mask = mask; + this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask); + } + + /** + * Clears the bits. + * + * @param holder the long data containing the bits we're interested in + * @return the value of holder with the specified bits cleared (set to {@code 0}) + */ + public long clear(final long holder) { + return holder & ~mask; + } + + /** + * Obtains the value for the specified LongBitField, unshifted. Review Comment: A getter "Gets..." ########## src/main/java/org/apache/commons/lang3/LongBitField.java: ########## @@ -0,0 +1,145 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +/** + * Supports operations on bit-mapped fields for 64-bit values. Instances of this class can be + * used to store a flag or data within a {@code long}. + * + * <p>Each {@link LongBitField} is constructed with a mask value, which indicates + * the bits that will be used to store and retrieve the data for that field. + * For instance, the mask {@code 0xFFL} indicates the least-significant byte + * should be used to store the data.</p> + * + * <p>Using these {@link LongBitField} instances, a long value can encode multiple fields:</p> + * + * <pre> + * LongBitField low8 = new LongBitField(0xFFL); + * LongBitField mid8 = new LongBitField(0xFF00L); + * LongBitField high8 = new LongBitField(0xFF0000L); + * + * long value = 0L; + * value = low8.setValue(value, 0x12); + * value = mid8.setValue(value, 0x34); + * value = high8.setValue(value, 0x56); + * + * System.out.println(low8.getValue(value)); // 0x12 + * System.out.println(mid8.getValue(value)); // 0x34 + * System.out.println(high8.getValue(value)); // 0x56 + * </pre> + * + * @since 3.13 (example) + */ +public class LongBitField { + + private final long mask; + private final int shiftCount; + + /** + * Creates a LongBitField instance. + * + * @param mask the mask specifying which bits apply to this + * LongBitField. Bits that are set in this mask are the bits + * that this LongBitField operates on + */ + public LongBitField(final long mask) { + this.mask = mask; + this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask); + } + + /** + * Clears the bits. + * + * @param holder the long data containing the bits we're interested in + * @return the value of holder with the specified bits cleared (set to {@code 0}) + */ + public long clear(final long holder) { + return holder & ~mask; + } + + /** + * Obtains the value for the specified LongBitField, unshifted. + * + * @param holder the long data containing the bits + * @return the selected bits + */ + public long getRawValue(final long holder) { + return holder & mask; + } + + /** + * Obtains the value for the specified LongBitField, appropriately shifted right. + * + * @param holder the long data containing the bits + * @return the selected bits, shifted right appropriately + */ + public long getValue(final long holder) { + return getRawValue(holder) >> shiftCount; + } + + /** + * Tests whether all of the bits are set or not. + * + * @param holder the long data containing the bits + * @return {@code true} if all bits in the mask are set + */ + public boolean isAllSet(final long holder) { + return (holder & mask) == mask; + } + + /** + * Tests whether any bit in the field is set. + * + * @param holder the long data containing the bits Review Comment: Sentences should end in a period. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
