#!/usr/bin/env python3
"""
概要:
    80文字のチャンクを繰り返し連結して文字列を構築するメソッドのベンチマークです。
詳細説明:
    s = s + chunk は意図的にCPythonのインプレース連結の高速化パスを避けており、
    イミュータブルな文字列の繰り返し連結がコスト高になる理由を示しています。
実行例:
    python strings_sum_benchmark.py
    python strings_sum_benchmark.py -n 1000000 -r 5
"""

from __future__ import annotations

import argparse
import statistics
import time
from io import StringIO
from typing import Callable


CHUNK = "#" * 80


def concat_plus(n: int) -> str:
    """
    概要:
        チャンクを + 演算子で繰り返し連結します。
    引数:
        :param n: 連結する回数
        :type n: int
    戻り値:
        :returns: 連結された文字列
        :rtype: str
    """
    result = ""
    for _ in range(n):
        result = result + CHUNK
    return result


def concat_iadd(n: int) -> str:
    """
    概要:
        チャンクを += 演算子で繰り返し連結します。
    引数:
        :param n: 連結する回数
        :type n: int
    戻り値:
        :returns: 連結された文字列
        :rtype: str
    """
    result = ""
    for _ in range(n):
        result += CHUNK
    return result


def list_join(n: int) -> str:
    """
    概要:
        リストにチャンクを追加し、最後に join で連結します。
    引数:
        :param n: 連結する回数
        :type n: int
    戻り値:
        :returns: 連結された文字列
        :rtype: str
    """
    parts: list[str] = []
    for _ in range(n):
        parts.append(CHUNK)
    return "".join(parts)


def string_io(n: int) -> str:
    """
    概要:
        StringIOを使ってチャンクを書き込み、文字列を取得します。
    引数:
        :param n: 連結する回数
        :type n: int
    戻り値:
        :returns: 連結された文字列
        :rtype: str
    """
    out = StringIO()
    for _ in range(n):
        out.write(CHUNK)
    return out.getvalue()


def benchmark(name: str, func: Callable[[int], str], n: int, repeat: int) -> None:
    """
    概要:
        指定された文字列連結関数のベンチマークを実行し、結果を出力します。
    引数:
        :param name: ベンチマーク名
        :type name: str
        :param func: 実行する関数
        :type func: Callable[[int], str]
        :param n: チャンクの連結回数
        :type n: int
        :param repeat: 実行する回数
        :type repeat: int
    戻り値:
        :returns: なし
        :rtype: None
    例外:
        :raises RuntimeError: 生成された文字列の長さが期待値と異なる場合
    """
    times: list[float] = []
    expected_length = len(CHUNK) * n

    for _ in range(repeat):
        start = time.perf_counter()
        result = func(n)
        times.append(time.perf_counter() - start)
        if len(result) != expected_length:
            raise RuntimeError(f"{name}: unexpected result length")

    print(
        f"{name:<18} {statistics.median(times):10.6f} s  "
        f"min={min(times):10.6f} s"
    )


def main() -> None:
    """
    概要:
        コマンドライン引数をパースし、各メソッドのベンチマークを実行します。
    戻り値:
        :returns: なし
        :rtype: None
    """
    parser = argparse.ArgumentParser(
        description="Benchmark repeated concatenation of '#' * 80."
    )
    parser.add_argument("-n", "--count", type=int, default=100_000,
                        help="number of chunks (default: 100000)")
    parser.add_argument("-r", "--repeat", type=int, default=3,
                        help="number of runs per method (default: 3)")
    args = parser.parse_args()

    if args.count < 0 or args.repeat < 1:
        parser.error("count must be non-negative and repeat must be at least 1")

    total_mib = len(CHUNK) * args.count / 1024**2
    print(f"chunk = '#' * {len(CHUNK)}, count = {args.count:,}, output = {total_mib:.2f} MiB")
    print(f"{'method':<18} {'median':>12}    minimum")
    print("-" * 56)

    for name, func in (
        ("s = s + chunk", concat_plus),
        ("s += chunk", concat_iadd),
        ("list.append + join", list_join),
        ("StringIO.write", string_io),
    ):
        benchmark(name, func, args.count, args.repeat)


if __name__ == "__main__":
    main()