Author: djones
Date: Mon May 5 07:05:33 2014
New Revision: 1592457
URL: http://svn.apache.org/r1592457
Log:
LANG-731: Better Javadoc for BitField class
Modified:
commons/proper/lang/trunk/src/changes/changes.xml
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/BitField.java
Modified: commons/proper/lang/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/changes/changes.xml?rev=1592457&r1=1592456&r2=1592457&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/changes/changes.xml [utf-8] (original)
+++ commons/proper/lang/trunk/src/changes/changes.xml [utf-8] Mon May 5
07:05:33 2014
@@ -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>
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/BitField.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/BitField.java?rev=1592457&r1=1592456&r2=1592457&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/BitField.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/BitField.java
Mon May 5 07:05:33 2014
@@ -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$
