This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 00efc7500 Fix Conversion hex method Javadoc (#1845)
00efc7500 is described below
commit 00efc7500abe2d1a810cb7138995c2dfbe5fa9a2
Author: Gary Gregory <[email protected]>
AuthorDate: Fri Oct 30 06:38:20 2026 -0400
Fix Conversion hex method Javadoc (#1845)
Apply documentation corrections from PR #1845.
Clarify result-string replacement and appending, zero-length
conversions,
and exception conditions for byteToHex, intToHex, longToHex, and
shortToHex.
---
src/changes/changes.xml | 1 +
.../java/org/apache/commons/lang3/Conversion.java | 60 +++++++++++++---------
2 files changed, 37 insertions(+), 24 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 183b9c9ca..d166dc8d7 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -80,6 +80,7 @@ The <action> type attribute can be add,update,fix,remove.
<action type="fix" dev="ggregory" due-to="alhuda, Gary
Gregory">Keep DateUtils.ceiling and round inside a DST overlap hour
(#1842).</action>
<action type="fix" dev="ggregory" due-to="alhuda, Gary
Gregory">Keep RandomStringUtils.random rejection cap from failing valid ranges
(#1843).</action>
<action type="fix" dev="ggregory" due-to="Pendela
Phanindra Rao, Gary Gregory">[javadoc] Correct hexadecimal output examples in
Conversion (#1844).</action>
+ <action type="fix" dev="ggregory" due-to="Mohd Irshad,
Gary Gregory">Fix Conversion hex method Javadoc (#1845).</action>
<!-- ADD -->
<action issue="LANG-1790" type="add" dev="ggregory" due-to="Mert Kirpici,
Ivan Šarić, Gary Gregory">Add optional FIFO ordering for TimedSemaphore
blocking acquisitions.</action>
<!-- UPDATE -->
diff --git a/src/main/java/org/apache/commons/lang3/Conversion.java
b/src/main/java/org/apache/commons/lang3/Conversion.java
index 6391fedfc..1737e1627 100644
--- a/src/main/java/org/apache/commons/lang3/Conversion.java
+++ b/src/main/java/org/apache/commons/lang3/Conversion.java
@@ -514,16 +514,19 @@ public static boolean[] byteToBinary(final byte src,
final int srcPos, final boo
}
/**
- * Converts a byte into an array of char using the default (little-endian,
LSB0) byte and bit ordering.
+ * Converts a byte into a hexadecimal string using the default
(little-endian, LSB0) byte and bit ordering.
+ *
+ * <p>The result is initialized from {@code dstInit}. Converted digits
replace characters starting at {@code dstPos} and are appended as needed.
+ * If {@code nHexs} is zero, {@code dstInit} is returned without
validating the other arguments.</p>
*
* @param src The byte to convert.
* @param srcPos The position in {@code src}, in bits, from where to
start the conversion.
* @param dstInit The initial value for the result String.
- * @param dstPos The position in {@code dst} where to copy the result.
- * @param nHexs The number of chars to copy to {@code dst}, must be
smaller or equal to the width of the input (from srcPos to MSB).
- * @return {@code dst}.
- * @throws IllegalArgumentException Thrown if {@code (nHexs - 1) *
4 + srcPos >= 8}.
- * @throws StringIndexOutOfBoundsException Thrown if {@code
dst.init.length() < dstPos}.
+ * @param dstPos The position in the result string where to start writing
hexadecimal digits.
+ * @param nHexs The number of hexadecimal digits to write, must be
smaller or equal to the width of the input (from srcPos to MSB).
+ * @return A {@link String} with the converted hex digits based on {@code
dstInit}, or {@code dstInit} if {@code nHexs} is zero.
+ * @throws IllegalArgumentException Thrown if {@code nHexs != 0} and
{@code (nHexs - 1) * 4 + srcPos >= 8}.
+ * @throws StringIndexOutOfBoundsException Thrown if {@code nHexs > 0} and
{@code (dstPos < 0 || dstInit.length() < dstPos)}.
*/
public static String byteToHex(final byte src, final int srcPos, final
String dstInit, final int dstPos, final int nHexs) {
if (0 == nHexs) {
@@ -930,16 +933,19 @@ public static byte[] intToByteArray(final int src, final
int srcPos, final byte[
}
/**
- * Converts an int into an array of char using the default (little-endian,
LSB0) byte and bit ordering.
+ * Converts a int into a hexadecimal string using the default
(little-endian, LSB0) byte and bit ordering.
+ *
+ * <p>The result is initialized from {@code dstInit}. Converted digits
replace characters starting at {@code dstPos} and are appended as needed.
+ * If {@code nHexs} is zero, {@code dstInit} is returned without
validating the other arguments.</p>
*
* @param src The int to convert.
* @param srcPos The position in {@code src}, in bits, from where to
start the conversion.
* @param dstInit The initial value for the result String.
- * @param dstPos The position in {@code dst} where to copy the result.
- * @param nHexs The number of chars to copy to {@code dst}, must be
smaller or equal to the width of the input (from srcPos to MSB).
- * @return {@code dst}.
- * @throws IllegalArgumentException Thrown if {@code (nHexs - 1) *
4 + srcPos >= 32}.
- * @throws StringIndexOutOfBoundsException Thrown if {@code
dst.init.length() < dstPos}.
+ * @param dstPos The position in the result string where to start writing
hexadecimal digits.
+ * @param nHexs The number of hexadecimal digits to write, must be
smaller or equal to the width of the input (from srcPos to MSB).
+ * @return A {@link String} with the converted hex digits based on {@code
dstInit}, or {@code dstInit} if {@code nHexs} is zero.
+ * @throws IllegalArgumentException Thrown if {@code nHexs != 0} and
{@code (nHexs - 1) * 4 + srcPos >= 32}.
+ * @throws StringIndexOutOfBoundsException Thrown if {@code nHexs > 0} and
{@code (dstPos < 0 || dstInit.length() < dstPos)}.
*/
public static String intToHex(final int src, final int srcPos, final
String dstInit, final int dstPos, final int nHexs) {
if (0 == nHexs) {
@@ -1126,16 +1132,19 @@ public static byte[] longToByteArray(final long src,
final int srcPos, final byt
}
/**
- * Converts a long into an array of char using the default (little-endian,
LSB0) byte and bit ordering.
+ * Converts a long into a hexadecimal string using the default
(little-endian, LSB0) byte and bit ordering.
+ *
+ * <p>The result is initialized from {@code dstInit}. Converted digits
replace characters starting at {@code dstPos} and are appended as needed.
+ * If {@code nHexs} is zero, {@code dstInit} is returned without
validating the other arguments.</p>
*
* @param src The long to convert.
* @param srcPos The position in {@code src}, in bits, from where to
start the conversion.
* @param dstInit The initial value for the result String.
- * @param dstPos The position in {@code dst} where to copy the result.
- * @param nHexs The number of chars to copy to {@code dst}, must be
smaller or equal to the width of the input (from srcPos to MSB).
- * @return {@code dst}.
- * @throws IllegalArgumentException Thrown if {@code (nHexs - 1) *
4 + srcPos >= 64}.
- * @throws StringIndexOutOfBoundsException Thrown if {@code
dst.init.length() < dstPos}.
+ * @param dstPos The position in the result string where to start writing
hexadecimal digits.
+ * @param nHexs The number of hexadecimal digits to write, must be
smaller or equal to the width of the input (from srcPos to MSB).
+ * @return A {@link String} with the converted hex digits based on {@code
dstInit}, or {@code dstInit} if {@code nHexs} is zero.
+ * @throws IllegalArgumentException Thrown if {@code nHexs != 0} and
{@code (nHexs - 1) * 4 + srcPos >= 64}.
+ * @throws StringIndexOutOfBoundsException Thrown if {@code nHexs > 0} and
{@code (dstPos < 0 || dstInit.length() < dstPos)}.
*/
public static String longToHex(final long src, final int srcPos, final
String dstInit, final int dstPos, final int nHexs) {
if (0 == nHexs) {
@@ -1329,16 +1338,19 @@ public static byte[] shortToByteArray(final short src,
final int srcPos, final b
}
/**
- * Converts a short into an array of char using the default
(little-endian, LSB0) byte and bit ordering.
+ * Converts a short into a hexadecimal string using the default
(little-endian, LSB0) byte and bit ordering.
+ *
+ * <p>The result is initialized from {@code dstInit}. Converted digits
replace characters starting at {@code dstPos} and are appended as needed.
+ * If {@code nHexs} is zero, {@code dstInit} is returned without
validating the other arguments.</p>
*
* @param src The short to convert.
* @param srcPos The position in {@code src}, in bits, from where to
start the conversion.
* @param dstInit The initial value for the result String.
- * @param dstPos The position in {@code dst} where to copy the result.
- * @param nHexs The number of chars to copy to {@code dst}, must be
smaller or equal to the width of the input (from srcPos to MSB).
- * @return {@code dst}.
- * @throws IllegalArgumentException Thrown if {@code (nHexs - 1) *
4 + srcPos >= 16}.
- * @throws StringIndexOutOfBoundsException Thrown if {@code
dst.init.length() < dstPos}.
+ * @param dstPos The position in the result string where to start writing
hexadecimal digits.
+ * @param nHexs The number of hexadecimal digits to write, must be
smaller or equal to the width of the input (from srcPos to MSB).
+ * @return A {@link String} with the converted hex digits based on {@code
dstInit}, or {@code dstInit} if {@code nHexs} is zero.
+ * @throws IllegalArgumentException Thrown if {@code nHexs != 0} and
{@code (nHexs - 1) * 4 + srcPos >= 16}.
+ * @throws StringIndexOutOfBoundsException Thrown if {@code nHexs > 0} and
{@code (dstPos < 0 || dstInit.length() < dstPos)}.
*/
public static String shortToHex(final short src, final int srcPos, final
String dstInit, final int dstPos, final int nHexs) {
if (0 == nHexs) {
