tint_me 1.0.0 → 1.1.0

data/benchmark/2025-09-08-style-caching-optimization/11_constant_vs_cache_analysis.txt

@@ -1,74 +0,0 @@
-CONSTANT ACCESS vs CACHING ANALYSIS
-====================================
-Date: 2025-09-08
-
-## Implementation Comparison
-
-### Caching Approach (Previous)
-```ruby
-# Initialization
-@reset_code = sgr_builder.reset_code
-
-# Usage
-"#{@prefix}#{text}#{@reset_code}"
-```
-
-### Constant Access Approach (Current)
-```ruby  
-# Initialization
-# (no @reset_code caching)
-
-# Usage  
-"#{@prefix}#{text}#{SGRBuilder::RESET_CODE}"
-```
-
-## Performance & Memory Results
-
-| Metric | Caching | Constant Access | Difference |
-|--------|---------|-----------------|------------|
-| **Performance** | 5.44M/s | 5.38M/s | **1% slower** |
-| **Creation Memory** | 6.1KB | 6.0KB | **8 bytes saved** |
-| **Runtime Memory** | 424 bytes | 616 bytes | **45% more** |
-
-## Analysis
-
-### Memory Trade-offs:
-
-**Creation Time:**
-- ✅ **8 bytes saved per Style instance** (no @reset_code storage)
-- Negligible but consistent savings
-
-**Runtime:**
-- ❌ **45% more memory per call** for simple styles (424 → 616 bytes)
-- Suggests constant lookup has slight overhead
-
-### Performance Impact:
-
-- **1% slower performance** - minimal but measurable
-- Constant lookup vs instance variable access overhead
-- Still much faster than baseline (5.38M vs 766k original)
-
-### Code Complexity:
-
-**Constant Access Pros:**
-- Slightly less memory per instance  
-- Fewer instance variables
-- Direct reference to source of truth
-
-**Caching Pros:**  
-- Faster runtime performance
-- Lower runtime memory usage
-- Simpler call method (no constant lookup)
-
-## Recommendation
-
-**Keep the caching approach** for optimal performance:
-
-1. **Performance priority**: The 1% performance difference matters for a performance-critical method
-2. **Runtime efficiency**: Lower memory usage during frequent calls
-3. **Minimal memory cost**: 8 bytes per instance is negligible for the benefits
-4. **Consistent pattern**: Matches the prefix caching strategy
-
-The reset_code is accessed on every Style#call, making instance variable access more efficient than constant lookup. The tiny memory savings don't justify the performance cost.
-
-**Final implementation: Cache both @prefix and @reset_code**

data/benchmark/2025-09-08-style-caching-optimization/12_empty_prefix_analysis.txt

@@ -1,81 +0,0 @@
-EMPTY PREFIX ANALYSIS
-=====================
-Date: 2025-09-08
-
-## When @prefix is Empty
-
-Based on testing, `@prefix` becomes empty ("") in these cases:
-
-1. **No styling attributes**: `Style.new`
-2. **Nil values**: `Style.new(foreground: nil)`
-3. **Default values**: `Style.new(foreground: :default)`
-4. **False effects**: `Style.new(bold: false)`
-5. **Default instance**: `Style.new.to_h` result
-
-**Key Finding**: `@prefix` is NEVER nil, always either `""` (empty) or a non-empty string.
-
-## Usage Likelihood Analysis
-
-### High Probability Cases:
-- **Default/plain text styling**: Applications may use `Style.new` for conditional styling
-- **Template systems**: May create base styles that are sometimes empty
-- **Configuration-driven styling**: User settings might result in "no styling"
-
-### Low Probability Cases:
-- **Performance-critical code**: Unlikely to create empty styles intentionally
-- **Library internal usage**: Most internal usage probably has specific styling
-
-## Current vs Alternative Implementations
-
-### Current: `empty?` check
-```ruby
-def call(text)
-  return text if @prefix.empty?
-  "#{@prefix}#{text}#{@reset_code}"
-end
-```
-
-### Alternative 1: Length check
-```ruby
-def call(text)
-  return text if @prefix.length == 0
-  "#{@prefix}#{text}#{@reset_code}"
-end
-```
-
-### Alternative 2: String comparison
-```ruby  
-def call(text)
-  return text if @prefix == ""
-  "#{@prefix}#{text}#{@reset_code}"
-end
-```
-
-### Alternative 3: No check (always interpolate)
-```ruby
-def call(text)
-  "#{@prefix}#{text}#{@reset_code}"
-end
-```
-
-## Performance Considerations
-
-**If empty styles are rare (<5% of calls):**
-- Current `empty?` check may be unnecessary overhead
-- Alternative 3 (no check) might be faster overall
-
-**If empty styles are common (>20% of calls):**
-- Current implementation is optimal
-- Early return saves string interpolation cost
-
-## Recommendation for Testing
-
-Test Alternative 3 (no empty check) to see if:
-1. The empty check overhead exceeds the interpolation savings
-2. Performance improves when most styles are non-empty
-
-This would be especially valuable since empty styles might be rare in typical usage patterns.
-
-## Conclusion
-
-The `nil?` vs `empty?` question is moot since `@prefix` is never nil. The real question is whether the `empty?` check itself is worth the overhead for the expected usage patterns of the library.

data/benchmark/2025-09-08-style-caching-optimization/13_nil_check_optimization_results.txt

@@ -1,107 +0,0 @@
-============================================================
-TIntMe Style Performance Benchmark
-============================================================
-
-Memory Usage Analysis:
-----------------------------------------
-Calculating -------------------------------------
- Create simple style     6.056k memsize (     0.000  retained)
-                        58.000  objects (     0.000  retained)
-                         2.000  strings (     0.000  retained)
-Create complex style     7.752k memsize (     0.000  retained)
-                        79.000  objects (     0.000  retained)
-                         9.000  strings (     0.000  retained)
-Apply simple style (short text)
-                       424.000  memsize (     0.000  retained)
-                         3.000  objects (     0.000  retained)
-                         1.000  strings (     0.000  retained)
-Apply complex style (short text)
-                       264.000  memsize (     0.000  retained)
-                         2.000  objects (     0.000  retained)
-                         1.000  strings (     0.000  retained)
-
-Comparison:
-Apply complex style (short text):        264 allocated
-Apply simple style (short text):        424 allocated - 1.61x more
- Create simple style:       6056 allocated - 22.94x more
-Create complex style:       7752 allocated - 29.36x more
-
-Performance Benchmark (operations per second):
-----------------------------------------
-ruby 3.2.9 (2025-07-24 revision 8f611e0c46) [arm64-darwin24]
-Warming up --------------------------------------
- Create simple style     2.856k i/100ms
-Create complex style     2.237k i/100ms
-Apply simple style (short)
-                       532.099k i/100ms
-Apply simple style (medium)
-                       502.313k i/100ms
-Apply simple style (long)
-                       488.252k i/100ms
-Apply complex style (short)
-                       375.127k i/100ms
-Apply complex style (medium)
-                       465.987k i/100ms
-Apply complex style (long)
-                       465.624k i/100ms
-Apply hex style (short)
-                       487.755k i/100ms
-Calculating -------------------------------------
- Create simple style     28.773k (± 3.1%) i/s   (34.76 μs/i) -    145.656k in   5.067273s
-Create complex style     24.042k (± 3.7%) i/s   (41.59 μs/i) -    120.798k in   5.031925s
-Apply simple style (short)
-                          5.456M (± 2.7%) i/s  (183.29 ns/i) -     27.669M in   5.075360s
-Apply simple style (medium)
-                          4.795M (± 2.8%) i/s  (208.54 ns/i) -     24.111M in   5.032058s
-Apply simple style (long)
-                          4.520M (± 5.1%) i/s  (221.24 ns/i) -     22.948M in   5.091184s
-Apply complex style (short)
-                          3.792M (± 3.6%) i/s  (263.74 ns/i) -     19.131M in   5.052424s
-Apply complex style (medium)
-                          4.633M (± 6.4%) i/s  (215.86 ns/i) -     23.299M in   5.059053s
-Apply complex style (long)
-                          4.508M (± 3.5%) i/s  (221.85 ns/i) -     22.816M in   5.068199s
-Apply hex style (short)
-                          4.534M (± 7.2%) i/s  (220.55 ns/i) -     22.924M in   5.085921s
-
-Comparison:
-Apply simple style (short):  5455745.6 i/s
-Apply simple style (medium):  4795323.9 i/s - 1.14x  slower
-Apply complex style (medium):  4632694.4 i/s - 1.18x  slower
-Apply hex style (short):  4534207.7 i/s - 1.20x  slower
-Apply simple style (long):  4520017.7 i/s - 1.21x  slower
-Apply complex style (long):  4507642.6 i/s - 1.21x  slower
-Apply complex style (short):  3791544.6 i/s - 1.44x  slower
- Create simple style:    28772.5 i/s - 189.62x  slower
-Create complex style:    24041.8 i/s - 226.93x  slower
-
-
-Repeated Application Benchmark:
-----------------------------------------
-Applying the same style 1000 times to measure caching benefit...
-ruby 3.2.9 (2025-07-24 revision 8f611e0c46) [arm64-darwin24]
-Warming up --------------------------------------
-  1000x simple style   644.000 i/100ms
- 1000x complex style   440.000 i/100ms
-     1000x hex style   542.000 i/100ms
-Calculating -------------------------------------
-  1000x simple style      6.412k (± 2.6%) i/s  (155.95 μs/i) -     32.200k in   5.025177s
- 1000x complex style      4.297k (± 2.5%) i/s  (232.70 μs/i) -     21.560k in   5.020173s
-     1000x hex style      5.504k (± 2.4%) i/s  (181.70 μs/i) -     27.642k in   5.025548s
-
-Comparison:
-  1000x simple style:     6412.2 i/s
-     1000x hex style:     5503.6 i/s - 1.17x  slower
- 1000x complex style:     4297.4 i/s - 1.49x  slower
-
-
-Object Allocation Analysis:
-----------------------------------------
-Create simple style: 117 objects allocated
-Create complex style: 136 objects allocated
-Apply simple style 100x: 104 objects allocated
-Apply complex style 100x: 104 objects allocated
-
-============================================================
-Benchmark complete!
-============================================================

data/benchmark/2025-09-08-style-caching-optimization/14_nil_vs_empty_check_analysis.txt

@@ -1,81 +0,0 @@
-NIL? vs EMPTY? CHECK ANALYSIS
-==============================
-Date: 2025-09-08
-
-## Implementation Comparison
-
-### Previous: empty? check
-```ruby
-# Initialization
-@prefix = sgr_builder.prefix_codes(...)
-
-# Usage
-return text if @prefix.empty?
-```
-
-### Current: nil? check with optimized assignment
-```ruby
-# Initialization  
-prefix = sgr_builder.prefix_codes(...)
-@prefix = prefix.empty? ? nil : prefix
-
-# Usage
-return text unless @prefix  # equivalent to @prefix.nil?
-```
-
-## Performance Results
-
-| Metric | empty? check | nil? check | Improvement |
-|--------|-------------|------------|-------------|
-| Simple style | 5.44M/s | 5.46M/s | **+0.4% faster** |
-| Performance gain | Baseline | +22k ops/s | Marginal but positive |
-
-## Analysis
-
-### Why nil? check is (slightly) faster:
-
-1. **Simpler comparison**: `nil?` is checking against a single value (nil)
-2. **No method call**: `unless @prefix` is more direct than `@prefix.empty?`
-3. **CPU cache friendly**: nil comparisons are highly optimized in Ruby
-
-### Trade-offs:
-
-**Pros of nil? optimization:**
-- ✅ Slightly faster runtime performance
-- ✅ More direct conditional check
-- ✅ Saves one string object per empty Style (empty string not stored)
-
-**Cons of nil? optimization:**
-- ❌ Additional logic in initialization (empty? check to decide nil)
-- ❌ Slightly more complex initialization code
-- ❌ Marginal complexity increase
-
-## Memory Impact
-
-### Empty Style instances:
-- **Before**: `@prefix = ""` (empty string object)  
-- **After**: `@prefix = nil` (no string object)
-- **Savings**: ~40 bytes per empty Style instance
-
-### Non-empty Style instances:
-- No difference in memory usage
-
-## Recommendation
-
-**Keep the nil? optimization** because:
-
-1. **Performance improvement**: Even marginal gains matter for high-frequency methods
-2. **Memory efficiency**: Eliminates empty string objects for empty Styles  
-3. **Semantic clarity**: nil clearly indicates "no styling" vs empty string
-4. **Ruby idiom**: `unless value` is more idiomatic than `if value.empty?`
-
-The initialization complexity increase is minimal and the benefits outweigh the costs.
-
-## Final Implementation Pattern
-
-This optimization demonstrates an important pattern:
-- Transform empty values to nil during initialization
-- Use simpler nil checks at runtime
-- Trade slight initialization complexity for runtime performance
-
-Perfect for performance-critical methods called frequently.

data/benchmark/2025-09-08-style-caching-optimization/README.md

@@ -1,45 +0,0 @@
-# Style Caching Performance Optimization Results
-
-Date: 2025-09-08  
-Issue: #5  
-
-## Files in this directory:
-
-### 1. Benchmark Script
-- `benchmark_script.rb` - Performance testing script used for all measurements
-
-### 2. Benchmark Results (in chronological order)
-- `01_baseline_results.txt` - Original performance before optimization
-- `02_with_full_caching_results.txt` - Performance with both prefix and reset_code caching
-- `03_prefix_only_caching_results.txt` - Performance with prefix caching only (no reset_code cache)
-- `06_append_operator_results.txt` - Performance with << operator instead of string interpolation
-
-### 3. Analysis Files
-- `04_baseline_vs_optimized_analysis.txt` - Comparison between baseline and fully optimized version
-- `05_caching_approaches_comparison.txt` - Comparison between different caching strategies
-- `07_string_concatenation_comparison.txt` - String interpolation vs << operator performance analysis
-
-## Key Results Summary
-
-### Final Implementation: Full Caching with String Interpolation
-- **7-18x performance improvement** in style application
-- **85-91% reduction** in object allocations
-- **Minimal memory overhead** at creation time (6-18% increase)
-- **Best overall trade-off** for typical usage patterns
-
-### Primary Optimization Results (Included in PR)
-- **Full caching** (prefix + reset_code): Best performance
-- **Prefix-only caching**: 14-22% slower, minimal memory savings
-- **No caching** (baseline): Significantly slower, high object allocations
-
-### Additional Experiments (Reference Only)
-- **String interpolation vs << operator**: String interpolation 13-47% faster
-- **freeze optimization**: 2-4% slower (counter-productive)
-- **Constant vs caching**: Caching 1% faster with better memory usage
-- **nil? vs empty? check**: nil? optimization provides 0.4% improvement
-
-## Implementation Details
-- Cache `@prefix` and `@reset_code` in `initialize` method before `super`
-- Simplified `call` method from ~35 lines to 3 lines of string concatenation
-- Maintains identical API and immutability guarantees
-- Transforms algorithm from O(n) to O(1) per call

data/benchmark/2025-09-08-style-caching-optimization/benchmark_script.rb

@@ -1,180 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "benchmark/ips"
-require "benchmark/memory"
-require "bundler/setup"
-require "tint_me"
-
-# Test data
-SHORT_TEXT = "Hello"
-MEDIUM_TEXT = "The quick brown fox jumps over the lazy dog"
-LONG_TEXT = "Lorem ipsum dolor sit amet, " * 10
-
-# Create various styles
-SIMPLE_STYLE = TIntMe::Style.new(foreground: :red)
-COMPLEX_STYLE = TIntMe::Style.new(
-  foreground: :blue,
-  background: :yellow,
-  bold: true,
-  italic: true,
-  underline: true
-)
-HEX_STYLE = TIntMe::Style.new(
-  foreground: "#FF6B35",
-  background: "#F7931E",
-  bold: true,
-  overline: true
-)
-
-puts "=" * 60
-puts "TIntMe Style Performance Benchmark"
-puts "=" * 60
-puts
-
-# Memory benchmark
-puts "Memory Usage Analysis:"
-puts "-" * 40
-Benchmark.memory do |x|
-  x.report("Create simple style") do
-    TIntMe::Style.new(foreground: :red)
-  end
-
-  x.report("Create complex style") do
-    TIntMe::Style.new(
-      foreground: :blue,
-      background: :yellow,
-      bold: true,
-      italic: true,
-      underline: true,
-      overline: true,
-      blink: true
-    )
-  end
-
-  x.report("Apply simple style (short text)") do
-    SIMPLE_STYLE.call(SHORT_TEXT)
-  end
-
-  x.report("Apply complex style (short text)") do
-    COMPLEX_STYLE.call(SHORT_TEXT)
-  end
-
-  x.compare!
-end
-
-puts
-puts "Performance Benchmark (operations per second):"
-puts "-" * 40
-
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  # Style creation benchmarks
-  x.report("Create simple style") do
-    TIntMe::Style.new(foreground: :red)
-  end
-
-  x.report("Create complex style") do
-    TIntMe::Style.new(
-      foreground: :blue,
-      background: :yellow,
-      bold: true,
-      italic: true,
-      underline: true
-    )
-  end
-
-  # Style application benchmarks
-  x.report("Apply simple style (short)") do
-    SIMPLE_STYLE.call(SHORT_TEXT)
-  end
-
-  x.report("Apply simple style (medium)") do
-    SIMPLE_STYLE.call(MEDIUM_TEXT)
-  end
-
-  x.report("Apply simple style (long)") do
-    SIMPLE_STYLE.call(LONG_TEXT)
-  end
-
-  x.report("Apply complex style (short)") do
-    COMPLEX_STYLE.call(SHORT_TEXT)
-  end
-
-  x.report("Apply complex style (medium)") do
-    COMPLEX_STYLE.call(MEDIUM_TEXT)
-  end
-
-  x.report("Apply complex style (long)") do
-    COMPLEX_STYLE.call(LONG_TEXT)
-  end
-
-  x.report("Apply hex style (short)") do
-    HEX_STYLE.call(SHORT_TEXT)
-  end
-
-  x.compare!
-end
-
-# Repeated application benchmark
-puts
-puts "Repeated Application Benchmark:"
-puts "-" * 40
-puts "Applying the same style 1000 times to measure caching benefit..."
-
-styles = [SIMPLE_STYLE, COMPLEX_STYLE, HEX_STYLE]
-style_names = %w[simple complex hex]
-
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  styles.zip(style_names).each do |style, name|
-    x.report("1000x #{name} style") do
-      1000.times { style.call(SHORT_TEXT) }
-    end
-  end
-
-  x.compare!
-end
-
-# Object allocation tracking
-puts
-puts "Object Allocation Analysis:"
-puts "-" * 40
-
-# Counts object allocations during block execution
-# @return [Integer] Number of objects allocated
-def count_allocations
-  before = GC.stat[:total_allocated_objects]
-  yield
-  after = GC.stat[:total_allocated_objects]
-  after - before
-end
-
-# Measure allocations for different operations
-operations = {
-  "Create simple style" => -> { TIntMe::Style.new(foreground: :red) },
-  "Create complex style" => -> {
-    TIntMe::Style.new(
-      foreground: :blue,
-      background: :yellow,
-      bold: true,
-      italic: true,
-      underline: true
-    )
-  },
-  "Apply simple style 100x" => -> { 100.times { SIMPLE_STYLE.call(SHORT_TEXT) } },
-  "Apply complex style 100x" => -> { 100.times { COMPLEX_STYLE.call(SHORT_TEXT) } }
-}
-
-operations.each do |name, operation|
-  GC.start
-  allocations = count_allocations(&operation)
-  puts "#{name}: #{allocations} objects allocated"
-end
-
-puts
-puts "=" * 60
-puts "Benchmark complete!"
-puts "=" * 60