Digits function

[1000ms]

Closes: #9077

Changelog category (leave one):

• New Feature

Changelog entry:

Add digits(n, offset[, length]) function which returns the number in n which starts at index offset(1-indexed) and has length number of digits. If length is not provided, the function returns the number from offset till end.

Version info

• Merged into: 26.7.1.871 (included in 26.7 and later)

[CLAassistant]

All committers have signed the CLA.

[clickhouse-gh]

Workflow [PR], commit [4c55ed2]

Summary: ✅

• Performance Comparison: Performance dashboard

---

AI Review

Summary

This PR adds digits(n, offset[, length]) for integer inputs, factors out the shared digits10 helper, and adds focused stateless coverage for the nullable/default-argument and large-UInt64 edge cases raised in earlier review rounds. After reviewing the current code, tests, prior discussion, and the current CI report, I did not find any remaining correctness, compatibility, or metadata issues.

Final Verdict

Status: ✅ Approve

[1000ms]

@thevar1able @yariks5s Anything else required for this? Thanks!

[yariks5s]

If you want to do it in a separate logic, and not involve already existing functions logic:

Toggle me

We can simplify the code a bit by replacing the curent nested logic for extractDigits with a helper like this:

  struct DigitRange
  {
      Int64 first; // 1-based
      Int64 count;
  };

  std::optional<DigitRange> getDigitRange(Int64 total_digits, Int64 offset, Int64 length, bool has_length)
  {
      if (offset == 0)
          throw Exception(ErrorCodes::ZERO_ARRAY_OR_TUPLE_INDEX, "Indices in number are 1-based");

      Int64 first = offset > 0 ? offset : total_digits + offset + 1;
      if (first > total_digits)
          return std::nullopt;

      if (!has_length)
      {
          first = std::max<Int64>(first, 1);
          return DigitRange{first, total_digits - first + 1};
      }

      if (length == 0)
          return std::nullopt;

      if (length < 0)
      {
          Int64 last = total_digits + length;
          if (last < 1)
              return std::nullopt;

          first = std::max<Int64>(first, 1);
          if (last < first)
              return std::nullopt;

          return DigitRange{first, last - first + 1};
      }

      if (first <= 0)
      {
          Int64 skipped = 1 - first;
          if (length <= skipped)
              return std::nullopt;

          length -= skipped;
          first = 1;
      }

      return DigitRange{first, std::min<Int64>(length, total_digits - first + 1)};
  }

Then extractDigits becomes much easier to audit:

  UInt64 extractDigits(UInt64 num, Int64 offset, Int64 length, bool has_length)
  {
      const Int64 total_digits = common::digits10(num);
      const auto range = getDigitRange(total_digits, offset, length, has_length);
      if (!range)
          return 0;

      const Int64 suffix = total_digits - range->first - range->count + 1;
      const UInt64 shifted = num / intExp10(static_cast<int>(suffix));
      return range->count >= 20 ? shifted : shifted % intExp10(static_cast<int>(range->count));
  }

I’d also simplify around the edges:

• Keep custom nullable handling. It is justified because offset = 0 throws, so default nullable execution is unsafe here
• Use wrapInNullable(result, null_map) instead of directly constructing ColumnNullable
• Replace getMaxSignedValFromUnsigned with a clearer getClampedInt64(const IColumn &, size_t)
• Use getNullPresense(arguments).has_nullable instead of the local anyArgumentNullable

---

but I think that reusing the aleady existing substring function can be good enough

[1000ms]

@yariks5s Addressed in latest commit, thanks!

[yariks5s]

Looks good, thank you. One nit: probably worth validating the data before the division rather than crashing

[clickhouse-gh]

LLVM Coverage Report

Metric	Baseline	Current	Δ
Lines	49.30%	85.80%	+36.50%
Functions	63.90%	92.70%	+28.80%
Branches	38.10%	78.00%	+39.90%

Changed lines: Changed C/C++ lines covered: 169/175 (96.57%) · Uncovered code

Full report · Diff report

[1000ms]

@yariks5s Unrelated tests are failing. Any input? Thanks!

[thevar1able]

Thank you for contributing!

[rschu1ze]

@groeneai Make a docs PR which cross-links the in-source docs of this function and the in-source docs-of SQL function substring.

[groeneai]

Acknowledged. I'll open a docs PR adding reciprocal related_functions cross-links between the in-source docs of digits and substring, and post the link here.

[groeneai]

Opened #111149 — reciprocal "See also" cross-links between the in-source docs of digits and substring.

Note: FunctionDocumentation has no related_functions field (that field lives on the separate Documentation struct used by engines/data-types), so I used the inline "See also" link convention already used by scalar functions (e.g. initialQueryID -> other-functions#queryID, tokens -> string-functions#sparseGrams).