Finish up overflow handling and expand comments

src/obj_long.c

@@ -2497,7 +2497,23 @@ static size_t round_to(char * str, size_t len, size_t actual, size_t digits) {
 /**
  * @brief Convert a double to a KrkString.
  *
+ * We approach the problem of string conversion by converting the mantissa of the
+ * double to a bigint. We then treat that bigint as part of a fraction with a large
+ * power-of-ten denominator, and then apply the 2^n portion represented by the
+ * exponent of the double. For n<0, we will increase the magnitude of the fraction
+ * by multiplying the top and bottom repeatedly by 10^31, so that the multiplication
+ * (actually a right shift) by the 2^n part does not lose any bits. The result of
+ * all of this is an exact representation of the numerator of "x" in "x * 10^y = m * 2^n"
+ * with a denominator that remains a large power-of-ten. We can then perform decimal
+ * string conversion on this, round the decimal result as needed, and piece together
+ * the digits to form a whole, fractional, and exponential part.
  *
+ * @param a Double value to convert.
+ * @param digits Desired precision, meaning varies between e/f and g.
+ * @param formatter printf-style formatter character: eEfFgG or ' '
+ * @param plus Whether to force a sign character when value is positive.
+ * @param forcedigits Force trailing zeros, particularly in 'g' formatters.
+ * @returns A KrkValue representing the string.
  */
 KrkValue krk_double_to_string(double a, unsigned int digits, char formatter, int plus, int forcedigits) {
  union { double d; uint64_t u; } val = {.d = a};
@@ -2742,49 +2758,91 @@ KrkValue krk_double_to_string(double a, unsigned int digits, char formatter, int
  return krk_finishStringBuilder(&sb);
 }
 
+/**
+ * @brief Parse a string into a float.
+ *
+ * The approach we take here is to collect all of the digits left of the exponent
+ * (if present), convert them to a big int disregarding the radix point, then
+ * multiply or divide that by an appropriate power of ten based on the exponent
+ * and location of the radix point. The division step uses are @c long.__truediv__
+ * to get accurate conversions of fractions to floats.
+ *
+ * May raise exceptions if parsing fails, either here or in integer parsing.
+ *
+ * @param s String to parse.
+ * @param l Length of string to parse.
+ * @returns A Kuroko float value, or None on exceptin.
+ */
 KrkValue krk_parse_float(const char * s, size_t l) {
  size_t c = 0;
  int sign = 1;
- size_t ps = 0, pe = 0, ss = 0, se = 0, es = 0, ee = 0;
+ size_t ps = 0, pe = 0, ss = 0, se = 0, es = 0, ee = 0, e_ex = 0;
 
  union Float { double d; uint64_t i; };
 
+ /* Collect a leading sign. */
  if (s[c] == '-') {
  sign = -1;
  c++;
  ps = 1;
+ } else if (s[c] == '+') {
+ c++;
+ ps = 1;
  }
 
+ /* Case-insensitive check for stringy floats: nan, inf */
  if (c + 3 == l) {
  if (((s[c+0] | 0x20) == 'n') && ((s[c+1] | 0x20) == 'a') && ((s[c+2] | 0x20) == 'n')) {
- return FLOATING_VAL(((union Float){.i=0x7ff0000000000001ULL}).d);
+ return FLOATING_VAL(((union Float){.i=0x7ff0000000000001ULL}).d); /* nan */
  }
  if (((s[c+0] | 0x20) == 'i') && ((s[c+1] | 0x20) == 'n') && ((s[c+2] | 0x20) == 'f')) {
- return FLOATING_VAL(((union Float){.i=0x7ff0000000000000ULL}).d * sign);
+ return FLOATING_VAL(((union Float){.i=0x7ff0000000000000ULL}).d * sign); /* inf */
  }
  }
 
+ /* Collect digits or separators before a radix point. */
  while (c < l && ((s[c] >= '0' && s[c] <= '9') || s[c] == '_')) c++;
  pe = c;
 
+ /* If we are now at a radix point, collect it and then collect digits after the radix point. */
  if (c < l && s[c] == '.') {
  c++;
  ss = c;
  while (c < l && s[c] >= '0' && s[c] <= '9') c++;
  se = c;
  }
 
+ /* If we're still not at the end, we expect an exponent. */
  if (c < l && (s[c] == 'e' || s[c] == 'E')) {
  c++;
  es = c;
+ /* The exponent can have an optional sign character, which we'll
+ * include in the string if it is - and ignore if it is + */
  if (c < l && s[c] == '-') c++;
  else if (c < l && s[c] == '+') { c++; es++; }
+
+ /* Digits of exponent */
  while (c < l && s[c] >= '0' && s[c] <= '9') c++;
  ee = c;
  }
 
+ /* If we're not at the end here, we have invalid characters. */
  if (c != l) return krk_runtimeError(vm.exceptions->valueError, "invalid literal for float");
 
+ /* We can reduce the work we need to do later if we account for leading 0s in are
+ * number here. First strip all of the leading zeros from the whole part; if that
+ * results in no whole part, then continue stripping zeros from the fractional part,
+ * but be sure to record how many we're removing so we can account for the difference. */
+ while (ps != pe && s[ps] == '0') ps++;
+ if (ps == pe) {
+ while (ss != se && s[ss] == '0') {
+ e_ex++;
+ ss++;
+ }
+ }
+
+ /* Pack up all the digits from whole and fractional parts into a string so we can parse
+ * it with our faster decimal string parsing tools. */
  struct StringBuilder sb = {0};
  for (size_t i = ps; i < pe; ++i) {
  if (!sb.length && s[i] == '0') continue;
@@ -2796,36 +2854,61 @@ KrkValue krk_parse_float(const char * s, size_t l) {
  krk_pushStringBuilder(&sb,s[i]);
  }
 
+ /* If that results in an empty string (because we stripped all of the zeros, and it was
+ * only zeros), then replace it with "0" or the parser will be unhappy. */
  const char * m = sb.bytes;
  size_t m_len = sb.length;
  if (!sb.length) {
  m = "0";
  m_len = 1;
  }
 
+ /* Now parse it. We call this resulting value "m" because it's the numerator of the
+ * mantissa fraction of a decimal float, if that makes any sense. */
  KrkLong m_l;
  krk_long_parse_string(m,&m_l,10,m_len);
  krk_discardStringBuilder(&sb);
+
+ /* We didn't include the leading - in our string to parse, so we still want to apply
+ * the sign to the resulting big int. */
  krk_long_set_sign(&m_l,sign);
 
+ /* Handle an exponent component if one exists, or assume 0 otherwise. */
  const char * e = (es != ee) ? &s[es] : "0";
  size_t e_len = (es != ee) ? (ee-es) : 1;
 
+ /* And parse that into a big int */
  KrkLong e_l;
  krk_long_parse_string(e,&e_l,10,e_len);
 
+ /* We don't actually want to deal with big ints in the exponent, so assume
+ * they are going to overflow without even bothering to check to the part
+ * before them. Overflow to signed infinity or zero. */
  if (e_l.width > 1) {
  krk_long_clear_many(&m_l,&e_l,NULL);
- return FLOATING_VAL(((union Float){.i=0x7ff0000000000000ULL}).d * sign);
+ return FLOATING_VAL(((union Float){.i=0x7ff0000000000000ULL}).d * sign); /* inf */
  } else if (e_l.width < -1) {
  krk_long_clear_many(&m_l,&e_l,NULL);
- return FLOATING_VAL(0.0);
+ return FLOATING_VAL(0.0 * sign);
  }
 
+ /* Extract the big int exponent back into a normal integer */
  int64_t exp = krk_long_medium(&e_l);
- ssize_t digits = (se - ss) - exp;
+ ssize_t digits = (se - ss + e_ex) - exp;
+
+ /* Now do a more accurate check of overflowing exponents before continuing,
+ * to avoid very costly math to get the answer from truediv. */
+ if (exp + (ssize_t)(pe - ps) - (ssize_t)e_ex > 309) {
+ krk_long_clear_many(&m_l,&e_l,NULL);
+ return FLOATING_VAL(((union Float){.i=0x7ff0000000000000ULL}).d * sign); /* inf */
+ } else if (exp + (ssize_t)(pe - ps) - (ssize_t)e_ex < -324) {
+ krk_long_clear_many(&m_l,&e_l,NULL);
+ return FLOATING_VAL(0.0 * sign);
+ }
 
  if (digits > 0) {
+ /* If digits > 0, exponent is effectively negative. Calculate the result as:
+ * m / (10 ** digits) */
  KrkLong ten_digits, digits_el;
  krk_long_init_si(&ten_digits, 10);
  krk_long_init_si(&digits_el, digits);
@@ -2834,6 +2917,8 @@ KrkValue krk_parse_float(const char * s, size_t l) {
  krk_long_clear_many(&digits_el,&m_l,&e_l,&ten_digits, NULL);
  return v;
  } else if (digits < 0) {
+ /* If digits < 0, exponent is effectively positive. Calculate the result as:
+ * (m * (10 ** -digits)) / 1 */
  KrkLong ten_digits, digits_el, one;
  krk_long_init_si(&ten_digits, 10);
  krk_long_init_si(&digits_el, -digits);
@@ -2844,14 +2929,15 @@ KrkValue krk_parse_float(const char * s, size_t l) {
  krk_long_clear_many(&digits_el,&m_l,&e_l,&ten_digits,&one,NULL);
  return v;
  } else {
+ /* If digits == 0, exponent is 0, we have only a whole component in m, so
+ * we only need to do (m / 1) */
  KrkLong one;
  krk_long_init_si(&one, 1);
  KrkValue v = _krk_long_truediv(&m_l, &one);
  krk_long_clear_many(&m_l,&e_l,&one,NULL);
  return v;
  }
 }
-
 #endif
 
 /**