Review: csv.md and decimal.md complexity documentation

- Verified 13 csv complexity claims, all correct
- Added 30+ missing Decimal methods to complexity table
- Removed non-performance sections from csv.md:
  - Dialect Class, Attributes, Built-in/Custom Dialects
  - Quoting Constants, Quote Handling, Edge Cases
  - Encoding Handling, CSV vs JSON comparison
- Consolidated redundant csv reading examples into Lazy vs Eager
- Fixed bug: removed writer.writeheader() on csv.writer
- Refocused Best Practices on performance patterns

Co-authored-by: Amp <amp@ampcode.com>

Author: heikkitoivonen

docs/stdlib/csv.md

@@ -24,49 +24,21 @@ The `csv` module provides functionality for reading and writing CSV (Comma-Separ
 
 ## Reading CSV Files
 
-### Basic CSV Reading
+### Lazy vs Eager Reading
 
 ```python
 import csv
 
-# Create reader - O(1)
-with open('data.csv', 'r') as file:
-    reader = csv.reader(file)  # O(1)
-    
-    # Iterate rows - O(k) per row
-    for row in reader:  # O(k) per iteration
-        print(row)  # List of fields
-        # row = ['name', 'age', 'city']
-```
-
-### Row-by-Row Iteration (Memory Efficient)
-
-```python
-import csv
-
-# Lazy iteration for large files - O(1) memory
-with open('data.csv', 'r') as file:
-    reader = csv.reader(file)
-    
-    for row in reader:  # O(k) per row, O(1) memory
-        first_name = row[0]  # O(1)
-        age = row[1]         # O(1)
-        process(row)         # O(k)
-```
-
-### Reading All Rows
-
-```python
-import csv
+# LAZY: O(1) memory - process one row at a time (preferred for large files)
+with open('data.csv', 'r', newline='') as file:
+    reader = csv.reader(file)  # O(1) - creates iterator
+    for row in reader:         # O(k) per row, k = row length
+        process(row)           # Row discarded after processing
 
-# Load all rows into memory - O(n) memory
-with open('data.csv', 'r') as file:
+# EAGER: O(n) memory - loads entire file (only for small files or random access)
+with open('data.csv', 'r', newline='') as file:
     reader = csv.reader(file)
-    all_rows = list(reader)  # O(n) memory, n = file size
-
-# Now iterate from memory
-for row in all_rows:  # O(1) per iteration (already in memory)
-    process(row)
+    all_rows = list(reader)    # O(n*k) time, O(n*k) memory
 ```
 
 ## Writing CSV Files
@@ -93,24 +65,6 @@ with open('output.csv', 'w') as file:
 # File auto-closed
 ```
 
-### Escaping and Quoting
-
-```python
-import csv
-
-# CSV handles escaping automatically - O(k)
-with open('output.csv', 'w') as file:
-    writer = csv.writer(file)
-    
-    # Values with commas (auto-quoted) - O(k)
-    writer.writerow(['Alice', 'NYC, NY', 'Engineer'])  # O(k)
-    # Output: Alice,"NYC, NY",Engineer
-    
-    # Values with quotes (auto-escaped) - O(k)
-    writer.writerow(['Bob', 'Says "hi"'])  # O(k)
-    # Output: Bob,"Says ""hi"""
-```
-
 ## Dictionary-based CSV Operations
 
 ### Reading as Dictionaries
@@ -176,26 +130,6 @@ with open('data.csv', 'r', encoding='latin-1') as file:
         process(row)
 ```
 
-## Quote Handling
-
-### Quote Styles
-
-```python
-import csv
-
-# QUOTE_MINIMAL (default) - quotes only when needed
-writer = csv.writer(file, quoting=csv.QUOTE_MINIMAL)
-
-# QUOTE_ALL - quotes all fields
-writer = csv.writer(file, quoting=csv.QUOTE_ALL)
-
-# QUOTE_NONNUMERIC - quotes non-numeric fields
-writer = csv.writer(file, quoting=csv.QUOTE_NONNUMERIC)
-
-# QUOTE_NONE - no quoting (must escape manually)
-writer = csv.writer(file, quoting=csv.QUOTE_NONE, escapechar='\\')
-```
-
 ## Common Patterns
 
 ### Reading and Processing
@@ -296,23 +230,23 @@ with open('merged.csv', 'w') as outfile:
 ```python
 import csv
 
-# Write in batches (more efficient) - O(n*k)
-with open('output.csv', 'w') as file:
+# Write in batches - reduces per-row overhead
+with open('output.csv', 'w', newline='') as file:
     writer = csv.writer(file)
-    writer.writeheader()
+    writer.writerow(['Name', 'Age', 'City'])  # Header
 
     # Collect rows in memory, then write batch
     batch = []
     for row in generate_rows():  # O(n)
         batch.append(row)
 
         if len(batch) >= 1000:  # Write every 1000 rows
-            writer.writerows(batch)  # O(1000*k)
+            writer.writerows(batch)  # O(1000*k) - one call vs 1000
             batch = []
 
     # Write remaining
     if batch:
-        writer.writerows(batch)  # O(final_batch*k)
+        writer.writerows(batch)
 ```
 
 ### Reading Large Files Efficiently
@@ -337,122 +271,27 @@ with open('large_file.csv', 'r') as file:
         process_chunk(chunk)
 ```
 
-## Encoding Handling
-
-```python
-import csv
-
-# UTF-8 (default) - O(1) setup
-with open('data.csv', 'r', encoding='utf-8') as file:
-    reader = csv.reader(file)
-    for row in reader:  # O(k) per row
-        process(row)
-
-# Latin-1 (for European data) - O(1) setup
-with open('data.csv', 'r', encoding='latin-1') as file:
-    reader = csv.reader(file)
-    for row in reader:
-        process(row)
-
-# Write with specific encoding
-with open('output.csv', 'w', encoding='utf-8', newline='') as file:
-    writer = csv.writer(file)
-    writer.writerow(['Name', 'Value'])
-```
-
-## Edge Cases
-
-### Handling Empty Fields
-
-```python
-import csv
-
-# Empty fields are preserved
-data = [
-    ['Name', '', 'City'],  # Empty age field
-    ['Alice', '', 'NYC'],
-    ['Bob', '25', 'LA']
-]
-
-with open('output.csv', 'w') as file:
-    writer = csv.writer(file)
-    writer.writerows(data)
-
-# Reading back
-with open('output.csv', 'r') as file:
-    reader = csv.DictReader(file)
-    for row in reader:
-        age = row[''] if '' in row else None  # Handle empty header
-```
-
-### Handling Newlines
-
-```python
-import csv
-
-# newline='' is required for proper handling (Python 3)
-with open('output.csv', 'w', newline='') as file:
-    writer = csv.writer(file)
-    writer.writerow(['Name', 'Description'])
-    writer.writerow(['Alice', 'Multi\nline\ntext'])  # Properly quoted
-
-# Reading
-with open('output.csv', 'r', newline='') as file:
-    reader = csv.reader(file)
-    for row in reader:
-        print(row)
-```
-
-## Comparison: CSV vs JSON vs Pickle
-
-```python
-import csv
-import json
-import pickle
-
-# CSV - good for tabular data
-# Pros: Simple, human-readable, Excel-compatible
-# Cons: No schema, string values
-
-# JSON - good for hierarchical data
-# Pros: Structured, preserves types
-# Cons: More verbose
-
-# Pickle - good for Python object serialization
-# Pros: Preserves exact Python types
-# Cons: Python-specific, security risk
-
-# CSV is preferred for tabular data export
-```
-
 ## Version Notes
 
-- **Python 2.x**: csv module available, unicode handling complex
-- **Python 3.x**: csv module standard, better unicode support
-- **All versions**: Use `newline=''` parameter in Python 3
+- **Python 3.12+**: Added `QUOTE_STRINGS` and `QUOTE_NOTNULL` constants
+- **All Python 3**: Use `newline=''` parameter when opening CSV files
 
 ## Related Modules
 
-- **pandas** - High-level CSV operations and data manipulation
-- **[json](json.md)** - Alternative structured data format
-- **[io](io.md)** - Low-level I/O operations
+- **pandas** - Higher-level CSV with O(n) memory but faster vectorized operations
+- **[json](json.md)** - O(n) parsing; use for hierarchical data
+- **[io](io.md)** - StringIO for in-memory CSV processing
 
-## Best Practices
+## Performance Best Practices
 
 ✅ **Do**:
 
-- Use `csv.DictReader` for named columns (clearer)
-- Use `csv.reader` for simple positional access
-- Use `newline=''` when opening CSV files (Python 3)
-- Specify `encoding='utf-8'` explicitly
-- Process large files line-by-line (lazy iteration)
-- Close files with context manager (`with` statement)
+- Process large files lazily (O(1) memory) instead of `list(reader)` (O(n) memory)
+- Use `writerows()` for batches - fewer function calls than repeated `writerow()`
+- Use `csv.reader` for positional access (O(1) per field vs O(1) dict lookup overhead)
 
 ❌ **Avoid**:
 
-- Manual string splitting (let csv handle parsing)
-- Assuming comma is delimiter (specify if different)
-- Loading entire large CSV into memory at once
-- Forgetting newline='' parameter
-- Mixing csv.reader with manual field indexing
-- Trying to handle complex nested structures (use JSON)
+- `list(reader)` on large files - loads entire file into memory O(n)
+- Manual string splitting with `split(',')` - incorrect for quoted fields, same O(k) complexity but buggy
+- Repeated small writes - buffer with batches for better I/O performance

docs/stdlib/decimal.md

@@ -8,11 +8,38 @@ The `decimal` module provides support for decimal floating point arithmetic with
 |-----------|------|-------|-------|
 | `Decimal(value)` | O(n) | O(n) | n = digits in value |
 | `Decimal.from_float(f)` | O(1) | O(1) | Convert from float |
+| `Decimal.from_number(x)` | O(n) | O(n) | Convert from int/float/Decimal |
 | Addition/Subtraction | O(n) | O(n) | n = max digits |
 | Multiplication | O(n²) | O(n) | Grade-school; Python uses Karatsuba for large n |
 | Division | O(n²) | O(n) | Long division algorithm |
 | `quantize()` | O(n) | O(n) | Round to precision |
-| Comparison | O(n) | O(1) | n = digits to compare |
+| `normalize()` | O(n) | O(n) | Remove trailing zeros |
+| `sqrt()` | O(n²) | O(n) | Square root |
+| `exp()` / `ln()` / `log10()` | O(n²) | O(n) | Transcendental functions |
+| Comparison (`compare()`) | O(n) | O(1) | n = digits to compare |
+| `compare_total()` | O(n) | O(1) | Compare with total ordering |
+| `as_tuple()` | O(n) | O(n) | Return (sign, digits, exponent) |
+| `as_integer_ratio()` | O(n) | O(n) | Return (numerator, denominator) |
+| `to_eng_string()` | O(n) | O(n) | Engineering notation string |
+| `to_integral_value()` | O(n) | O(n) | Round to integer |
+| `copy_abs()` / `copy_negate()` | O(n) | O(n) | Copy with sign change |
+| `copy_sign(other)` | O(n) | O(n) | Copy with other's sign |
+| `is_finite()` / `is_infinite()` | O(1) | O(1) | Check special values |
+| `is_nan()` / `is_qnan()` / `is_snan()` | O(1) | O(1) | Check NaN types |
+| `is_signed()` / `is_zero()` | O(1) | O(1) | Check sign/zero |
+| `is_normal()` / `is_subnormal()` | O(1) | O(1) | Check normalization |
+| `number_class()` | O(1) | O(1) | Return classification string |
+| `adjusted()` | O(1) | O(1) | Return adjusted exponent |
+| `radix()` | O(1) | O(1) | Return 10 (base) |
+| `same_quantum(other)` | O(1) | O(1) | Check same exponent |
+| `scaleb(exp)` | O(n) | O(n) | Scale by power of 10 |
+| `shift(n)` / `rotate(n)` | O(n) | O(n) | Shift/rotate digits |
+| `logical_and/or/xor/invert` | O(n) | O(n) | Logical ops on digit strings |
+| `fma(x, y)` | O(n²) | O(n) | Fused multiply-add |
+| `max(other)` / `min(other)` | O(n) | O(1) | Return max/min |
+| `next_plus()` / `next_minus()` | O(n) | O(n) | Next representable value |
+| `next_toward(other)` | O(n) | O(n) | Next value toward other |
+| `remainder_near(other)` | O(n²) | O(n) | IEEE remainder |
 
 ## Creating Decimal Objects