elharo commented on code in PR #1095:
URL: https://github.com/apache/commons-lang/pull/1095#discussion_r1299405292
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -1847,4 +1862,211 @@ public static int compare(final short x, final short y)
{
public static int compare(final byte x, final byte y) {
return x - y;
}
-}
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
+ * {@link
org.apache.commons.lang3.math.NumberUtils#countSignificantFigures(String, char)}
+ *
+ * @param decimalNumber The decimal number string. Must be numeric digits
with optional decimal
Review Comment:
Please follow Oracle guidelines for formatting doc comments
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -1847,4 +1862,211 @@ public static int compare(final short x, final short y)
{
public static int compare(final byte x, final byte y) {
return x - y;
}
-}
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
+ * {@link
org.apache.commons.lang3.math.NumberUtils#countSignificantFigures(String, char)}
+ *
+ * @param decimalNumber The decimal number string. Must be numeric digits
with optional decimal
+ * and optional integer exponential suffix
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber) {
+ return countSignificantFigures(decimalNumber, CHAR_DECIMAL_PERIOD);
+ }
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
This method must
Review Comment:
Need a link to an authoritati=ve definition o0f signifcant figures
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -32,6 +33,20 @@
*/
public class NumberUtils {
+ /** Reusable char constant for zero. */
+ public static final char CHAR_ZERO = '0';
Review Comment:
These are all superfluous. Named constants are for number, not string and
char literals.
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -1847,4 +1862,211 @@ public static int compare(final short x, final short y)
{
public static int compare(final byte x, final byte y) {
return x - y;
}
-}
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
+ * {@link
org.apache.commons.lang3.math.NumberUtils#countSignificantFigures(String, char)}
+ *
+ * @param decimalNumber The decimal number string. Must be numeric digits
with optional decimal
+ * and optional integer exponential suffix
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber) {
+ return countSignificantFigures(decimalNumber, CHAR_DECIMAL_PERIOD);
+ }
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
This method must
+ * accept a string because significant figures can only be inferred from
the a user provided
Review Comment:
delete the
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -1847,4 +1862,211 @@ public static int compare(final short x, final short y)
{
public static int compare(final byte x, final byte y) {
return x - y;
}
-}
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
+ * {@link
org.apache.commons.lang3.math.NumberUtils#countSignificantFigures(String, char)}
+ *
+ * @param decimalNumber The decimal number string. Must be numeric digits
with optional decimal
+ * and optional integer exponential suffix
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber) {
+ return countSignificantFigures(decimalNumber, CHAR_DECIMAL_PERIOD);
+ }
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
This method must
+ * accept a string because significant figures can only be inferred from
the a user provided
+ * representation, and not from a binary numerical value. This logic is
useful/necessary when
+ * working with measured values where it is critical to retain the implied
uncertainty in the
+ * initial value for use in formatting after calculations. <br>
+ * The rules that are followed, outlined below, are widely accepted
standard conventions,
+ * discussed in many texts [1][2]. <b>Note:</b> Zero values are an
exceptional case that is
+ * unfortunately not often discussed or handled. This implementation aims
to retain the implied
+ * uncertainty and precision in a zero value such that further
mathematical operations can
+ * continue to report it. The goal of this logic is to allow zero values
to be reported with
+ * significant figure counts that match measurements in the same dataset.
i.e. if the values 2.1
+ * and 0.0 are measured on the same apparatus and reported in the same
dataset, we should be
+ * able to convey that they both have 2 significant figures. <br>
+ * <b>Note:</b> Rules 1-6 deal with the non-exponent portion of the
string, and by rule apply
+ * only to characters prior to the optional exponent character ('e'|'E').
Rule 7 covers the
+ * exponential portion. <br>
+ * 1) All nonzero digits are always significant. <br>
+ * 2) Zeros that appear between other nonzero digits are called "middle
zeros", and are always
+ * significant. <br>
+ * 3) Zeros that appear in front of all of the nonzero digits are called
"leading zeros", and
+ * are never significant. <br>
+ * 4) Zeros that appear after all nonzero digits are called "trailing
zeros". In a value with a
+ * decimal point they are significant. <br>
+ * 5) "Trailing zeros" in a value that does not contain a decimal are not
significant. <br>
+ * 6) Zero values are strings that only contain zeros and an optional
decimal. In these values,
+ * the first leading zero is considered to be significant, and all
trailing zeros are handled as
+ * if the first were nonzero (See Examples Below). <br>
+ * <table border="1">
+ * <tr>
+ * <th>String</th>
+ * <th>Count</th>
+ * <th>Reason</th>
+ * <th>Note</th>
+ * </tr>
+ * <tr>
+ * <td>0.00</td>
+ * <td>3</td>
+ * <td>The first whole zero is significant (Rule 6), and the two trailing
zeros are significant
+ * (Rule 4)</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>0e20</td>
+ * <td>1</td>
+ * <td>The first whole zero is significant (Rule 6) and the exponent is
not (Rule 7)</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>0000</td>
+ * <td>1</td>
+ * <td>The first whole zero is significant (Rule 6) and the last three are
not significant (Rule
+ * 5)</td>
+ * <td>This is an extreme case, documented here for clarity, uncommon in
practice</td>
+ * </tr>
+ * <tr>
+ * <td>00.0</td>
+ * <td>3</td>
+ * <td>First whole zero is significant (Rule 6) and the last two are also
significant (Rule
+ * <td></td> 4)</td>
+ * </tr>
+ * <tr>
+ * <td>0000.</td>
+ * <td>4</td>
+ * <td>First whole zero is significant (Rule 6) and the last three are
also significant (Rule
+ * <td></td> 4)</td>
+ * </tr>
+ * </table>
+ * 7) Integers present after an optional 'e' character are the "exponent".
These may only be
+ * decimal digit characters, and are never significant. <br>
+ * <br>
+ * [1] <a href=
+ *
"https://chem.libretexts.org/Bookshelves/Introductory_Chemistry/Map%3A_Fundamentals_of_General_Organic_and_Biological_Chemistry_(McMurry_et_al.)/01%3A_Matter_and_Measurements/1.08%3A_Measurement_and_Significant_Figures">Measurement
+ * and Significant Figures</a> [2]
+ * <a
href="https://chemed.chem.purdue.edu/genchem/topicreview/bp/ch1/sigfigs.html";>Significant
+ * Figures</a>
+ *
+ * @param decimalNumber The decimal number string. Must be optional sign +
numeric digits with optional decimal
+ * and optional e|E + sign + integer exponential suffix
+ * @param decimalSeparator the decimal separator character to use
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber, char
decimalSeparator) {
+ if (decimalNumber.length() == 0) {
+ throw new IllegalArgumentException("Decimal Number string was
empty");
+ }
+ if (CharUtils.isAsciiNumeric(decimalSeparator)) {
+ throw new IllegalArgumentException("Decimal Separator cannot be
numeric");
+ }
+ if (decimalSeparator == CHAR_EXPONENT_UPPER || decimalSeparator ==
CHAR_EXPONENT_LOWER) {
Review Comment:
inline the constants and I could read this without scrolling
##########
src/main/java/org/apache/commons/lang3/math/NumberUtils.java:
##########
@@ -1847,4 +1862,211 @@ public static int compare(final short x, final short y)
{
public static int compare(final byte x, final byte y) {
return x - y;
}
-}
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
+ * {@link
org.apache.commons.lang3.math.NumberUtils#countSignificantFigures(String, char)}
+ *
+ * @param decimalNumber The decimal number string. Must be numeric digits
with optional decimal
+ * and optional integer exponential suffix
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber) {
+ return countSignificantFigures(decimalNumber, CHAR_DECIMAL_PERIOD);
+ }
+
+ /**
+ * Counts the number of significant figures within a decimal value string.
This method must
+ * accept a string because significant figures can only be inferred from
the a user provided
+ * representation, and not from a binary numerical value. This logic is
useful/necessary when
+ * working with measured values where it is critical to retain the implied
uncertainty in the
+ * initial value for use in formatting after calculations. <br>
+ * The rules that are followed, outlined below, are widely accepted
standard conventions,
+ * discussed in many texts [1][2]. <b>Note:</b> Zero values are an
exceptional case that is
+ * unfortunately not often discussed or handled. This implementation aims
to retain the implied
+ * uncertainty and precision in a zero value such that further
mathematical operations can
+ * continue to report it. The goal of this logic is to allow zero values
to be reported with
+ * significant figure counts that match measurements in the same dataset.
i.e. if the values 2.1
+ * and 0.0 are measured on the same apparatus and reported in the same
dataset, we should be
+ * able to convey that they both have 2 significant figures. <br>
+ * <b>Note:</b> Rules 1-6 deal with the non-exponent portion of the
string, and by rule apply
+ * only to characters prior to the optional exponent character ('e'|'E').
Rule 7 covers the
+ * exponential portion. <br>
+ * 1) All nonzero digits are always significant. <br>
+ * 2) Zeros that appear between other nonzero digits are called "middle
zeros", and are always
+ * significant. <br>
+ * 3) Zeros that appear in front of all of the nonzero digits are called
"leading zeros", and
+ * are never significant. <br>
+ * 4) Zeros that appear after all nonzero digits are called "trailing
zeros". In a value with a
+ * decimal point they are significant. <br>
+ * 5) "Trailing zeros" in a value that does not contain a decimal are not
significant. <br>
+ * 6) Zero values are strings that only contain zeros and an optional
decimal. In these values,
+ * the first leading zero is considered to be significant, and all
trailing zeros are handled as
+ * if the first were nonzero (See Examples Below). <br>
+ * <table border="1">
+ * <tr>
+ * <th>String</th>
+ * <th>Count</th>
+ * <th>Reason</th>
+ * <th>Note</th>
+ * </tr>
+ * <tr>
+ * <td>0.00</td>
+ * <td>3</td>
+ * <td>The first whole zero is significant (Rule 6), and the two trailing
zeros are significant
+ * (Rule 4)</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>0e20</td>
+ * <td>1</td>
+ * <td>The first whole zero is significant (Rule 6) and the exponent is
not (Rule 7)</td>
+ * <td></td>
+ * </tr>
+ * <tr>
+ * <td>0000</td>
+ * <td>1</td>
+ * <td>The first whole zero is significant (Rule 6) and the last three are
not significant (Rule
+ * 5)</td>
+ * <td>This is an extreme case, documented here for clarity, uncommon in
practice</td>
+ * </tr>
+ * <tr>
+ * <td>00.0</td>
+ * <td>3</td>
+ * <td>First whole zero is significant (Rule 6) and the last two are also
significant (Rule
+ * <td></td> 4)</td>
+ * </tr>
+ * <tr>
+ * <td>0000.</td>
+ * <td>4</td>
+ * <td>First whole zero is significant (Rule 6) and the last three are
also significant (Rule
+ * <td></td> 4)</td>
+ * </tr>
+ * </table>
+ * 7) Integers present after an optional 'e' character are the "exponent".
These may only be
+ * decimal digit characters, and are never significant. <br>
+ * <br>
+ * [1] <a href=
+ *
"https://chem.libretexts.org/Bookshelves/Introductory_Chemistry/Map%3A_Fundamentals_of_General_Organic_and_Biological_Chemistry_(McMurry_et_al.)/01%3A_Matter_and_Measurements/1.08%3A_Measurement_and_Significant_Figures">Measurement
+ * and Significant Figures</a> [2]
+ * <a
href="https://chemed.chem.purdue.edu/genchem/topicreview/bp/ch1/sigfigs.html";>Significant
+ * Figures</a>
+ *
+ * @param decimalNumber The decimal number string. Must be optional sign +
numeric digits with optional decimal
+ * and optional e|E + sign + integer exponential suffix
+ * @param decimalSeparator the decimal separator character to use
+ * @return The number of significant figures in the string
+ */
+ public static int countSignificantFigures(String decimalNumber, char
decimalSeparator) {
+ if (decimalNumber.length() == 0) {
+ throw new IllegalArgumentException("Decimal Number string was
empty");
Review Comment:
needs a doc comment throws clause
--
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]
