diff --git a/README.md b/README.md index 8d5d3cb..126fdf1 100644 --- a/README.md +++ b/README.md @@ -36,72 +36,50 @@ xnhjrfyjvth3nxr 1 ## Design decisions -The assignment leaves a few points open. The choices made here are: +The assignment leaves a few points open: -**"Total number of symbols replaced" counts source symbols.** A line where -`bb` and `a` were both replaced counts 3, being the combined length of the -matched `value1` strings, not the number of replacements and not the length of -the substituted text. This makes the count a measure of how much of the -original line changed. +**"Total number of symbols replaced" counts source symbols.** A line where `bb` +and `a` were replaced counts 3, the combined length of the matched `value1` +strings, not the number of replacements. -**Overlapping patterns resolve to the longest match.** If the configuration -contains both `b` and `bb`, the input `bbbb` is read as two `bb` matches rather -than four `b` matches. The assignment guarantees unique values but not that -none is a prefix of another, so `prepare_pairs` orders the pairs by descending -length once, and `replace_line` takes the first match at each position. Without -a rule like this the output would depend on configuration file ordering. +**Overlapping patterns resolve to the longest match.** With both `b` and `bb` +configured, `bbbb` is two `bb` matches, not four `b`. Values are unique but may +still be prefixes of one another, so `prepare_pairs` orders by descending length +and `replace_line` takes the first match at each position. Otherwise the output +would depend on configuration file ordering. -**Ties keep their original file order.** The final sort keys only on the -replacement count and Python's sort is stable, so lines replaced an equal -number of times appear in the order they had in the input file. +**Ties keep their original file order.** The sort keys only on the count, and +Python's sort is stable. -**Unchanged lines are still printed.** The assignment says to sort the changed -lines but also to output the resulting text. Dropping lines that happened to -match nothing would silently lose content, so every line is printed and lines -with zero replacements simply sort last. +**Unchanged lines are still printed.** Dropping non-matching lines would +silently lose content, so they print last with a count of zero. -**Input is preserved apart from the line terminator.** Both `\n` and `\r\n` are -stripped; every other character is kept and eligible for replacement. The -configuration format has no quoting either, so whitespace inside a value is -significant: the trailing space in `a=z ` is part of the replacement value. +**Only the line terminator is stripped.** `\n` and `\r\n` both; every other +character stays replaceable. The format has no quoting, so the trailing space in +`a=z ` is part of the value. ## Performance characteristics -`replace_line` tries every configured pair at each position in the line, so the -work grows with both the line length and the number of pairs. Measured on a -fixed 20,000-line input of 40-character lines: +`replace_line` tries every pair at each position, so cost grows with both the +line length and the number of pairs. On a fixed 20,000-line input of +40-character lines, against two alternatives producing identical output: -| Pairs | Time | -| ----: | ---: | -| 3 | 0.27s | -| 100 | 6.13s | -| 1000 | 58.8s | +| Pairs | this implementation | `re` alternation | prefix tree | +| ----: | ------------------: | ---------------: | ----------: | +| 3 | 0.27s | 0.011s | 0.067s | +| 100 | 6.13s | 0.011s | 0.073s | +| 1000 | 58.80s | 0.011s | 0.067s | -Time tracks the pair count roughly proportionally, so it is the size of the -configuration rather than the size of the input that dominates. Parsing, -ordering the pairs and the final sort stay under a millisecond each even at -1000 pairs; the per-position scan is effectively the entire cost. +The regex is a constant-factor win, running the scan in C; the prefix tree is +the algorithmic one, taking the pair count out of the complexity entirely. The +explicit loop is kept because at the sizes described here the difference is not +observable, and the loop keeps the longest-match rule visible in the code. -Two alternatives were measured against the same input and produce identical -output: +The regex is only equivalent because `prepare_pairs` already orders patterns +longest first: Python's `re` is leftmost-first, not leftmost-longest. -- A single `re` alternation moves the scan into CPython's C engine and stays at - roughly 0.011s at every configuration size. It is only equivalent because - `prepare_pairs` already orders the patterns longest first: Python's `re` is - leftmost-first rather than leftmost-longest, so `b|bb` would otherwise match - `b` against the input `bb`. -- A prefix tree walked once per position removes the pair count from the - complexity rather than making each step cheaper, and stays at roughly 0.067s. - It is slower than the regex here only because it is interpreted Python - competing with a C engine. - -The explicit loop is kept: at the sizes this assignment describes the difference -is not observable, and the loop keeps the longest-match rule visible in the -code. A configuration large enough for the scan to matter would justify one of -the alternatives above. - -Memory is proportional to the size of the input file, since every line is held -before sorting and sorting cannot be done on a stream. +Memory is proportional to the input size, since every line is held before +sorting. ## Error handling