cellproof 0.2.0__py3-none-any.whl

cellproof/fn/lookup.py

@@ -0,0 +1,302 @@
+"""VLOOKUP, HLOOKUP, MATCH, INDEX, XLOOKUP, CHOOSE.
+
+The value found is read from the cells table. Its type comes from the cells the range holds: one type ->
+that type; mixed, or text with empty cells -> 'any' (known when the SQL runs). An empty cell found reads
+as 0, like Excel. Exact matching of text ignores case and (except XLOOKUP's default) honours wildcards.
+
+Every search is an aggregate (arg_min/arg_max by position) over a table that does not depend on the formula's row;
+only the WHERE does. DuckDB plans such a subquery as one join for a whole region, where ORDER BY ... LIMIT 1 or a
+LEFT JOIN on the row's values cannot be planned at all.
+"""
+from __future__ import annotations
+
+from cellproof.expr import CELLS, NO_ERR, Expr, any_of, errs, lit_str, num, unify_all, where_area
+from cellproof.fn.criteria import like_pattern
+from cellproof.functions import arity, register
+from cellproof.model import Unsupported
+from cellproof.parser import Bool, Num, RefNode, Str, Unary
+from cellproof.refs import Area, resolve
+
+
+def _area(c, node, sheet: str, fname: str) -> tuple[Area, object]:
+    if not isinstance(node, RefNode):
+        raise Unsupported(f"{fname} needs a cell range")
+    area = resolve(node.text, sheet, c.book)
+    return area, c.ready(area)
+
+
+def _type_of(c, area: Area, keys) -> str:
+    kinds = set(keys.kinds) - {"e"}  # an error found is returned as that error, whatever the type
+    full = len(keys) == (area.r2 - area.r1 + 1) * (area.c2 - area.c1 + 1)
+    if kinds <= {"n"}:
+        return "num"  # an empty cell found reads as 0
+    if full and kinds == {"s"}:
+        return "txt"
+    if full and kinds == {"b"}:
+        return "bool"
+    return "any"
+
+
+def _read(pick, typ: str, err: str, r: str = "k.r_") -> Expr:
+    """The cell found. pick(x, default) is x of that cell, default when the cell is empty, NULL when nothing is
+    found; r prefixes the cell's columns."""
+    if typ == "num":
+        return Expr(pick(f"{r}num", "0"), "num", err)
+    if typ == "txt":
+        return Expr(pick(f"{r}txt", "''"), "txt", err)
+    if typ == "bool":
+        return Expr(pick(f"{r}num <> 0", "FALSE"), "bool", err)
+    return any_of(pick(f"{r}kind", "'n'"), pick(f"{r}num", "0"), pick(f"{r}txt", "''"), err)
+
+
+def _found_error(pick, missing: str) -> str:
+    """'missing' when nothing is found, the cell's own error when it holds one, else NULL."""
+    found = pick("CASE WHEN k.r_kind = 'e' THEN k.r_txt END", "''")
+    return f"(CASE WHEN {found} IS NULL THEN '{missing}' WHEN {found} = '' THEN NULL ELSE {found} END)"
+
+
+def _static_text(node) -> bool:
+    return isinstance(node, Str) and not any(ch in node.value for ch in "*?~")
+
+
+def _exact(k: str, x: Expr, wild: bool) -> str:
+    """SQL true when cell `k` equals the lookup value x (text ignores case; wildcards when `wild`)."""
+    text = f"lower(COALESCE({k}.txt, ''))"
+    t = (f"{text} LIKE {like_pattern(x.txt if x.type == 'any' else x.sql)} ESCAPE '\\'" if wild
+         else f"{text} = lower({x.txt if x.type == 'any' else x.sql})")
+    if x.type == "num":
+        return f"({k}.kind = 'n' AND {k}.num = {x.sql})"
+    if x.type == "txt":
+        return f"({k}.kind = 's' AND {t})"
+    if x.type == "bool":
+        return f"({k}.kind = 'b' AND {k}.num = CAST({x.sql} AS DOUBLE))"
+    if x.type == "any":
+        return (f"(CASE {x.kind} WHEN 'n' THEN {k}.kind = 'n' AND {k}.num = {x.sql} "
+                f"WHEN 's' THEN {k}.kind = 's' AND {t} ELSE {k}.kind = 'b' AND {k}.num = {x.sql} END)")
+    raise Unsupported(f"lookup of a value of type {x.type}")
+
+
+def _near(k: str, x: Expr, cmp: str) -> tuple[str, str]:
+    """(condition, sort key) for approximate match: values of x's type that are <= x (cmp '<=') or >= x."""
+    if x.type == "num":
+        return f"({k}.kind = 'n' AND {k}.num {cmp} {x.sql})", f"{k}.num"
+    if x.type == "txt":
+        return f"({k}.kind = 's' AND lower({k}.txt) {cmp} lower({x.sql}))", f"lower({k}.txt)"
+    raise Unsupported("approximate match on this kind of value not supported yet")
+
+
+def _require_sorted(c, line: Area, descending: bool, fname: str) -> None:
+    """Excel's approximate match is a binary search. On data that is not in order its answer depends on the search
+    path (real Excel: MATCH(150, {0,100,500}, -1) is #N/A although 500 >= 150), so cellproof refuses to guess.
+    The order is judged from the saved values, which the verifier then holds the computed values to."""
+    seen = []
+    for key in line.cells():
+        cell = c.book.cells.get(key)
+        if cell is None or cell.kind == "blank":
+            continue
+        if cell.kind == "e":
+            raise Unsupported(f"{fname} approximate match over a range holding an error")
+        seen.append((cell.kind, cell.value.lower() if isinstance(cell.value, str) else cell.value))
+    if len({kind for kind, _ in seen}) > 1:
+        raise Unsupported(f"{fname} approximate match over a range of mixed types")
+    values = [v for _, v in seen]
+    if not all(a >= b if descending else a <= b for a, b in zip(values, values[1:])):
+        raise Unsupported(f"{fname} approximate match needs {'descending' if descending else 'ascending'} sorted data: "
+                          "on unsorted data Excel's answer depends on its binary search")
+
+
+class Search:
+    """The cell `k` of the 1-D range `line` that a lookup finds. With `back` = (sheet SQL, join condition on k and r)
+    also the cell r it returns, read as k.r_kind, k.r_num, k.r_txt (NULL when r is empty)."""
+
+    def __init__(self, x: Expr, line: Area, mode: str, wild: bool, last: bool | None = None, back=None):
+        self.pos = "k.row_num" if line.c1 == line.c2 else "k.col_num"
+        table = f"{CELLS} k"
+        if back:
+            table = (f"(SELECT k.*, r.kind AS r_kind, r.num AS r_num, r.txt AS r_txt FROM {CELLS} k "
+                     f"LEFT JOIN {CELLS} r ON r.sheet = {back[0]} AND {back[1]} WHERE {where_area(line, 'k')}) k")
+        if mode == "exact":  # the first match, the last when `last`
+            cond, self.agg, self.key = _exact("k", x, wild), "arg_max" if last else "arg_min", self.pos
+        elif mode == "le":  # largest value <= x; the last of equal ones, as Excel's search on sorted data
+            cond, key = _near("k", x, "<=")
+            self.agg, self.key = "arg_max", f"({key}, {'-' if last is False else ''}{self.pos})"
+        else:  # "ge": smallest value >= x, the first of equal ones
+            cond, key = _near("k", x, ">=")
+            self.agg, self.key = "arg_min", f"({key}, {'-' if last else ''}{self.pos})"
+        self.src = f"FROM {table} WHERE {where_area(line, 'k')} AND {cond}"
+
+    def pick(self, value: str, default: str | None = None) -> str:
+        if default is not None:  # arg_min skips a NULL value: the cell would look not found
+            value = f"COALESCE({value}, {default})"
+        return f"(SELECT {self.agg}({value}, {self.key}) {self.src})"
+
+    def hit(self) -> str:
+        return f"(EXISTS (SELECT 1 {self.src}))"
+
+
+def int_literal(node) -> int | None:
+    """A whole number written in the formula (-1 parses as minus applied to 1), else None."""
+    if isinstance(node, Num):
+        return int(node.value)
+    if isinstance(node, Unary) and isinstance(node.operand, Num):
+        return -int(node.operand.value)
+    return None
+
+
+def _exact_flag(node) -> bool:
+    """VLOOKUP/HLOOKUP 4th argument: FALSE or 0 -> exact; omitted, TRUE or 1 -> approximate."""
+    if node is None:
+        return True
+    if isinstance(node, Bool):
+        return not node.value
+    if isinstance(node, Num):
+        return node.value == 0
+    raise Unsupported("lookup match type must be TRUE/FALSE written in the formula")
+
+
+def _xlookup_x(c, args, sheet) -> Expr:
+    x = c.expr(args[0], sheet)
+    if x.type == "blank":
+        raise Unsupported("lookup of an empty cell not supported yet")
+    return x
+
+
+def _table_lookup(fname: str, by_row: bool):
+    def fn(c, args, sheet):
+        arity(fname, args, 3, 4)
+        exact = len(args) == 4 and _exact_flag(args[3])
+        if not isinstance(args[2], Num):
+            raise Unsupported(f"{fname} index must be a number written in the formula")
+        table, _ = _area(c, args[1], sheet, fname)
+        offset = int(args[2].value) - 1
+        if by_row:
+            line = Area(table.sheet, table.r1, table.c1, table.r2, table.c1)
+            target = Area(table.sheet, table.r1, table.c1 + offset, table.r2, table.c1 + offset)
+            ok = table.c1 <= target.c1 <= table.c2
+            hit = f"r.row_num = k.row_num AND r.col_num = {target.c1}"
+        else:
+            line = Area(table.sheet, table.r1, table.c1, table.r1, table.c2)
+            target = Area(table.sheet, table.r1 + offset, table.c1, table.r1 + offset, table.c2)
+            ok = table.r1 <= target.r1 <= table.r2
+            hit = f"r.col_num = k.col_num AND r.row_num = {target.r1}"
+        if not ok:
+            raise Unsupported(f"{fname} {'column' if by_row else 'row'} index outside the table")
+        x = _xlookup_x(c, args, sheet)
+        if not exact:
+            _require_sorted(c, line, False, fname)
+        found = Search(x, line, "exact" if exact else "le", wild=exact, back=("k.sheet", hit))
+        keys = c.ready(target)
+        return _read(found.pick, _type_of(c, target, keys), errs(x.err, _found_error(found.pick, "#N/A")))
+    return fn
+
+
+register("VLOOKUP")(_table_lookup("VLOOKUP", by_row=True))
+register("HLOOKUP")(_table_lookup("HLOOKUP", by_row=False))
+
+
+def _line(c, node, sheet: str, fname: str) -> Area:
+    area, _ = _area(c, node, sheet, fname)
+    if area.r1 != area.r2 and area.c1 != area.c2:
+        raise Unsupported(f"{fname} needs a single row or column")
+    return area
+
+
+@register("MATCH")
+def match(c, args, sheet):
+    arity("MATCH", args, 2, 3)
+    kind = 1 if len(args) == 2 or args[2] is None else int_literal(args[2])
+    if kind not in (-1, 0, 1):
+        raise Unsupported("MATCH type must be -1, 0 or 1 written in the formula")
+    line = _line(c, args[1], sheet, "MATCH")
+    x = _xlookup_x(c, args, sheet)
+    if kind != 0:
+        _require_sorted(c, line, kind == -1, "MATCH")
+    found = Search(x, line, {0: "exact", 1: "le", -1: "ge"}[kind], wild=True)
+    first = line.r1 if line.c1 == line.c2 else line.c1
+    return Expr(found.pick(f"CAST({found.pos} - {first} + 1 AS DOUBLE)"), "num",
+                errs(x.err, f"(CASE WHEN NOT {found.hit()} THEN '#N/A' END)"))
+
+
+@register("XLOOKUP")
+def xlookup(c, args, sheet):
+    arity("XLOOKUP", args, 3, 6)
+    modes = []
+    for i, default in ((4, 0), (5, 1)):
+        node = args[i] if len(args) > i else None
+        mode = default if node is None else int_literal(node)
+        if mode is None:
+            raise Unsupported("XLOOKUP modes must be numbers written in the formula")
+        modes.append(mode)
+    match_mode, search_mode = modes
+    if match_mode not in (0, -1, 1, 2) or search_mode not in (1, -1):
+        raise Unsupported("XLOOKUP binary search modes not supported yet")
+    look = _line(c, args[1], sheet, "XLOOKUP")
+    back = _line(c, args[2], sheet, "XLOOKUP")
+    by_row = look.c1 == look.c2
+    if (by_row and (back.c1 != back.c2 or back.r2 - back.r1 != look.r2 - look.r1)) or \
+            (not by_row and (back.r1 != back.r2 or back.c2 - back.c1 != look.c2 - look.c1)):
+        raise Unsupported("XLOOKUP return range must be one row or column the size of the lookup range")
+    x = _xlookup_x(c, args, sheet)
+    mode = {0: "exact", 2: "exact", -1: "le", 1: "ge"}[match_mode]
+    hit = (f"r.row_num = k.row_num + {back.r1 - look.r1} AND r.col_num = {back.c1}" if by_row
+           else f"r.col_num = k.col_num + {back.c1 - look.c1} AND r.row_num = {back.r1}")
+    search = Search(x, look, mode, wild=match_mode == 2, last=search_mode == -1, back=(lit_str(back.sheet).sql, hit))
+    keys = c.ready(back)
+    found = _read(search.pick, _type_of(c, back, keys), errs(x.err, _found_error(search.pick, "#N/A")))
+    if len(args) < 4 or args[3] is None:
+        return found
+    missing = c.expr(args[3], sheet)
+    found, missing = unify_all([found, missing])
+    hit_sql = search.hit()
+    pick_err = f"(CASE WHEN {hit_sql} THEN {found.err} ELSE {missing.err} END)"
+
+    def case(a: str, b: str) -> str:
+        return f"(CASE WHEN {hit_sql} THEN {a} ELSE {b} END)"
+    return Expr(case(found.sql, missing.sql), found.type, errs(x.err, pick_err), case(found.txt, missing.txt),
+                case(found.kind, missing.kind))
+
+
+@register("INDEX")
+def index(c, args, sheet):
+    arity("INDEX", args, 2, 3)
+    area, keys = _area(c, args[0], sheet, "INDEX")
+    height, width = area.r2 - area.r1 + 1, area.c2 - area.c1 + 1
+    first = num(c.expr(args[1], sheet))
+    second = num(c.expr(args[2], sheet)) if len(args) == 3 and args[2] is not None else None
+    if second is None:
+        if height == 1:
+            row, col = Expr("CAST(1 AS DOUBLE)", "num"), first  # one row: the number picks the column
+        elif width == 1:
+            row, col = first, Expr("CAST(1 AS DOUBLE)", "num")
+        else:
+            raise Unsupported("INDEX of a block needs a row and a column")
+    else:
+        row, col = first, second
+    r = f"(CASE WHEN trunc({row.sql}) BETWEEN 1 AND {height} THEN CAST(trunc({row.sql}) AS BIGINT) END)"
+    k = f"(CASE WHEN trunc({col.sql}) BETWEEN 1 AND {width} THEN CAST(trunc({col.sql}) AS BIGINT) END)"
+    src = (f"FROM {CELLS} r WHERE r.sheet = {lit_str(area.sheet).sql} "
+           f"AND r.row_num = {area.r1} - 1 + {r} AND r.col_num = {area.c1} - 1 + {k}")
+
+    def pick(value: str, default: str) -> str:  # at most one cell matches; none when it is empty
+        return f"COALESCE((SELECT max({value}) {src}), {default})"
+    bounds = f"(CASE WHEN {r} IS NULL OR {k} IS NULL OR {r} < 1 OR {r} > {height} OR {k} < 1 OR {k} > {width} THEN '#REF!' END)"
+    found = f"(SELECT max(CASE WHEN r.kind = 'e' THEN r.txt END) {src})"
+    return _read(pick, _type_of(c, area, keys), errs(row.err, col.err, bounds, found), "r.")
+
+
+@register("CHOOSE")
+def choose(c, args, sheet):
+    if len(args) < 2:
+        raise Unsupported("CHOOSE needs an index and values")
+    i = num(c.expr(args[0], sheet))
+    values = unify_all([c.expr(a, sheet) for a in args[1:]])
+    n = f"TRY_CAST(trunc({i.sql}) AS BIGINT)"
+
+    def case(parts: list[str]) -> str:
+        if len(set(parts)) == 1:
+            return parts[0]
+        return "(CASE " + " ".join(f"WHEN {n} = {j} THEN {p}" for j, p in enumerate(parts, 1)) + " END)"
+    bad = f"(CASE WHEN {n} IS NULL OR {n} < 1 OR {n} > {len(values)} THEN '#VALUE!' END)"
+    err = errs(i.err, bad, case([v.err for v in values]) if any(v.err != NO_ERR for v in values) else NO_ERR)
+    return Expr(case([v.sql for v in values]), values[0].type, err, case([v.txt for v in values]),
+                case([v.kind for v in values]))

cellproof/fn/maths.py

@@ -0,0 +1,118 @@
+"""ABS, INT, SIGN, PI, SQRT, EXP, LN, LOG10, LOG, POWER, MOD, TRUNC, ROUNDUP, ROUNDDOWN, CEILING, FLOOR, MROUND.
+
+DuckDB throws on ln(0) or sqrt(-1), and one throw would stop the whole batch, so every function with a
+domain is written as CASE WHEN <ok> THEN f(x) END plus the Excel error for the rest (a CASE never runs the
+branch it skips, verified on DuckDB 1.5.6). Rounding to a digit first rounds to 15 significant digits, as
+Excel does, so ROUNDUP(0.1*3, 1) is 0.3, not 0.4.
+"""
+from __future__ import annotations
+
+from cellproof.expr import ZERO, Expr, errs, num
+from cellproof.functions import arity, register
+from cellproof.parser import Binary
+
+
+def _guarded(value: str, bad: str, code: str) -> tuple[str, str]:
+    return f"(CASE WHEN NOT ({bad}) THEN {value} END)", f"(CASE WHEN {bad} THEN '{code}' END)"
+
+
+def _one(name: str, value, bad=None, code: str = "#NUM!"):
+    def fn(c, args, sheet):
+        arity(name, args, 1, 1)
+        x = num(c.expr(args[0], sheet))
+        if bad is None:
+            return Expr(value(x.sql), "num", x.err)
+        sql, err = _guarded(value(x.sql), bad(x.sql), code)
+        return Expr(sql, "num", errs(x.err, err))
+    register(name)(fn)
+
+
+_one("ABS", lambda x: f"abs({x})")
+_one("INT", lambda x: f"floor({x})")
+_one("SIGN", lambda x: f"CAST(sign({x}) AS DOUBLE)")
+_one("SQRT", lambda x: f"sqrt({x})", lambda x: f"{x} < 0")
+_one("EXP", lambda x: f"exp({x})", lambda x: f"{x} > 709.782712893384")
+_one("LN", lambda x: f"ln({x})", lambda x: f"{x} <= 0")
+_one("LOG10", lambda x: f"log10({x})", lambda x: f"{x} <= 0")
+
+
+@register("PI")
+def pi(c, args, sheet):
+    arity("PI", args, 0, 0)
+    return Expr("pi()", "num")
+
+
+@register("LOG")
+def log(c, args, sheet):
+    arity("LOG", args, 1, 2)
+    x = num(c.expr(args[0], sheet))
+    base = num(c.expr(args[1], sheet)) if len(args) == 2 and args[1] is not None else Expr("CAST(10 AS DOUBLE)", "num")
+    bad = f"(CASE WHEN {x.sql} <= 0 OR {base.sql} <= 0 THEN '#NUM!' WHEN {base.sql} = 1 THEN '#DIV/0!' END)"
+    return Expr(f"(CASE WHEN {x.sql} > 0 AND {base.sql} > 0 AND {base.sql} <> 1 THEN ln({x.sql}) / ln({base.sql}) END)",
+                "num", errs(x.err, base.err, bad))
+
+
+@register("POWER")
+def power(c, args, sheet):
+    arity("POWER", args, 2, 2)
+    return c.binary(Binary("^", args[0], args[1]), sheet)
+
+
+def _two(c, args, sheet, name: str, default=None) -> tuple[Expr, Expr]:
+    arity(name, args, 1 if default is not None else 2, 2)
+    x = num(c.expr(args[0], sheet))
+    y = num(c.expr(args[1], sheet)) if len(args) == 2 and args[1] is not None else (default or ZERO)
+    return x, y
+
+
+def xl15(v: str) -> str:
+    """v rounded to 15 significant digits, the precision Excel works at."""
+    return f"(CASE WHEN {v} = 0 THEN 0 WHEN NOT isfinite({v}) THEN {v} ELSE round({v}, 14 - CAST(floor(log10(abs({v}))) AS INTEGER)) END)"
+
+
+@register("MOD")
+def mod(c, args, sheet):
+    x, y = _two(c, args, sheet, "MOD")
+    # Real Excel: MOD(1, 0.1) = 0.09999999999999995, the exact floating-point remainder, not x - y*floor(x/y).
+    # DuckDB's % is the C remainder (sign of the dividend); its fmod() function is not, so it is not used.
+    rem = f"({x.sql} % {y.sql})"
+    sql, err = _guarded(f"(CASE WHEN {rem} <> 0 AND ({rem} < 0) <> ({y.sql} < 0) THEN {rem} + {y.sql} ELSE {rem} END)",
+                        f"{y.sql} = 0", "#DIV/0!")
+    return Expr(sql, "num", errs(x.err, y.err, err))  # Excel: the result takes the divisor's sign
+
+
+def _digits(name: str, rnd: str):
+    def fn(c, args, sheet):
+        x, d = _two(c, args, sheet, name, default=ZERO if name == "TRUNC" else None)
+        p = f"power(10, trunc({d.sql}))"
+        # shortcut: scaling outside DOUBLE gives #NUM!, revisit with Excel boundary fixtures.
+        scaled = f"abs({x.sql}) * {p}"
+        ok = f"(isfinite({p}) AND {p} > 0 AND isfinite({scaled}))"
+        sql = f"(CASE WHEN {d.sql} > 308 THEN {x.sql} WHEN {ok} THEN sign({x.sql}) * {rnd}({xl15(scaled)}) / {p} END)"
+        bad = f"(CASE WHEN {d.sql} <= 308 AND NOT {ok} THEN '#NUM!' END)"
+        return Expr(sql, "num", errs(x.err, d.err, bad))
+    register(name)(fn)
+
+
+_digits("ROUNDUP", "ceil")
+_digits("ROUNDDOWN", "floor")
+_digits("TRUNC", "floor")
+
+
+def _multiple(name: str, rnd: str, zero_code: str | None):
+    def fn(c, args, sheet):
+        x, m = _two(c, args, sheet, name)
+        bad = f"({x.sql} > 0 AND {m.sql} < 0)" if name != "MROUND" else f"({x.sql} * {m.sql} < 0)"
+        if zero_code:
+            bad = f"({bad} OR {m.sql} = 0)"
+        value = f"(CASE WHEN {m.sql} = 0 THEN 0 ELSE {rnd}({xl15(f'{x.sql} / {m.sql}')}) * {m.sql} END)"
+        sql, _ = _guarded(value, bad, "#NUM!")
+        code = (f"(CASE WHEN {m.sql} = 0 THEN '{zero_code}' WHEN {bad} THEN '#NUM!' END)" if zero_code
+                else f"(CASE WHEN {bad} THEN '#NUM!' END)")
+        return Expr(sql, "num", errs(x.err, m.err, code))
+    register(name)(fn)
+
+
+_multiple("CEILING", "ceil", None)
+_multiple("FLOOR", "floor", "#DIV/0!")
+_multiple("MROUND", "round", None)

cellproof/fn/text.py

@@ -0,0 +1,257 @@
+"""CONCATENATE, CONCAT, TEXTJOIN, LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER, PROPER, SUBSTITUTE, REPLACE,
+FIND, SEARCH, REPT, VALUE, TEXT, EXACT, CHAR, CLEAN.
+
+Numbers become text the way Excel writes them (expr.num_text: 15 significant digits). Positions are 1-based
+and counted in characters, as in Excel. TEXT supports the number formats in NUMBER_FORMATS; dates.py adds
+date formats to FORMATS.
+"""
+from __future__ import annotations
+
+from cellproof.expr import BLANK, CELLS, NO_ERR, Expr, errs, num, num_text, txt, where_area
+from cellproof.functions import arity, register
+from cellproof.model import Unsupported
+from cellproof.parser import Bool, RefNode, Str
+from cellproof.refs import resolve
+
+
+def _t(c, node, sheet: str) -> Expr:
+    return txt(c.expr(node, sheet) if node is not None else BLANK)
+
+
+def _n(c, node, sheet: str) -> Expr:
+    return num(c.expr(node, sheet) if node is not None else BLANK)
+
+
+def _bad(cond: str) -> str:
+    return f"(CASE WHEN {cond} THEN '#VALUE!' END)"
+
+
+CELL_TEXT = ("(CASE kind WHEN 's' THEN COALESCE(txt, '') WHEN 'b' THEN (CASE WHEN num <> 0 THEN 'TRUE' ELSE 'FALSE' END) "
+             f"ELSE {num_text('num')} END)")
+
+
+def _range_texts(c, node, sheet: str) -> tuple[str, str, int]:
+    """(SQL list of the range's cell texts in row order, first error, number of empty cells in the range)."""
+    area = resolve(node.text, sheet, c.book)
+    keys = c.ready(area)
+    where = f"FROM {CELLS} WHERE {where_area(area)}"
+    err = NO_ERR
+    if keys.may_err:
+        err = f"(SELECT txt {where} AND kind = 'e' ORDER BY row_num, col_num LIMIT 1)"
+    blanks = (area.r2 - area.r1 + 1) * (area.c2 - area.c1 + 1) - len(keys)
+    return (f"(SELECT COALESCE(list({CELL_TEXT} ORDER BY row_num, col_num), []) {where} AND kind <> 'e')", err,
+            blanks)
+
+
+@register("CONCATENATE")
+def concatenate(c, args, sheet):
+    if not args:
+        raise Unsupported("CONCATENATE needs arguments")
+    parts = [_t(c, a, sheet) for a in args]
+    return Expr("(" + " || ".join(p.sql for p in parts) + ")", "txt", errs(*(p.err for p in parts)))
+
+
+def _pieces(c, args, sheet: str, keep_blanks: bool) -> tuple[list[str], list[str]]:
+    lists, err = [], []
+    for a in args:
+        if isinstance(a, RefNode) and not resolve(a.text, sheet, c.book).is_single:
+            items, e, blanks = _range_texts(c, a, sheet)
+            if keep_blanks and blanks:
+                raise Unsupported("TEXTJOIN keeping the empty cells of a range not supported yet")
+            lists.append(items)
+            err.append(e)
+        else:
+            p = _t(c, a, sheet)
+            lists.append(f"[{p.sql}]")
+            err.append(p.err)
+    return lists, err
+
+
+@register("CONCAT")
+def concat(c, args, sheet):
+    if not args:
+        raise Unsupported("CONCAT needs arguments")
+    lists, err = _pieces(c, args, sheet, keep_blanks=False)
+    return Expr(f"array_to_string(list_concat({', '.join(lists)}), '')" if len(lists) > 1
+                else f"array_to_string({lists[0]}, '')", "txt", errs(*err))
+
+
+@register("TEXTJOIN")
+def textjoin(c, args, sheet):
+    if len(args) < 3 or not isinstance(args[1], Bool):
+        raise Unsupported("TEXTJOIN needs a delimiter, TRUE/FALSE written in the formula, and values")
+    delim = _t(c, args[0], sheet)
+    lists, err = _pieces(c, args[2:], sheet, keep_blanks=not args[1].value)
+    items = f"list_concat({', '.join(lists)})" if len(lists) > 1 else lists[0]
+    if args[1].value:
+        items = f"list_filter({items}, x -> x <> '')"
+    return Expr(f"array_to_string({items}, {delim.sql})", "txt", errs(delim.err, *err))
+
+
+def _count_arg(c, args, sheet: str, i: int) -> Expr:
+    if len(args) > i and args[i] is not None:
+        return _n(c, args[i], sheet)
+    return Expr("CAST(1 AS DOUBLE)", "num")
+
+
+def _side(name: str, fn: str):
+    def impl(c, args, sheet):
+        arity(name, args, 1, 2)
+        t, n = _t(c, args[0], sheet), _count_arg(c, args, sheet, 1)
+        return Expr(f"{fn}({t.sql}, CAST(trunc(least(greatest({n.sql}, 0), length({t.sql}))) AS BIGINT))", "txt",
+                    errs(t.err, n.err, _bad(f"{n.sql} < 0")))
+    register(name)(impl)
+
+
+_side("LEFT", "left")
+_side("RIGHT", "right")
+
+
+@register("MID")
+def mid(c, args, sheet):
+    arity("MID", args, 3, 3)
+    t, start, n = _t(c, args[0], sheet), _n(c, args[1], sheet), _n(c, args[2], sheet)
+    return Expr(f"substr({t.sql}, CAST(trunc(least(greatest({start.sql}, 1), length({t.sql}) + 1)) AS BIGINT), "
+                f"CAST(trunc(least(greatest({n.sql}, 0), length({t.sql}))) AS BIGINT))", "txt",
+                errs(t.err, start.err, n.err, _bad(f"{start.sql} < 1 OR {n.sql} < 0")))
+
+
+def _text1(name: str, sql, typ: str = "txt"):
+    def impl(c, args, sheet):
+        arity(name, args, 1, 1)
+        t = _t(c, args[0], sheet)
+        return Expr(sql(t.sql), typ, t.err)
+    register(name)(impl)
+
+
+_text1("LEN", lambda t: f"CAST(length({t}) AS DOUBLE)", "num")
+_text1("TRIM", lambda t: f"regexp_replace(trim({t}, ' '), ' +', ' ', 'g')")  # Excel also squeezes inner spaces
+_text1("UPPER", lambda t: f"upper({t})")
+_text1("LOWER", lambda t: f"lower({t})")
+_text1("PROPER", lambda t: (f"array_to_string(list_transform(range(length({t})), i -> CASE WHEN i = 0 OR NOT "
+                            f"regexp_matches({t}[i], '[[:alpha:]]') THEN upper({t}[i + 1]) ELSE lower({t}[i + 1]) END), '')"))
+_text1("CLEAN", lambda t: f"regexp_replace({t}, '[\\x00-\\x1f]', '', 'g')")
+
+
+@register("SUBSTITUTE")
+def substitute(c, args, sheet):
+    arity("SUBSTITUTE", args, 3, 4)
+    t, old, new = (_t(c, a, sheet) for a in args[:3])
+    if len(args) == 3:
+        return Expr(f"(CASE WHEN {old.sql} = '' THEN {t.sql} ELSE replace({t.sql}, {old.sql}, {new.sql}) END)", "txt",
+                    errs(t.err, old.err, new.err))
+    n = _n(c, args[3], sheet)
+    parts = f"string_split({t.sql}, {old.sql})"
+    k = f"CAST(trunc(least(greatest({n.sql}, 0), len({parts}))) AS BIGINT)"
+    return Expr(f"(CASE WHEN {old.sql} = '' OR len({parts}) <= {k} THEN {t.sql} ELSE "
+                f"array_to_string({parts}[1:{k}], {old.sql}) || {new.sql} || array_to_string({parts}[{k} + 1:], {old.sql}) END)",
+                "txt", errs(t.err, old.err, new.err, n.err, _bad(f"{n.sql} < 1")))
+
+
+@register("REPLACE")
+def replace_(c, args, sheet):
+    arity("REPLACE", args, 4, 4)
+    t, start, n, new = _t(c, args[0], sheet), _n(c, args[1], sheet), _n(c, args[2], sheet), _t(c, args[3], sheet)
+    s = f"CAST(trunc(least(greatest({start.sql}, 1), length({t.sql}) + 1)) AS BIGINT)"
+    k = f"CAST(trunc(least(greatest({n.sql}, 0), length({t.sql}))) AS BIGINT)"
+    return Expr(f"(substr({t.sql}, 1, {s} - 1) || {new.sql} || substr({t.sql}, {s} + {k}))", "txt",
+                errs(t.err, start.err, n.err, new.err, _bad(f"{start.sql} < 1 OR {n.sql} < 0")))
+
+
+def _find(name: str, sensitive: bool):
+    def impl(c, args, sheet):
+        arity(name, args, 2, 3)
+        what, within = _t(c, args[0], sheet), _t(c, args[1], sheet)
+        start = _count_arg(c, args, sheet, 2)
+        s = f"TRY_CAST(trunc({start.sql}) AS BIGINT)"
+        rest = f"substr({within.sql}, {s})"
+        if sensitive:
+            pos = f"strpos({rest}, {what.sql})"
+            found = f"{pos} > 0"
+        else:  # SEARCH: ignores case, * and ? are wildcards, ~ escapes them
+            pat = f"regexp_escape(lower({what.sql}))"  # escaped: * -> \\*, ? -> \\?, ~ -> \\~
+            for a, b in (("'\\~\\*'", "chr(1)"), ("'\\~\\?'", "chr(2)"), ("'\\*'", "'.*'"), ("'\\?'", "'.'"),
+                         ("chr(1)", "'\\*'"), ("chr(2)", "'\\?'")):
+                pat = f"replace({pat}, {a}, {b})"
+            found = f"regexp_matches(lower({rest}), {pat})"
+            pos = f"(length(regexp_extract(lower({rest}), '(?s)^(.*?)(' || {pat} || ')', 1)) + 1)"
+        bad = f"{s} IS NULL OR {s} < 1 OR {s} > length({within.sql}) + 1 OR NOT ({found})"
+        return Expr(f"(CASE WHEN NOT ({bad}) THEN CAST({pos} + {s} - 1 AS DOUBLE) END)", "num",
+                    errs(what.err, within.err, start.err, _bad(bad)))
+    register(name)(impl)
+
+
+_find("FIND", sensitive=True)
+_find("SEARCH", sensitive=False)
+
+
+@register("REPT")
+def rept(c, args, sheet):
+    arity("REPT", args, 2, 2)
+    t, n = _t(c, args[0], sheet), _n(c, args[1], sheet)
+    bad = f"({n.sql} < 0 OR length({t.sql}) * trunc({n.sql}) > 32767)"
+    sql = (f"(CASE WHEN NOT {bad} THEN CASE WHEN {t.sql} = '' THEN '' "
+           f"ELSE repeat({t.sql}, CAST(trunc({n.sql}) AS BIGINT)) END END)")
+    return Expr(sql, "txt", errs(t.err, n.err, _bad(bad)))
+
+
+@register("VALUE")
+def value(c, args, sheet):
+    arity("VALUE", args, 1, 1)
+    return num(c.expr(args[0], sheet))
+
+
+@register("EXACT")
+def exact(c, args, sheet):
+    arity("EXACT", args, 2, 2)
+    a, b = _t(c, args[0], sheet), _t(c, args[1], sheet)
+    return Expr(f"({a.sql} = {b.sql})", "bool", errs(a.err, b.err))
+
+
+CP1252 = bytes(range(128, 160)).decode("cp1252", errors="replace")
+
+
+@register("CHAR")
+def char(c, args, sheet):
+    arity("CHAR", args, 1, 1)
+    n = _n(c, args[0], sheet)
+    k = f"TRY_CAST(trunc({n.sql}) AS INTEGER)"
+    table = "'" + CP1252.replace("'", "''") + "'"
+    return Expr(f"(CASE WHEN {k} BETWEEN 128 AND 159 THEN substr({table}, {k} - 127, 1) "
+                f"WHEN {k} BETWEEN 1 AND 255 THEN chr({k}) END)", "txt",
+                errs(n.err, _bad(f"COALESCE({k} < 1 OR {k} > 255, TRUE)")))  # Windows-1252, the character set of Excel for Windows
+
+
+def _fixed(decimals: int, grouped: bool, percent: bool):
+    def sql(x: str) -> str:
+        v = f"round({x} * 100, {decimals})" if percent else f"round({x}, {decimals})"
+        v = f"(CASE WHEN {v} = 0 THEN CAST(0 AS DOUBLE) ELSE {v} END)"  # real Excel: TEXT(-0.001,"0.00") is "0.00", not "-0.00"
+        body = f"format('{{:,.{decimals}f}}', {v})" if grouped else f"printf('%.{decimals}f', {v})"
+        return f"({body} || '%')" if percent else body
+    return sql
+
+
+NUMBER_FORMATS = {"General": num_text}
+for d in range(5):
+    tail = "." + "0" * d if d else ""
+    NUMBER_FORMATS[f"0{tail}"] = _fixed(d, False, False)
+    NUMBER_FORMATS[f"#,##0{tail}"] = _fixed(d, True, False)
+    NUMBER_FORMATS[f"0{tail}%"] = _fixed(d, False, True)
+FORMATS = dict(NUMBER_FORMATS)  # dates.py adds the date formats
+
+
+@register("TEXT")
+def text(c, args, sheet):
+    arity("TEXT", args, 2, 2)
+    if not isinstance(args[1], Str):
+        raise Unsupported("TEXT format must be text written in the formula")
+    fmt = FORMATS.get(args[1].value) or FORMATS.get(args[1].value.lower())
+    if fmt is None:
+        raise Unsupported(f"TEXT format {args[1].value!r} not supported yet")
+    if getattr(fmt, "is_date", False) and c.book.date1904:
+        raise Unsupported("1904 date system not supported yet")
+    x = c.expr(args[0], sheet)
+    if x.type == "txt":  # TEXT("abc", "0.00") passes text through
+        return x
+    x = num(x)
+    return Expr(fmt(x.sql), "txt", x.err)