Manual review of builtin functions from beginning to issubclass

Mostly removing content that has nothing to do with performance.

Author: heikkitoivonen

docs/builtins/chr.md

@@ -210,18 +210,6 @@ except TypeError:
     pass
 ```
 
-## Surrogates and Edge Cases
-
-```python
-# Valid surrogate pairs (combined characters)
-# These are valid Unicode code points
-chr(0xDC00)    # Surrogate character (valid as standalone)
-
-# But combining characters exist
-chr(0x0301)    # Combining acute accent
-# Used with other characters: 'e' + chr(0x0301) = 'é'
-```
-
 ## Performance Considerations
 
 ### vs String Literals
@@ -259,15 +247,11 @@ result = ''.join(map(chr, codes))
 
 ✅ **Do**:
 
-- Use `chr()` to create characters from code points
-- Use with `ord()` for bidirectional conversion
 - Use `map(chr, codes)` for bulk conversion
-- Use for encoding/decoding operations
 
 ❌ **Avoid**:
 
 - Creating strings character by character (use join)
-- Assuming ASCII-only (support Unicode)
 - Using string literals when code points are computed
 - Unnecessary intermediate lists
 

docs/builtins/divmod.md

@@ -269,14 +269,10 @@ for i in range(large_count):
 - Use `divmod()` when you need both quotient and remainder
 - Use for base conversion algorithms
 - Use for time calculations and pagination
-- Remember floor division semantics for negatives
 
 ❌ **Avoid**:
 
 - Computing `q` and `r` separately when you need both
-- Forgetting about negative number behavior
-- Assuming truncation toward zero (Python uses floor)
-- Dividing by zero without checking
 
 ## Related Functions
 

docs/builtins/iter.md

@@ -15,26 +15,6 @@ The `iter()` function creates an iterator object from an iterable, and `next()`
 
 ## Creating Iterators
 
-### Basic Iterator Creation
-
-```python
-# Create iterator from list - O(1)
-lst = [1, 2, 3, 4, 5]
-it = iter(lst)  # O(1) - returns list iterator
-
-# Create iterator from string - O(1)
-s = "hello"
-it = iter(s)  # O(1) - returns string iterator
-
-# Create iterator from dict - O(1)
-d = {'a': 1, 'b': 2}
-it = iter(d)  # O(1) - returns dict_keyiterator
-
-# Create iterator from set - O(1)
-st = {1, 2, 3}
-it = iter(st)  # O(1) - returns set iterator
-```
-
 ### Iterating Over Sequences
 
 ```python
@@ -260,6 +240,18 @@ for it in [it1, it2, it3]:
             break
 ```
 
+### Consuming First Item Separately
+
+```python
+# Use iter() explicitly when you need to advance past some items manually
+data = ["header", "row1", "row2", "row3"]
+it = iter(data)
+
+header = next(it)       # O(1) - consume first item separately
+for row in it:          # O(n) - continues from second item
+    print(f"Row: {row}")
+```
+
 ### Zip with Iterators
 
 ```python

docs/builtins/min.md

@@ -58,7 +58,7 @@ lst = list(range(1000000))
 result = min(lst)  # ~1M comparisons
 
 # Same complexity with generators
-result = min(x**2 for x in range(10000))  # O(n)
+result = min(x**2 for x in range(10000))  # O(n) time, O(1) space
 ```
 
 ### Working with Different Types
@@ -109,6 +109,7 @@ shortest = min(words, key=len)  # "code"
 # O(n) - compare tuples lexicographically
 coords = [(1, 5), (3, 2), (2, 8)]
 min_coord = min(coords)  # (1, 5) - compared by first element
+# If first equal, compares second element, etc.
 
 # Compare by second element instead
 min_by_y = min(coords, key=lambda c: c[1])  # (3, 2)

docs/builtins/ord.md

@@ -190,18 +190,6 @@ except TypeError:
 
 ## Performance Considerations
 
-### vs ASCII Codes
-
-```python
-# ord() - works with all Unicode
-result = ord('€')  # 8364
-
-# ASCII - only 0-127
-import string
-if ord('a') in range(128):
-    print("ASCII character")
-```
-
 ### Bulk Operations
 
 ```python
@@ -218,17 +206,11 @@ codes = list(map(ord, text))  # O(n) - slightly more efficient
 
 ✅ **Do**:
 
-- Use `ord()` for getting character code points
-- Use with `chr()` for bidirectional conversion
 - Use `map(ord, string)` for bulk operations
-- Use for encoding/decoding operations
 
 ❌ **Avoid**:
 
 - Using `ord()` for character type checking (use str methods)
-- Assuming ASCII-only (support Unicode)
-- Passing multiple characters or strings
-- Building unnecessary lookup tables
 
 ## Related Functions
 

docs/builtins/pow.md

@@ -209,7 +209,7 @@ except ZeroDivisionError:
 
 - **[abs()](abs.md)** - Absolute value
 - **math.pow()** - Float-only power
-- **[**  operator** - Exponentiation (equivalent)
+- **operator\*\*** - Exponentiation (equivalent)
 - **math.isqrt()** - Integer square root
 
 ## Comparison with Alternatives

docs/builtins/reversed.md

@@ -158,38 +158,6 @@ for item in items[::-1]:
 # reversed() is more memory efficient
 ```
 
-### reversed() vs Reverse Method
-
-```python
-# List has reverse() method
-items = [1, 2, 3, 4, 5]
-items.reverse()  # O(n) in-place, modifies original
-
-# reversed() doesn't modify original
-items = [1, 2, 3, 4, 5]
-for item in reversed(items):
-    process(item)
-# Original unchanged
-
-# Use reversed() to preserve original
-# Use reverse() to modify in-place
-```
-
-### reversed() vs Sorting
-
-```python
-# reversed() preserves order
-items = [3, 1, 4, 1, 5, 9, 2, 6]
-result = list(reversed(items))
-# [6, 2, 9, 5, 1, 4, 1, 3]
-
-# sorted with reverse=True sorts
-result = sorted(items, reverse=True)
-# [9, 6, 5, 4, 3, 2, 1, 1]
-
-# Different operations - don't confuse them
-```
-
 ## Supported Types
 
 ### Works With
@@ -204,29 +172,6 @@ range_rev = reversed(range(1, 4))  # O(1)
 # All work efficiently
 ```
 
-### Doesn't Work With
-
-```python
-# Types without __reversed__ method
-try:
-    reversed({1, 2, 3})  # TypeError - sets
-except TypeError:
-    pass
-
-try:
-    reversed({'a': 1, 'b': 2})  # TypeError - dicts
-except TypeError:
-    pass
-
-try:
-    reversed(42)  # TypeError - integers
-except TypeError:
-    pass
-
-# But you can iterate them differently
-reversed(list(my_set))  # Convert first
-```
-
 ## Edge Cases
 
 ### Empty Sequence

docs/builtins/round.md

@@ -177,20 +177,6 @@ round(1e20, 2)     # 1e+20
 round(123456789.123, 2)  # 123456789.12
 ```
 
-## Floating Point Pitfalls
-
-```python
-# Be aware of float representation issues
-round(2.675, 2)    # 2.67 (not 2.68!)
-# Float representation: 2.675 is actually 2.6749999...
-
-# For exact rounding use Decimal
-from decimal import Decimal, ROUND_HALF_UP
-
-result = float(Decimal("2.675").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP))
-# 2.68 - exact
-```
-
 ## Performance Notes
 
 ```python
@@ -209,17 +195,10 @@ t_format = timeit.timeit(lambda: f"{3.14159:.2f}", number=10**7)
 
 ✅ **Do**:
 
-- Use `round()` for numeric rounding
-- Use `Decimal` for financial calculations
 - Use `f"{x:.2f}"` for display formatting
-- Remember banker's rounding behavior
-- Use negative digits for rounding to powers of 10
 
 ❌ **Avoid**:
 
-- Using `round()` for financial calculations (precision issues)
-- Assuming traditional rounding (0.5 rounds up) - Python uses banker's
-- Relying on exact float precision
 - Using `round()` for display (use format strings)
 
 ## Related Functions

docs/builtins/sorted.md

@@ -253,7 +253,7 @@ result = sorted(original)
 original = [3, 1, 4, 1, 5]
 original.sort()
 
-# Both: O(n log n) time, O(n) space for Timsort
+# Both: O(n log n) time, O(n) space for Timsort/Powersort
 # Choose based on whether you need original
 ```
 
@@ -290,7 +290,7 @@ result = sorted([42])
 ### Already Sorted
 
 ```python
-# O(n) - Timsort detects and handles efficiently
+# O(n) - Timsort/Powersort detects and handles efficiently
 numbers = list(range(1000000))
 result = sorted(numbers)  # Nearly O(n)
 ```

docs/builtins/sum.md

@@ -48,11 +48,11 @@ total = sum([x for x in range(1000000)])  # O(n) time, O(n) space
 ### Counting Items
 
 ```python
-# O(n) - count 1s
+# O(n) time, O(n) space - list comprehension
 count = sum([1 for x in range(100) if x % 2 == 0])  # 50 even numbers
 
-# Better: use len() or sum with boolean
-count = sum(1 for x in range(100) if x % 2 == 0)  # Still O(n)
+# Better: sum with boolean (True=1, False=0) - O(n) time, O(1) space
+count = sum(x % 2 == 0 for x in range(100))  # 50 even numbers
 ```
 
 ### Computing Statistics
@@ -70,17 +70,17 @@ average = sum(numbers) / len(numbers)  # Iterate twice
 ### Flattening Lists
 
 ```python
-# O(n²) - inefficient!
-# Each sum call is O(n), and we have n lists
+# O(n*k) - inefficient! n=number of lists, k=items per list
+# Each + creates a new list and copies all accumulated items
 nested = [[1, 2], [3, 4], [5, 6]]
-flat = sum(nested, [])  # O(n²) - avoid this!
+flat = sum(nested, [])  # O(n*k) - avoid this!
 
 # Better approaches:
-# O(n) - single iteration
+# O(n*k) total items, but no repeated copying
 from itertools import chain
 flat = list(chain(*nested))
 
-# O(n) - unpacking
+# O(n*k) - single pass, no repeated copying
 flat = [item for sublist in nested for item in sublist]
 ```
 
@@ -174,40 +174,6 @@ total = sum(numbers)  # 15
 totals = list(accumulate(numbers))  # [1, 3, 6, 10, 15]
 ```
 
-## Pitfalls
-
-### Floating Point Precision
-
-```python
-# Summing floats can lose precision
-numbers = [0.1] * 10
-print(sum(numbers))  # 1.0000000000000007, not exactly 1.0
-
-# Better: use decimal for financial calculations
-from decimal import Decimal
-numbers = [Decimal('0.1')] * 10
-print(sum(numbers, Decimal('0')))  # Exact: 1.0
-```
-
-### Empty Sequence
-
-```python
-# sum() of empty is 0
-result = sum([])  # 0
-
-# Or start value
-result = sum([], start=100)  # 100
-
-# But TypeError with strings if no start
-try:
-    sum(["a", "b"])  # TypeError
-except TypeError:
-    pass
-
-# Works with start=""
-result = sum(["a", "b"], start="")  # "ab"
-```
-
 ## Performance Notes
 
 ```python
@@ -233,15 +199,11 @@ fsum([0.1] * 10)  # More precise for floats
 
 - Use `sum()` for numeric aggregation
 - Use generator expressions with `sum()` for memory efficiency
-- Use `sum([], start=[])` with explicit start value
-- Use `math.fsum()` when precision matters
 
 ❌ **Avoid**:
 
 - `sum(nested_lists, [])` - O(n²) concatenation
 - `sum(strings, "")` - inefficient string concatenation
-- Forgetting start value (causes TypeError with non-numeric sequences)
-- Summing booleans when `any()` or `all()` is clearer
 
 ## Related Functions