⚡️ Speed up function _excel2num by 16%

[codeflash-ai]

📄 16% (0.16x) speedup for _excel2num in pandas/io/excel/_util.py

⏱️ Runtime : 2.94 milliseconds → 2.53 milliseconds (best of 66 runs)

📝 Explanation and details

The optimized code achieves a 16% speedup by eliminating redundant operations inside the character processing loop and optimizing string validation.

Key optimizations:

1. Moved string preprocessing outside the loop: The original code called x.upper().strip() on every loop iteration. The optimized version calls this once and stores the result in s, eliminating repeated string method calls.

2. Precomputed ord('A') values: Instead of calling ord('A') and ord('Z') multiple times within the loop, these values are computed once and reused, reducing function call overhead.

3. Faster character validation: Replaced cp < ord("A") or cp > ord("Z") with not ('A' <= c <= 'Z'). This avoids calling ord() on the character for validation and uses Python's optimized string comparison operators, which are faster for single ASCII characters.

4. Reduced ord() calls per iteration: The original code called ord() three times per character (once for c, once for "A", once for "Z"). The optimized version calls ord() only once per character.

Performance impact by test case:

• Large inputs benefit most: Tests with long column names like "A" * 1000 show dramatic improvements (71-72% faster), indicating the optimizations scale well with input length
• Medium-length inputs: 3-letter columns show 7-16% improvements
• Single characters: Modest 2-5% improvements, as expected since loop overhead is minimal

Function usage context:
Based on function_references, _excel2num is called by _range2cols which processes comma-separated column ranges. This means _excel2num can be called multiple times per range specification (e.g., "A:Z,AA:AZ"), making the per-call optimization significant for Excel file processing workflows where column ranges are frequently parsed.

The optimization maintains identical functionality while providing meaningful performance gains, especially for longer column names and batch processing scenarios common in pandas Excel operations.

✅ Correctness verification report:

Test	Status
⚙️ Existing Unit Tests	🔘 None Found
🌀 Generated Regression Tests	✅ 3181 Passed
⏪ Replay Tests	🔘 None Found
🔎 Concolic Coverage Tests	🔘 None Found
📊 Tests Coverage	100.0%

🌀 Generated Regression Tests and Runtime

import pytest  # used for our unit tests
from pandas.io.excel._util import _excel2num

# unit tests


# ---------------------------
# 1. Basic Test Cases
# ---------------------------
@pytest.mark.parametrize(
    "col,expected",
    [
        ("A", 0),  # First column
        ("B", 1),  # Second column
        ("Z", 25),  # Last single-letter column
        ("AA", 26),  # First double-letter column
        ("AB", 27),  # Second double-letter column
        ("AZ", 51),  # Last double-letter column starting with 'A'
        ("BA", 52),  # First double-letter column starting with 'B'
        ("ZZ", 701),  # Last double-letter column
        ("AAA", 702),  # First triple-letter column
        ("AAB", 703),  # Second triple-letter column
        ("XFD", 16383),  # Last column in Excel (as of Excel 2016+)
    ],
)
def test_excel2num_basic(col, expected):
    # Test basic valid Excel column names
    codeflash_output = _excel2num(col)  # 24.5μs -> 24.5μs (0.143% slower)


# ---------------------------
# 2. Edge Test Cases
# ---------------------------


def test_excel2num_strip_and_case():
    # Test that spaces are stripped and case is ignored
    codeflash_output = _excel2num("  a ")  # 1.89μs -> 1.88μs (0.213% faster)
    codeflash_output = _excel2num("  Z ")  # 785ns -> 832ns (5.65% slower)
    codeflash_output = _excel2num(" aa ")  # 1.05μs -> 909ns (15.1% faster)
    codeflash_output = _excel2num("Ab")  # 695ns -> 704ns (1.28% slower)
    codeflash_output = _excel2num("zZ")  # 951ns -> 755ns (26.0% faster)
    codeflash_output = _excel2num("xFd")  # 955ns -> 850ns (12.4% faster)


@pytest.mark.parametrize(
    "col",
    [
        "",  # Empty string
        " ",  # Only whitespace
        "A1",  # Contains digit
        "1A",  # Starts with digit
        "A_B",  # Contains underscore
        "A!",  # Contains special character
        "A B",  # Contains space in the middle
        "a-",  # Contains hyphen
        "A.",  # Contains dot
        "A*",  # Contains asterisk
        "AA#",  # Contains hash
        "A\n",  # Contains newline
        "A\t",  # Contains tab
        "a🙂",  # Contains emoji
        "Aß",  # Contains non-ASCII letter
        "Aé",  # Contains accented letter
        "A你",  # Contains CJK character
    ],
)
def test_excel2num_invalid(col):
    # Test that invalid column names raise ValueError
    with pytest.raises(ValueError):
        _excel2num(col)  # 35.2μs -> 36.2μs (2.74% slower)


def test_excel2num_longest_single_letter():
    # Test the last single-letter column name
    codeflash_output = _excel2num("Z")  # 1.87μs -> 2.02μs (7.46% slower)


def test_excel2num_longest_double_letter():
    # Test the last double-letter column name
    codeflash_output = _excel2num("ZZ")  # 2.40μs -> 2.34μs (2.61% faster)


def test_excel2num_first_triple_letter():
    # Test the first triple-letter column name
    codeflash_output = _excel2num("AAA")  # 2.59μs -> 2.47μs (4.70% faster)


def test_excel2num_only_letters():
    # Test that a string with only letters is accepted
    codeflash_output = _excel2num("abc")  # 2.44μs -> 2.50μs (2.44% slower)


def test_excel2num_leading_and_trailing_whitespace():
    # Test with leading and trailing whitespace
    codeflash_output = _excel2num("   AA  ")  # 2.34μs -> 2.31μs (1.17% faster)


def test_excel2num_lowercase():
    # Lowercase input should work
    codeflash_output = _excel2num("abc")  # 2.48μs -> 2.44μs (1.80% faster)


def test_excel2num_mixed_case():
    # Mixed case input should work
    codeflash_output = _excel2num("aBc")  # 2.53μs -> 2.36μs (7.07% faster)


# ---------------------------
# 3. Large Scale Test Cases
# ---------------------------


def test_excel2num_large_column_names():
    # Test with a long column name (e.g., 10 letters, all 'A')
    # 'A' * n should be sum_{i=0}^{n-1} 26^i, minus 1
    n = 10
    col = "A" * n
    # The formula for the 0-based index for 'A'*n is: (26**n - 1)//25 - 1
    expected = (26**n - 1) // 25 - 1
    codeflash_output = _excel2num(col)  # 4.13μs -> 3.69μs (11.9% faster)


def test_excel2num_large_column_names_last():
    # Test with a long column name, all 'Z'
    # 'Z' * n: 26^n - 1
    n = 6
    col = "Z" * n
    # For 'Z'*n, index = sum_{i=0}^{n-1} 25*26^i = 26^n - 1
    expected = 26**n - 1
    codeflash_output = _excel2num(col)  # 2.99μs -> 2.56μs (16.8% faster)


@pytest.mark.parametrize("n", [1, 2, 3, 4, 5, 10, 20, 50, 100])
def test_excel2num_large_scale_AZ(n):
    # Test that 'A'*n returns the expected value for increasing n
    col = "A" * n
    expected = (26**n - 1) // 25 - 1
    codeflash_output = _excel2num(col)  # 51.4μs -> 41.1μs (25.0% faster)


@pytest.mark.parametrize("n", [1, 2, 3, 4, 5, 10, 20, 50, 100])
def test_excel2num_large_scale_ZZ(n):
    # Test that 'Z'*n returns the expected value for increasing n
    col = "Z" * n
    expected = 26**n - 1
    codeflash_output = _excel2num(col)  # 51.3μs -> 40.9μs (25.3% faster)


def test_excel2num_performance():
    # Test that the function completes in reasonable time for a 1000-letter column name
    import time

    col = "A" * 1000
    start = time.time()
    codeflash_output = _excel2num(col)
    result = codeflash_output  # 352μs -> 204μs (72.2% faster)
    end = time.time()


# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

import pytest  # used for our unit tests
from pandas.io.excel._util import _excel2num

# unit tests

# 1. BASIC TEST CASES


@pytest.mark.parametrize(
    "col,expected",
    [
        # Single letter columns
        ("A", 0),  # First column
        ("B", 1),
        ("Z", 25),  # Last single letter column
        # Two letter columns
        ("AA", 26),  # First two-letter column
        ("AB", 27),
        ("AZ", 51),
        ("BA", 52),
        ("ZZ", 701),  # Last two-letter column
        # Three letter columns
        ("AAA", 702),  # First three-letter column
        ("AAB", 703),
        ("AAZ", 727),
        ("ABA", 728),
        ("ZZZ", 18277),  # Last three-letter column
        # Lowercase input
        ("a", 0),
        ("zz", 701),
        ("aaa", 702),
        # Mixed case input
        ("Aa", 26),
        ("aA", 26),
        ("aZ", 51),
        ("Az", 51),
        ("zZ", 701),
        # Leading/trailing whitespace
        ("  A", 0),
        ("B  ", 1),
        ("  AB  ", 27),
    ],
)
def test_excel2num_basic(col, expected):
    """Test basic valid Excel column strings."""
    codeflash_output = _excel2num(col)  # 52.9μs -> 52.0μs (1.78% faster)


# 2. EDGE TEST CASES


@pytest.mark.parametrize(
    "col",
    [
        "",  # Empty string
        " ",  # Only whitespace
        "A ",  # Trailing whitespace is fine, but not just whitespace
        "1",  # Numeric
        "A1",  # Alphanumeric
        "1A",  # Alphanumeric
        "A!",  # Special character
        "A-",  # Special character
        "A_",  # Special character
        "A B",  # Space in between
        "A\tB",  # Tab in between
        "a\n",  # Newline at end
        "a\nb",  # Newline in middle
        "Ä",  # Non-ASCII letter
        "aä",  # Mixed ASCII/non-ASCII
        "A.",  # Dot
        "A/",  # Slash
        "A*",  # Star
        "A#",  # Hash
        "A$",  # Dollar
        "A%",  # Percent
        "A[",  # Out of range ASCII
        "A`",  # Out of range ASCII
        "A{",  # Out of range ASCII
        "A~",  # Out of range ASCII
    ],
)
def test_excel2num_invalid(col):
    """Test invalid Excel column strings raise ValueError."""
    with pytest.raises(ValueError):
        _excel2num(col)  # 56.1μs -> 57.2μs (1.98% slower)


def test_excel2num_strip_and_case():
    """Test that leading/trailing whitespace and case are handled."""
    codeflash_output = _excel2num("  a  ")  # 1.95μs -> 1.90μs (2.63% faster)
    codeflash_output = _excel2num("  ZzZ  ")  # 1.87μs -> 1.65μs (13.7% faster)


def test_excel2num_single_letter_bounds():
    """Test edge single-letter columns."""
    codeflash_output = _excel2num("A")  # 1.75μs -> 1.80μs (2.78% slower)
    codeflash_output = _excel2num("Z")  # 790ns -> 825ns (4.24% slower)


def test_excel2num_two_letter_bounds():
    """Test edge two-letter columns."""
    codeflash_output = _excel2num("AA")  # 2.06μs -> 2.02μs (2.03% faster)
    codeflash_output = _excel2num("AZ")  # 909ns -> 944ns (3.71% slower)
    codeflash_output = _excel2num("BA")  # 721ns -> 647ns (11.4% faster)
    codeflash_output = _excel2num("ZZ")  # 909ns -> 816ns (11.4% faster)


def test_excel2num_three_letter_bounds():
    """Test edge three-letter columns."""
    codeflash_output = _excel2num("AAA")  # 2.33μs -> 2.28μs (2.24% faster)
    codeflash_output = _excel2num("AAZ")  # 1.17μs -> 1.09μs (7.23% faster)
    codeflash_output = _excel2num("ABA")  # 797ns -> 876ns (9.02% slower)
    codeflash_output = _excel2num("ZZZ")  # 919ns -> 794ns (15.7% faster)


def test_excel2num_case_insensitivity():
    """Test that function is case-insensitive."""
    codeflash_output = _excel2num("a")  # 1.66μs -> 1.64μs (1.28% faster)
    codeflash_output = _excel2num("zZz")  # 1.54μs -> 1.32μs (16.7% faster)
    codeflash_output = _excel2num("AbC")  # 984ns -> 927ns (6.15% faster)


# 3. LARGE SCALE TEST CASES


def test_excel2num_large_scale_4_letters():
    """
    Test the function with the highest 4-letter Excel column name under 1000 steps.
    'ZZZZ' = 26^4 + 26^3 + 26^2 + 26^1 + 26^0 - 1 = 475253
    """
    codeflash_output = _excel2num("ZZZZ")  # 2.33μs -> 2.28μs (2.15% faster)


def test_excel2num_large_scale_first_1000():
    """
    Test the function for the first 1000 Excel columns.
    This ensures the function is correct and efficient for a large range.
    """

    # Build expected mapping for first 1000 columns
    def index_to_col(idx):
        """Convert 0-based index to Excel column name."""
        col = ""
        idx += 1
        while idx > 0:
            idx, rem = divmod(idx - 1, 26)
            col = chr(rem + ord("A")) + col
        return col

    for idx in range(1000):
        col = index_to_col(idx)
        # Test both upper and lower case
        codeflash_output = _excel2num(col)  # 543μs -> 534μs (1.71% faster)
        codeflash_output = _excel2num(col.lower())


def test_excel2num_large_scale_last_1000_of_4_letters():
    """
    Test the function for the last 1000 4-letter Excel columns.
    """
    start_idx = 475253 - 999

    def index_to_col(idx):
        """Convert 0-based index to Excel column name."""
        col = ""
        idx += 1
        while idx > 0:
            idx, rem = divmod(idx - 1, 26)
            col = chr(rem + ord("A")) + col
        return col

    for idx in range(start_idx, 475253 + 1):
        col = index_to_col(idx)
        codeflash_output = _excel2num(col)  # 794μs -> 726μs (9.41% faster)


def test_excel2num_performance_large_input():
    """
    Test that the function works efficiently for a 1000-character column name.
    The value will be huge, but we only check that it does not error and returns an int.
    """
    col = "A" * 1000
    codeflash_output = _excel2num(col)
    result = codeflash_output  # 351μs -> 205μs (71.4% faster)


def test_excel2num_leading_trailing_whitespace_large():
    """
    Test large column name with leading/trailing whitespace.
    """
    col = "   " + "Z" * 10 + "   "
    codeflash_output = _excel2num(col)  # 4.38μs -> 3.67μs (19.5% faster)


def test_excel2num_all_letters():
    """
    Test all single letters from A-Z and a-z.
    """
    for i in range(26):
        upper = chr(ord("A") + i)
        lower = chr(ord("a") + i)
        codeflash_output = _excel2num(upper)  # 11.7μs -> 12.0μs (2.73% slower)
        codeflash_output = _excel2num(lower)


# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

To edit these changes git checkout codeflash/optimize-_excel2num-mihdoy1n and push.