You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by "elharo (via GitHub)" <gi...@apache.org> on 2023/08/20 16:52:57 UTC
[GitHub] [commons-lang] elharo commented on a diff in pull request #1095: NumberUtils countSignificantFigures method
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: issues-unsubscribe@commons.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org