gradient_filled_segment_with_buffer

bubbletea_rs::gradient

Function gradient_filled_segment_with_buffer 

Source 
pub fn gradient_filled_segment_with_buffer(
    filled_width: usize,
    ch: char,
    buffer: &mut String,
) -> &str
Expand description

Creates a gradient-colored text segment using a reusable buffer for optimal performance.

This is a buffer-reusing variant of gradient_filled_segment designed for scenarios where gradient segments are generated frequently, such as animated progress bars or real-time UI updates. By reusing the same buffer, this function eliminates repeated heap allocations and improves performance in tight rendering loops.

§Arguments

  • filled_width - The number of characters to include in the gradient segment. If 0, the function clears the buffer and returns an empty string reference.
  • ch - The character to repeat for each position in the gradient (commonly ‘█’, ‘▓’, etc.)
  • buffer - A mutable reference to a String that will be cleared and used to build the gradient segment. The buffer’s capacity is preserved and extended if needed.

§Returns

A string slice (&str) reference to the buffer’s contents containing the gradient-colored characters with embedded ANSI escape sequences.

§Performance Benefits

  • No allocations: Reuses the provided buffer’s existing capacity
  • Reduced fragmentation: Avoids creating temporary strings
  • Cache efficiency: Better memory locality when used in loops
  • Optimal for animation: Perfect for 60fps+ rendering scenarios

§Examples

use bubbletea_rs::gradient::gradient_filled_segment_with_buffer;

let mut buffer = String::new();

// Simulate an animated progress bar
for progress in 0..=10 {
    let segment = gradient_filled_segment_with_buffer(progress, '█', &mut buffer);
    println!("Progress: [{}{}]", segment, " ".repeat(10 - progress));
    // Buffer is automatically reused for the next iteration
}

// The buffer retains its capacity for future use
assert!(buffer.capacity() >= 250); // Approximate capacity after 10 characters

§Usage Patterns

use bubbletea_rs::gradient::gradient_filled_segment_with_buffer;

// Pattern 1: Reuse buffer in animation loop
let mut gradient_buffer = String::new();
loop {
    let width = calculate_progress_width();
    let bar = gradient_filled_segment_with_buffer(width, '█', &mut gradient_buffer);
    render_ui_with_progress_bar(bar);
}

// Pattern 2: Multiple gradient elements with separate buffers
let mut bar_buffer = String::new();
let mut spinner_buffer = String::new();

let progress_bar = gradient_filled_segment_with_buffer(15, '█', &mut bar_buffer);
let loading_spinner = gradient_filled_segment_with_buffer(3, '▓', &mut spinner_buffer);

§Buffer Management

  • The buffer is cleared on each call but its capacity is preserved
  • If the buffer’s capacity is insufficient, it will be extended as needed
  • The buffer can be reused indefinitely across multiple calls
  • For optimal performance, pre-allocate buffer capacity if the maximum width is known

§See Also