Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

LANG-731: Better Javadoc for BitField class 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1592457 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Duncan Jones 2014-05-05 07:05:33 +00:00
parent d44f573f7c
commit 75fbc009dd
2 changed files with 51 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/changes/changes.xml
View File

@ -22,6 +22,7 @@
<body>
<release version="3.4" date="tba" description="tba">
<action issue="LANG-731" type="update" dev="djones">Better Javadoc for BitField class</action>
<action issue="LANG-1004" type="update" dev="britter" due-to="Michael Osipov">DurationFormatUtils#formatDurationHMS implementation does not correspond to Javadoc and vice versa</action>
<action issue="LANG-1003" type="update" dev="britter">DurationFormatUtils are not able to handle negative durations/periods</action>
<action issue="LANG-1001" type="fix" dev="ggregory" due-to="Michael Osipov">ISO 8601 misspelled throughout the Javadocs</action>

51
src/main/java/org/apache/commons/lang3/BitField.java
View File

@ -17,7 +17,56 @@
package org.apache.commons.lang3;
/**
* <p>Operations on bit-mapped fields.</p>
* <p>Supports operations on bit-mapped fields. Instances of this class can be
* used to store a flag or data within an {@code int}, {@code short} or
* {@code byte}.</p>
*
* <p>Each {@code BitField} 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 0xFF} indicates the least-significant byte
* should be used to store the data.</p>
*
* <p>As an example, consider a car painting machine that accepts
* paint instructions as integers. Bit fields can be used to encode this:</p>
*
*<pre>
* // blue, green and red are 1 byte values (0-255) stored in the three least
* // significant bytes
* BitField blue = new BitField(0xFF);
* BitField green = new BitField(0xFF00);
* BitField red = new BitField(0xFF0000);
*
* // anyColor is a flag triggered if any color is used
* BitField anyColor = new BitField(0xFFFFFF);
*
* // isMetallic is a single bit flag
* BitField isMetallic = new BitField(0x1000000);
*</pre>
*
* <p>Using these {@code BitField} instances, a paint instruction can be
* encoded into an integer:</p>
*
*<pre>
* int paintInstruction = 0;
* paintInstruction = red.setValue(paintInstruction, 35);
* paintInstruction = green.setValue(paintInstruction, 100);
* paintInstruction = blue.setValue(paintInstruction, 255);
*</pre>
*
* <p>Flags and data can be retrieved from the integer:</p>
*
*<pre>
* // Prints true if red, green or blue is non-zero
* System.out.println(anyColor.isSet(paintInstruction)); // prints true
*
* // Prints value of red, green and blue
* System.out.println(red.getValue(paintInstruction)); // prints 35
* System.out.println(green.getValue(paintInstruction)); // prints 100
* System.out.println(blue.getValue(paintInstruction)); // prints 255
*
* // Prints true if isMetallic was set
* System.out.println(isMetallic.isSet(paintInstruction)); // prints false
*</pre>
*
* @since 2.0
* @version $Id$