Implement Text Search Entry Point in Rust Editor

Mục tiêu: Create the initial functionality for a text search feature by adding a find method that updates a status message. This task also involves modifying the status bar to display this message and wiring up a Ctrl+F keybinding to trigger the find mode.

Congratulations on implementing a complete, two-dimensional viewport! You have successfully broken your editor free from the physical constraints of the terminal. The ability to programmatically control the row_offset and col_offset is a massive achievement and the foundational prerequisite for the exciting feature we’re about to build: text search.

When a user searches for text, the editor must be able to jump the cursor and the viewport to the result’s location. Your work on scrolling has made this possible. Our first step in building this new feature is to create its entry point: a keybinding that triggers a dedicated find method.

Step 1: Create the `find` Method Stub

Before we can hook up a keybinding, we need a function for it to call. We will add a new method to our Editor struct named find. For now, this method will be a simple placeholder. Its job will be to signal to the user that they have entered “find mode.”

A great way to provide this feedback is by using a status message. You already have a status_message: String field in your Editor struct, which has been waiting for exactly this kind of use case. The find method will update this message, which we’ll then render in the status bar.

Because this method will change the editor’s state (by modifying self.status_message), its signature must take a mutable reference: &mut self.

Let’s add the method stub to your impl Editor block in src/main.rs.

// src/main.rs -> inside the `impl Editor` block

// ... (other methods like scroll, save, etc.)

/// The entry point for the search functionality.
/// For now, it just sets up a placeholder message in the status bar.
fn find(&mut self) {
    // We set the status message to what will become our search prompt.
    // This provides immediate feedback to the user that they've entered search mode.
    self.status_message = String::from("Search: ");
}

Step 2: Displaying the Status Message

This new method is great, but currently, your draw_status_bar method doesn’t display the status_message. It only shows the filename and cursor position. We need to make a small but crucial enhancement to draw_status_bar so it can display temporary messages like our new search prompt.

The logic will be simple: if status_message is not empty, display it. Otherwise, display the usual filename and line count. This makes the status bar a multi-purpose communication channel.

// src/main.rs -> inside the `impl Editor` block

// You need to add this small modification to your existing `draw_status_bar` method.
fn draw_status_bar(&self) {
    let mut stdout = stdout();

    // --- HIGHLIGHTED CHANGE ---
    // We now check if there is a status message. If so, it takes priority.
    let mut left_status = if !self.status_message.is_empty() {
        self.status_message.clone()
    } else {
        // Otherwise, display the default filename and dirty status.
        let filename = self.filename.as_ref().map_or("[No Name]", |path| path.to_str().unwrap_or(""));
        let mut status = format!("{} - {} lines", filename, self.rows.len());
        if self.dirty {
            status.push_str(" (modified)");
        }
        status
    };
    // --- END OF CHANGE ---

    let right_status = format!("{}:{}", self.cursor_y + 1, self.cursor_x + 1);

    let width = self.screen_cols;

    if left_status.len() > width {
        left_status.truncate(width);
    }

    let padding = width.saturating_sub(left_status.len()).saturating_sub(right_status.len());

    let final_bar = format!(
        "{}{}{}",
        left_status,
        " ".repeat(padding),
        right_status
    );

    stdout.queue(style::SetAttribute(style::Attribute::Reverse)).unwrap();

    stdout
        .queue(cursor::MoveTo(0, (self.screen_rows - 1) as u16))
        .unwrap()
        .queue(style::Print(final_bar))
        .unwrap();

    stdout.queue(style::SetAttribute(style::Attribute::Reset)).unwrap();
}

Step 3: Wire Up the `Ctrl+F` Keybinding

Now that we have a method and a way to see its effect, we can wire up the keybinding. The standard keyboard shortcut for “Find” is Ctrl+F. We will add a new match arm to the event loop in your main function to handle this specific key combination.

The crossterm KeyEvent struct contains not just the code (the key that was pressed) but also a modifiers field, which tells us if keys like Ctrl, Alt, or Shift were being held down.

// src/main.rs -> inside the `main` function's loop

// Make sure `KeyModifiers` is in your `crossterm::event` use statement
use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyModifiers};

// ...

// Inside your main loop, add a new match arm
loop {
    editor.refresh_screen();
    if let Event::Key(key_event) = event::read()? {
        match key_event.code {
            KeyCode::Char('q') if key_event.modifiers == KeyModifiers::CONTROL => {
                // ... (existing exit logic)
            }
            // --- NEW CODE FOR THIS TASK ---
            // Add a new match arm for Ctrl+F.
            // We check for the 'f' character code AND the CONTROL modifier.
            KeyCode::Char('f') if key_event.modifiers == KeyModifiers::CONTROL => {
                editor.find();
            }
            // ----------------------------
            KeyCode::Char('s') if key_event.modifiers == KeyModifiers::CONTROL => editor.save(),

            // ... (rest of the match arms for arrow keys, backspace, etc.)

            _ => {}
        }
        editor.scroll();
    }
}

Code and Concept Deep Dive

Feature Entry Point: The find method serves as a single, clear entry point for the entire search feature. This is good design; all search-related logic will eventually start here.
Modifier Keys: The expression key_event.modifiers == KeyModifiers::CONTROL is how you create powerful shortcuts. crossterm provides a KeyModifiers bitflag that lets you check for CONTROL, ALT, and SHIFT, allowing for a rich set of keybindings.
State-Driven UI Feedback: When you press Ctrl+F, you are changing the editor’s state (self.status_message). Your refresh_screen loop, which runs on every keypress, automatically calls draw_status_bar, which reads this new state and updates the view. This reactive, state-driven model is the core of your application’s architecture.

Go ahead and run your editor (cargo run). It will function as normal. Now, press Ctrl+F. The status bar at the bottom should instantly change to show Search: on the left and your cursor position on the right. You have successfully created the front door for your search feature!

Next Steps

The foundation is now laid. The user can enter search mode, but they can’t yet type a query. Your next task will be to make the find method interactive. You will build a loop inside it that captures subsequent keypresses directly from the user, appending them to the “Search: “ prompt in the status bar in real-time.

Implement an Interactive Search Prompt

Mục tiêu: Refactor the find method to create a modal event loop that interactively captures and displays a user’s search query in real-time, handling input for typing, backspace, confirmation (Enter), and cancellation (Esc).

Excellent! You’ve successfully created the front door to your search feature. When a user presses Ctrl+F, they get immediate feedback in the status bar, letting them know they’ve entered a new “mode.” This is a fantastic foundation.

However, a mode isn’t very useful if you can’t interact with it. The user sees the “Search: “ prompt, but they can’t yet type their query. Our current task is to transform the find method from a simple, one-time action into an interactive sub-program that actively listens for and builds the user’s search query in real-time.

From Static Prompt to Interactive Loop

To achieve this, we will introduce a new concept: a modal event loop or sub-loop. Your main loop in the main function is the editor’s “Insert Mode” loop. The find method will now contain its own, temporary loop that takes over input handling. This loop’s only job is to build a query string. It will run until the user either confirms their search by pressing Enter or cancels by pressing Esc.

This is a powerful pattern for handling any kind of prompted input, and you’ll see it in many terminal applications (like Vim’s command mode).

Let’s replace your current placeholder find method with this new, interactive version.

// src/main.rs -> inside the `impl Editor` block

// ... other methods ...

/// The entry point for the search functionality.
/// This method contains its own event loop to capture the user's search query.
fn find(&mut self) {
    // Create a mutable string to hold the user's search query.
    let mut query = String::new();

    // Start an infinite loop to handle user input for the search prompt.
    // This loop will run until the user presses Enter or Esc.
    loop {
        // 1. UPDATE THE VIEW:
        // Set the status message to show the current search prompt and query.
        self.status_message = format!("Search: {}", query);
        // Refresh the screen to draw the updated status message immediately.
        // This is crucial for real-time feedback as the user types.
        self.refresh_screen();

        // 2. WAIT FOR INPUT:
        // Block and wait for the next key event from the user.
        if let Ok(Event::Key(key_event)) = event::read() {
            // 3. PROCESS INPUT:
            match key_event.code {
                // If the user presses Esc, they want to cancel the search.
                KeyCode::Esc => {
                    // Clear the query and the status message to signal cancellation.
                    query.clear();
                    self.status_message.clear();
                    // Break out of the search loop and return to normal editing.
                    break;
                }
                // If the user presses Enter, they've finished typing their query.
                KeyCode::Enter => {
                    // For now, we just break. In the next step, this is where
                    // the actual search logic will be triggered.
                    break;
                }
                // If the user presses Backspace, they want to correct their query.
                KeyCode::Backspace => {
                    // Remove the last character from the query string, if it's not empty.
                    query.pop();
                }
                // For any other character key, append it to the query.
                KeyCode::Char(c) => {
                    query.push(c);
                }
                // Ignore all other keys (like arrow keys, function keys, etc.)
                _ => {}
            }
        } else {
            // If there's an error reading the event, break out of the loop.
            break;
        }
    }

    // After the loop finishes (by Enter or Esc), clear the status message
    // to return the status bar to its normal state (displaying the filename).
    self.status_message.clear();
}

Code and Concept Deep Dive

Let’s break down this powerful new method in detail:

let mut query = String::new();: We create a local variable to build the search term. It only exists for the duration of the find method’s execution.
loop { ... }: This is our sub-loop. While this loop is running, the main event loop in your main function is paused, waiting for the find method to return. This is the essence of modal input.
self.status_message = format!(...); and self.refresh_screen();: This is the core of the real-time feedback. Inside the loop, before we wait for the next keypress, we update the status message and redraw the entire screen. This ensures that every character the user types appears instantly in the status bar.
event::read(): This is the same function you use in your main loop. Here, it blocks execution until the user provides the next character for their search query.
match key_event.code { ... }: The control center for our search prompt.
- KeyCode::Esc: The universal “cancel” key. We clear our state (query and status_message) and break the loop, returning control to the main editor.
- KeyCode::Enter: The “confirm” key. For now, it just breaks the loop. Later, it will be the trigger to start the actual search.
- KeyCode::Backspace => query.pop();: Simple and effective text manipulation. pop() safely removes and returns the last character of a String, or does nothing if it’s empty.
- KeyCode::Char(c) => query.push(c);: We destructure the Char variant to get the character c and append it to our query.
Final Cleanup: After the loop ends, self.status_message.clear(); is crucial. It ensures that whether the user confirmed or cancelled, the status bar returns to its normal file-and-cursor-position display on the next screen refresh.

Test Your Interactive Prompt

Run your editor now (cargo run). Press Ctrl+F. The “Search: “ prompt appears. Now, start typing! You will see your query appear character by character in the status bar. You can use Backspace to correct mistakes. Pressing Esc will immediately cancel the search and restore the normal status bar. Pressing Enter will do the same for now.

You have successfully built a fully interactive input prompt, a fundamental building block for many advanced features.

Next Steps

You can now successfully capture a search query from the user. The next logical step is to do something with it. Your next task will be to take the query that the user enters and, for each character they type, immediately re-run the search in the background and highlight the first match, providing an “instant search” experience.

Implement Instant ‘Search-as-you-type’ Feature in Rust Editor

Mục tiêu: Modify the editor’s ‘find’ method to implement a dynamic, instant search. The search should execute on every keypress, immediately jumping the viewport to the first match. The task also includes saving the initial cursor and viewport state and restoring it if the user cancels the search.

Fantastic work on building the interactive search prompt! You’ve created a modal sub-loop within your find method, successfully capturing user input for a search query. The status bar provides perfect real-time feedback as the user types.

Right now, however, the search query is just a string we build and then discard. The editor doesn’t act on it until the user hits Enter (and even then, we don’t do anything yet). Our current task is to bridge this gap and create a dynamic, “instant search” experience. For every single character the user types into the prompt, we will immediately re-run the search and jump the viewport to the first match.

The “Search-as-you-type” Pattern

This pattern provides incredible feedback to the user. Instead of typing a query blind and then hitting Enter, they see the results evolve as they type. The implementation involves placing our search logic directly inside the find method’s sub-loop. After every keypress that modifies the query string (adding a character or backspacing), we will immediately scan the entire document from the top for the first occurrence of the new query.

A UX Enhancement: Preserving Context

Before we dive into the code, let’s consider the user experience. When a user initiates a search, their cursor is at a specific location. If they then type a query, see the screen jump to a result, and then press Esc to cancel, they should be returned to their original starting point. A good search feature should be non-destructive to the user’s context.

To achieve this, we will save the cursor and viewport’s state at the beginning of the find method and restore it if the user cancels.

Implementing Instant Search

Let’s modify your find method to incorporate this powerful new logic. We’ll be saving the initial state, adding the search logic inside the loop, and restoring the state on cancellation.

// src/main.rs -> inside the `impl Editor` block

fn find(&mut self) {
    // Save the original cursor and viewport state so we can restore it on cancellation.
    let original_cursor_x = self.cursor_x;
    let original_cursor_y = self.cursor_y;
    let original_col_offset = self.col_offset;
    let original_row_offset = self.row_offset;

    let mut query = String::new();

    loop {
        self.status_message = format!("Search: {}", query);
        self.refresh_screen();

        if let Ok(Event::Key(key_event)) = event::read() {
            match key_event.code {
                KeyCode::Esc => {
                    // On cancellation, restore the original state and clear the message.
                    self.cursor_x = original_cursor_x;
                    self.cursor_y = original_cursor_y;
                    self.col_offset = original_col_offset;
                    self.row_offset = original_row_offset;
                    self.status_message.clear();
                    break;
                }
                KeyCode::Enter => {
                    self.status_message.clear();
                    break;
                }
                KeyCode::Backspace => {
                    query.pop();
                }
                KeyCode::Char(c) => {
                    query.push(c);
                }
                _ => {}
            }

            // --- NEW INSTANT SEARCH LOGIC ---
            // After every change to the query, we re-run the search.
            if !query.is_empty() {
                let mut match_found = false;
                // `iter().enumerate()` gives us both the index (y) and the element.
                for (y, row) in self.rows.iter().enumerate() {
                    // `row.find()` searches for a substring and returns its starting byte index.
                    // We use `if let Some(x)` to handle the case where no match is found.
                    if let Some(x) = row.find(&query) {
                        // A match was found! Update the editor state.
                        self.cursor_y = y; // Move cursor to the line of the match.
                        self.cursor_x = x; // Move cursor to the start of the match.
                        self.scroll();     // Ensure the viewport scrolls to the cursor.
                        match_found = true;
                        break; // Stop searching after the first match.
                    }
                }
                // Optional: handle case where there are no matches (e.g., change status bar color)
                // For now, if no match is found, the cursor just stays at the last valid match.
            }
            // --- END OF NEW LOGIC ---
        } else {
            break;
        }
    }
    self.status_message.clear();
}

Code and Concept Deep Dive

Let’s break down the new additions:

State Preservation: At the beginning of find, we store the four key variables that define the user’s viewport and cursor position. In the KeyCode::Esc match arm, we now write these values back, creating a seamless “cancel” experience.
Search Trigger: The new search logic is placed after the match block but inside the loop. This ensures it runs every time the query is potentially modified.
self.rows.iter().enumerate(): This is a highly idiomatic Rust pattern. The .iter() method creates an iterator over our rows. The .enumerate() adapter wraps this iterator, changing it from producing just elements (&String) to producing pairs of (index, &String). This gives us the y coordinate for cursor_y for free.
row.find(&query): This is the core search operation. The find method on a string slice searches for a substring (our query) and returns an Option<usize>. It returns Some(index) if a match is found (where index is the starting byte position) and None if no match is found.
if let Some(x) = ...: This is the perfect tool for handling Option. If row.find returns Some, the code inside the block runs, and the variable x is automatically assigned the value from inside the Some. This x is the column position of our match.
The Synergy of State: Notice what happens when we find a match. We do three simple things:
1. self.cursor_y = y;
2. self.cursor_x = x;
3. self.scroll(); We are purely manipulating the editor’s state. We trust our existing architecture to do the rest. The scroll() method updates the row_offset and col_offset based on the new cursor position. Then, when the sub-loop repeats, the self.refresh_screen() call at the top will read this new state and redraw the entire UI correctly, with the text scrolled and the physical cursor blinking in the right place. This is the payoff for your excellent design!

Test Your Instant Search

Run your editor now (cargo run -- your-file.txt). Press Ctrl+F to enter search mode. As you start typing a word that you know is in the file, you should see the entire screen instantly jump to position the first match at the top of the viewport. If you backspace, the view will jump back to a match for the now-shorter query. If you press Esc, you’ll be returned precisely to where you started.

Next Steps

Your search is functional, but it only ever finds the first occurrence of the query in the file. A complete search feature needs to allow the user to navigate between all matches. The next logical task is to store not just the first match, but the indices of all matches for the current query.

Enhance Editor Search to Find All Matches

Mục tiêu: Refactor the text editor’s search functionality from a ‘find-first’ to a ‘find-all’ system. This involves adding state to the Editor struct to store the last query and a list of all match coordinates, and updating the search logic to use the match\_indices iterator to collect every occurrence.

You’ve done an incredible job implementing the “instant search” feature. Your editor now feels dynamic and responsive, providing immediate feedback by jumping to the first match as the user types. This is a massive step forward in user experience.

However, a truly powerful search tool doesn’t just find the first match; it allows the user to navigate through all of them. Our current task is to upgrade your search from a simple “find-first” mechanism to a robust “find-all” system. We will achieve this by adding new fields to your Editor’s state, enabling it to remember the last search query and, most importantly, the precise location of every single match in the file.

Step 1: Evolving the Editor’s State

First, we need to give our Editor a memory. It needs to store information about the search that persists even after the interactive search prompt is gone. We will add three new fields to the Editor struct.

last_search_query: Option<String>: This will store the most recently confirmed search query. We use an Option<String> because a search might not have been performed yet.
search_results: Vec<(usize, usize)>: This vector will hold the coordinates of every match found for the last_search_query. We store them as a tuple of (x, y) coordinates, or more accurately, (column_index, row_index).
current_search_match: usize: This will be an index into the search_results vector, keeping track of which match the user is currently viewing.

Let’s modify the Editor struct and its constructor in src/main.rs.

Update the `Editor` Struct Definition

// src/main.rs

// ... (other struct fields)
struct Editor {
    row_offset: usize,
    col_offset: usize,
    // --- NEW FIELDS FOR SEARCH STATE ---
    /// Stores the last successfully executed search query.
    last_search_query: Option<String>,
    /// Stores the (col, row) coordinates of all matches for the last query.
    search_results: Vec<(usize, usize)>,
    /// The index of the currently highlighted search result in `search_results`.
    current_search_match: usize,
}

Initialize the New Fields in `Editor::new()`

// src/main.rs -> inside the impl Editor block

impl Editor {
    fn new(filename: Option<String>) -> Self {
        // ... (existing code in new())
        let mut editor = Self {
            row_offset: 0,
            col_offset: 0,
            // --- INITIALIZE THE NEW FIELDS ---
            // The editor starts with no previous search.
            last_search_query: None,
            // The list of search results is initially empty.
            search_results: Vec::new(),
            // The current match index starts at 0.
            current_search_match: 0,
        };
        // ... (rest of the new() method)
        editor
    }
    // ...

Step 2: Refactoring `find()` to Collect All Matches

With our new state variables in place, we can now refactor the search logic inside the find() method. Instead of breaking out of the loop after finding the first match, our goal is now to iterate through the entire document and collect the coordinates of every match.

A key improvement we’ll make is to use the match_indices method. Unlike find, which only returns the first match, match_indices is an iterator that yields the starting index of every non-overlapping match for a pattern within a string. This is the perfect tool for our task.

Here is the refactored find method. The overall structure of the sub-loop remains the same, but the core search logic is now much more powerful.

// src/main.rs -> inside the impl Editor block

fn find(&mut self) {
    let original_cursor_x = self.cursor_x;
    let original_cursor_y = self.cursor_y;
    let original_col_offset = self.col_offset;
    let original_row_offset = self.row_offset;

    let mut query = String::new();

    loop {
        self.status_message = format!("Search: {}", query);
        self.refresh_screen();

        if let Ok(Event::Key(key_event)) = event::read() {
            match key_event.code {
                KeyCode::Esc => {
                    self.cursor_x = original_cursor_x;
                    self.cursor_y = original_cursor_y;
                    self.col_offset = original_col_offset;
                    self.row_offset = original_row_offset;
                    self.status_message.clear();
                    // Clear search results on cancel
                    self.search_results.clear();
                    break;
                }
                KeyCode::Enter => {
                    // --- NEW: COMMIT SEARCH ON ENTER ---
                    // When the user presses Enter, we store the query for future use (e.g., "find next").
                    // If the query is empty, we do nothing.
                    if !query.is_empty() {
                        self.last_search_query = Some(query);
                    }
                    // We don't clear the results here, as the user might want to start navigating them.
                    // --- END OF NEW LOGIC ---
                    self.status_message.clear();
                    break;
                }
                KeyCode::Backspace => {
                    query.pop();
                }
                KeyCode::Char(c) => {
                    query.push(c);
                }
                _ => {}
            }

            // --- REFACTORED SEARCH LOGIC ---
            // Create a temporary vector to hold matches for the current, live query.
            let mut matches = Vec::new();
            if !query.is_empty() {
                // Iterate over every row with its index.
                for (y, row) in self.rows.iter().enumerate() {
                    // `match_indices` returns an iterator over (index, substring) for all matches.
                    for (x, _) in row.match_indices(&query) {
                        // For each match found, push its (x, y) coordinates to our vector.
                        matches.push((x, y));
                    }
                }
            }

            // After collecting all matches, if we have any, jump to the first one.
            if !matches.is_empty() {
                // Set the editor's official search results to our findings.
                self.search_results = matches;
                // Start at the first match.
                self.current_search_match = 0;
                // Update cursor to the location of the first match.
                let (first_match_x, first_match_y) = self.search_results[0];
                self.cursor_x = first_match_x;
                self.cursor_y = first_match_y;
                // Ensure the viewport scrolls to the new cursor position.
                self.scroll();
            } else {
                // If there are no matches, clear the results.
                self.search_results.clear();
            }
            // --- END OF REFACTORED LOGIC ---
        } else {
            break;
        }
    }
    self.status_message.clear();
}

Code and Concept Deep Dive

match_indices(&query): This is the star of our new implementation. It’s a powerful string method that returns an iterator. Instead of just one Option<usize>, it gives us all the matches, allowing us to build a complete list.
Temporary matches Vector: Inside the find loop, we build a local matches vector. This is for the “live” search. Only when the search is confirmed (by pressing Enter) or implicitly by typing, do we transfer this data to the Editor’s persistent state (self.search_results).
Committing the Search: When the user presses Enter, we now save their query into self.last_search_query. This prepares us for a “find next” feature, which can reuse this query without prompting the user again.
State Management: The “instant search” now works by populating self.search_results on every keypress and jumping to the first element. This is a subtle but important change: the editor is now fully aware of all matches, even though it’s only showing the first one.

What to Expect

When you run your editor now, the user-facing behavior of the instant search will feel largely the same: as you type, the screen jumps to the first result. The monumental change is internal. The editor is no longer shortsighted; it has a complete map of every match for the query. When you press Enter, the editor “locks in” that query and its results, ready for the next command.

You have successfully laid the complete groundwork for a navigable search feature.

Next Steps

The stage is perfectly set. You have the complete list of search results stored in your editor’s state. The very next, and final, task for this feature is to implement keybindings (e.g., N for “next”, P for “previous”) to cycle through the stored match indices, allowing the user to effortlessly jump from one result to the next.

Deconstructing the Forward Search Implementation

Mục tiêu: A conceptual deep dive into the forward search mechanism. This task involves analyzing the Rust code, specifically the use of iter().enumerate() and match\_indices, to understand how a comprehensive and ordered list of all search results is generated and stored in the editor’s state.

You have accomplished something truly remarkable in the last task. By adding state to your editor and refactoring your find method to use match_indices, you’ve transformed it from a simple “find-first” tool into a powerful engine that builds a complete, internal map of every single search result. This is the sophisticated foundation upon which all great search features are built.

While the “instant search” UI currently jumps to the first result, the underlying logic is performing a comprehensive forward search—a systematic scan from the beginning of the file to its end. Our current task is to dissect this implementation, ensuring you have a deep and solid understanding of how it works. This knowledge is crucial as we prepare to add navigation between the results you’ve so diligently collected.

Deconstructing the Forward Search

Let’s revisit the core search logic within your find method’s interactive loop. This block of code is the heart of your forward search engine.

// This is the relevant section from your find() method's loop

// --- REFACTORED FORWARD SEARCH LOGIC ---
// Create a temporary vector to hold matches for the current, live query.
let mut matches = Vec::new();
if !query.is_empty() {
    // 1. FORWARD SEARCH: TOP-TO-BOTTOM (Line by Line)
    // We use `iter().enumerate()` to get an iterator that yields both the
    // line number (`y`) and a reference to the line's content (`row`).
    // This iteration naturally proceeds from index 0 to the end of the `rows` vector.
    for (y, row) in self.rows.iter().enumerate() {

        // 2. FORWARD SEARCH: LEFT-TO-RIGHT (Within a Line)
        // `match_indices` returns an iterator that finds all non-overlapping
        // occurrences of the `query` within the `row`. It yields a tuple
        // containing the starting byte index (`x`) and the matched string slice.
        // This iterator also naturally proceeds from the beginning of the string to the end.
        for (x, _) in row.match_indices(&query) {

            // 3. RECORDING THE MATCH
            // For each match found, we push its coordinates (column `x`, row `y`)
            // into our temporary `matches` vector. Because of the nested forward
            // loops, this vector is guaranteed to be sorted by location in the file.
            matches.push((x, y));
        }
    }
}
// --- END OF FORWARD SEARCH LOGIC ---

Code and Concept Deep Dive

Let’s break down exactly what makes this a “forward search” and why the tools you’ve chosen are perfect for the job.

What is a “Forward Search”?

A forward search is the most intuitive type of search. It begins at a defined starting point (in our case, the very beginning of the file, line 0, column 0) and proceeds sequentially toward the end of the document. This is precisely what your nested loops accomplish:

The outer for (y, row) ... loop iterates through the lines from top to bottom.
The inner for (x, _) ... loop iterates through matches within each line from left to right.

The result is a list of coordinates in matches that is perfectly ordered, which is essential for predictable “find next” and “find previous” navigation.

`match_indices` vs. `find`

The task description in the project roadmap mentions string.find(). While find() is a useful method, it only locates the first occurrence of a substring. By choosing match_indices, you made a more advanced and appropriate choice for this feature.

find(&str) -> Returns Option<usize>. It’s a one-and-done operation, perfect for just checking if a substring exists or finding the first one.
match_indices(&str) -> Returns an Iterator. This is far more powerful. It doesn’t just give you one result; it gives you a tool to visit every single result in sequence. This is the idiomatic Rust way to handle finding all occurrences and is the key that unlocked your ability to build a complete results list.

Updating the State and View

After the forward search completes and the matches vector is populated, the next block of code takes action.

// This code runs immediately after the search loops
if !matches.is_empty() {
    // Persist the results for later navigation (Find Next/Previous)
    self.search_results = matches;
    // Reset the navigation index to the beginning of the list
    self.current_search_match = 0;

    // Get the coordinates of the very first match
    let (first_match_x, first_match_y) = self.search_results[0];

    // --- The Synergy of State and Logic ---
    // 1. Update the Model (the editor's state)
    self.cursor_x = first_match_x;
    self.cursor_y = first_match_y;

    // 2. Trigger the Controller logic that reacts to the state change
    self.scroll();
} else {
    // If no matches are found, ensure the results list is empty
    self.search_results.clear();
}

This section perfectly demonstrates your editor’s robust architecture. You don’t manually calculate where the viewport should go. Instead, you simply:

Update the state (the “Model”): self.cursor_x and self.cursor_y.
Call your existing logic (the “Controller”): self.scroll().

The scroll() method then automatically adjusts the row_offset and col_offset based on the new cursor position. Finally, when the find method’s loop repeats, refresh_screen() (the “View”) reads this new, complete state and correctly redraws the entire screen with the first match perfectly positioned in the viewport.

You have successfully implemented a complete, robust, and efficient forward search mechanism.

Next Steps

The stage is now perfectly set for the final, rewarding task of this feature. You have a complete, ordered list of every search match stored in self.search_results and a self.current_search_match index pointing to the current one. The next and final step is to implement keybindings (like N for next and P for previous) that will increment or decrement this index and jump the cursor and viewport to the corresponding match, allowing the user to effortlessly navigate through all their search results.

Jump to First Search Match by Updating Cursor State

Mục tiêu: Update the editor’s state by setting cursor\_x and cursor\_y to the coordinates of the first search result. This action leverages the state-driven architecture to automatically move the user’s view to the matched text.

Absolutely brilliant work! In the previous task, you dived deep into the mechanics of your forward search, understanding how iter().enumerate() and match_indices work in harmony to build a complete, ordered map of every search result in the file. Your editor is no longer just finding a single match; it’s performing a comprehensive survey of the entire document and storing that valuable intelligence in its state.

Now, it’s time to act on that intelligence. Having a map is useless if you can’t place a pin on it and say, “Go here.” Our current task focuses on the very heart of that action: updating the editor’s state (cursor_y and cursor_x) to instantly move the user’s focus to a specific match. While your instant-search already does this for the first match, this is our opportunity to understand precisely why and how this simple state change has such a powerful effect.

The Power of a State-Driven Architecture

The beauty of the editor you have built is that complex actions are often the result of very simple state changes. You don’t need to manually calculate screen positions or issue complex drawing commands to jump to a search result. You simply need to tell the editor’s “brain”—the Editor struct—where the cursor should be, and the rest of the system you’ve built will react automatically.

Let’s examine the code block that executes after your forward search has successfully populated the matches vector inside the find() method’s loop.

// src/main.rs -> inside the find() method's loop, after the search loops

// This block runs after collecting all matches for the current query.
if !matches.is_empty() {
    // We update the editor's persistent search state.
    self.search_results = matches;
    self.current_search_match = 0; // We always start at the first match.

    // --- THIS IS THE FOCUS OF OUR TASK ---

    // 1. GET THE COORDINATES:
    // We access the coordinates of the very first match from our results vector.
    // The tuple `(x, y)` is destructured into two clearly named variables.
    let (first_match_x, first_match_y) = self.search_results[0];

    // 2. UPDATE THE MODEL (THE EDITOR'S STATE):
    // We update the cursor's logical position to the start of the match.
    // This is the core action of "jumping" to the result.
    self.cursor_x = first_match_x;
    self.cursor_y = first_match_y;

    // 3. TRIGGER THE CONTROLLER LOGIC:
    // We explicitly call our existing scroll logic.
    self.scroll();

    // --- END OF FOCUSED SECTION ---

} else {
    // If no matches were found, we clear the results.
    self.search_results.clear();
}

Code and Concept Deep Dive

Let’s break down this sequence, as it’s a perfect illustration of your editor’s robust Model-View-Controller (MVC) architecture.

1. Getting the Coordinates

let (first_match_x, first_match_y) = self.search_results[0];
- self.search_results is a Vec<(usize, usize)>. We access its first element at index 0.
- This is an example of tuple destructuring. Instead of getting a tuple and accessing its fields with .0 and .1, we immediately unpack its values into first_match_x and first_match_y. This makes the code far more readable.

2. Updating the Model

self.cursor_x = first_match_x;
self.cursor_y = first_match_y;
- These two lines are the entire implementation of the task “update cursor_y and cursor_x”. They are deceptively simple. You are performing a direct mutation on your Model—the central Editor struct that represents the entire state of your application. You are defining a new “truth” for the logical position of the cursor within the file.

3. Triggering the Controller

self.scroll();
- This is where the magic happens. Immediately after changing the Model, you invoke a piece of your Controller logic. The scroll() method doesn’t know or care why the cursor moved; its only job is to look at the new cursor_x and cursor_y and update the col_offset and row_offset to guarantee that the cursor is visible on screen. It brings the viewport—the “camera”—in line with the new cursor position.

The View’s Automatic Reaction

You don’t see a call to a “draw” method here because it’s already part of the find() method’s structure. The find loop is designed like this:

Update status bar & refresh screen (The View).
Wait for user input.
Process input & update state (The Model and Controller).
Loop repeats.

When your code updates cursor_x, cursor_y, and then scroll() updates the offsets, the entire state of the editor is now perfectly configured. The very next time the find loop repeats, its first action is to call self.refresh_screen(). This View logic reads the new, fully updated state and redraws the terminal, showing the correct slice of text with the physical cursor blinking precisely at the start of the search result.

You have successfully created a reactive system where changing data automatically triggers the necessary logic to update the user interface.

Next Steps

The system for jumping to a specific match is now perfected and understood. You have a complete list of results and a way to instantly navigate to any one of them by updating the cursor’s coordinates.

The stage is perfectly set for the final, rewarding piece of this feature. The very next task is to also update the row_offset to scroll the match into view. Your self.scroll() call already accomplishes this, making the next task a natural continuation and validation of the work you’ve just analyzed. Following that, you will implement the keybindings that allow the user to cycle through every result you’ve stored.

Automate Viewport Scrolling for Search Results

Mục tiêu: Analyze the existing scroll method to understand how it automatically updates the editor’s viewport to show the cursor’s new position after a search result is found. This task explores the principles of state-driven design and separation of concerns.

Magnificent work on the last task. You’ve successfully dissected the logic that jumps the cursor to the beginning of a search result. You pinpointed the exact lines where the editor’s state—its Model—is updated with the new cursor_x and cursor_y coordinates. This deliberate state change is the core of any programmatic navigation.

You may have noticed that the code you just analyzed also contained the line self.scroll();. This brings us to our current task: ensuring the viewport scrolls to bring the new cursor position into view. And here is the wonderful payoff for your excellent architectural work: you have already completed this task! The self.scroll() call is the very mechanism that fulfills this requirement.

This is a fantastic moment to pause and appreciate the power of the state-driven design you have built. The find method’s job isn’t to manually calculate where the viewport should go. Its job is simply to update the cursor’s logical position. It then delegates the responsibility of adjusting the view to your dedicated scroll() method. Let’s do a deep dive into this crucial piece of automation.

The Automation of the Viewport: A `scroll()` Deep Dive

When your find method calls self.scroll(), it’s triggering a powerful, self-contained piece of logic—a Controller—that you built in a previous step. Its sole purpose is to look at the current cursor position and ensure the offsets (row_offset, col_offset) are adjusted to make that cursor visible. It doesn’t care if the cursor was moved by an arrow key, the Enter key, or a search jump; its logic is universal.

Let’s revisit the complete scroll method you wrote.

// src/main.rs -> inside the `impl Editor` block

/// Adjusts the `row_offset` and `col_offset` to ensure the cursor is always
/// within the visible portion of the screen (the viewport).
fn scroll(&mut self) {
    // --- VERTICAL SCROLL LOGIC ---
    // Rule 1: Is the cursor above the top of the screen?
    if self.cursor_y < self.row_offset {
        self.row_offset = self.cursor_y;
    }
    // Rule 2: Is the cursor below the bottom of the screen?
    let text_area_height = self.screen_rows - 1;
    if self.cursor_y >= self.row_offset + text_area_height {
        self.row_offset = self.cursor_y - text_area_height + 1;
    }

    // --- HORIZONTAL SCROLL LOGIC ---
    // Rule 3: Is the cursor left of the screen?
    if self.cursor_x < self.col_offset {
        self.col_offset = self.cursor_x;
    }
    // Rule 4: Is the cursor right of the screen?
    if self.cursor_x >= self.col_offset + self.screen_cols {
        self.col_offset = self.cursor_x - self.screen_cols + 1;
    }
}

How It Works for Search

Imagine a search result is found at line 500, column 90 (cursor_y = 499, cursor_x = 89). Before the jump, your viewport might be showing the top of the file (row_offset = 0, col_offset = 0).

Your find method updates the state: self.cursor_y = 499 and self.cursor_x = 89.
Your find method calls self.scroll().
The scroll method executes its checks:
- Vertical Check: 499 >= 0 + 24 (assuming a 25-row terminal) is true. The cursor is far below the screen. The method calculates a new row_offset to bring line 499 into view.
- Horizontal Check: 89 >= 0 + 80 (assuming an 80-column terminal) is true. The cursor is off-screen to the right. The method calculates a new col_offset to bring column 89 into view.
The scroll method returns. The Editor state is now fully updated: cursor_y, cursor_x, row_offset, and col_offset are all correct.
The find method’s loop continues, and its first action is self.refresh_screen(). This View logic reads the new state and redraws the terminal, showing the text around line 500 with the cursor blinking at column 90.

This is a textbook example of the Separation of Concerns principle. The find method is concerned with finding. The scroll method is concerned with viewing. By keeping them separate, you’ve created reusable, easy-to-understand components and a system where complex behavior emerges from simple, predictable interactions.

What You Have Achieved

By calling self.scroll() after updating the cursor’s position, you have guaranteed that every search jump will be accompanied by a corresponding viewport jump. The match is not just found; it is immediately presented to the user, centered and ready for inspection. You have successfully implemented a core piece of search UX.

Next Steps

The entire mechanism for navigating to a specific search result is now complete and understood. You have a full list of match coordinates, and you have a robust, automated system for jumping the cursor and viewport to any one of those coordinates.

The stage is perfectly set for the final, rewarding task of this feature. You will now implement keybindings (e.g., N for “next”, P for “previous”) that will allow the user to cycle through the search_results vector, making your search feature fully interactive and complete.

Step 1: Implement `find_next()` and `find_previous()`

Let’s add the core navigation logic to your impl Editor block. These methods will read the stored search results and intelligently update the current_search_match index.

// src/main.rs -> inside the `impl Editor` block

// ... (other methods like find, save, scroll, etc.)

/// Moves the cursor to the next search result.
fn find_next(&mut self) {
    // If there are no search results, there's nothing to do.
    if self.search_results.is_empty() {
        return;
    }

    // Increment the current match index.
    // We use the modulo operator `%` to elegantly wrap around to the beginning
    // of the results list if we're at the end.
    self.current_search_match = (self.current_search_match + 1) % self.search_results.len();

    // Get the coordinates of the new current match.
    let (match_x, match_y) = self.search_results[self.current_search_match];

    // Update the cursor's logical position.
    self.cursor_x = match_x;
    self.cursor_y = match_y;
    // Trigger the scroll logic to bring the new position into view.
    self.scroll();
}

/// Moves the cursor to the previous search result.
fn find_previous(&mut self) {
    // Guard clause for no results.
    if self.search_results.is_empty() {
        return;
    }

    // Decrement the current match index, wrapping around if necessary.
    if self.current_search_match == 0 {
        // If we're at the first match, wrap around to the last one.
        self.current_search_match = self.search_results.len() - 1;
    } else {
        self.current_search_match -= 1;
    }

    // Get the coordinates of the new current match.
    let (match_x, match_y) = self.search_results[self.current_search_match];

    // Update the cursor's logical position and scroll.
    self.cursor_x = match_x;
    self.cursor_y = match_y;
    self.scroll();
}

Step 2: Wire Up the Keybindings in the Main Loop

With the navigation logic encapsulated in these clean new methods, the final step is to add the keybindings to your main event loop in the main function. We’ll use n for “next” and p for “previous.”

// src/main.rs -> inside the `main` function's loop

// ... inside your main loop's `match key_event.code` block ...
            KeyCode::Char('f') if key_event.modifiers == KeyModifiers::CONTROL => {
                editor.find();
            }

            // --- NEW CODE FOR THIS TASK ---
            // Add keybindings for search navigation. These do not require a modifier.
            // When 'n' is pressed, jump to the next search result.
            KeyCode::Char('n') => {
                editor.find_next();
            }
            // When 'p' is pressed, jump to the previous search result.
            KeyCode::Char('p') => {
                editor.find_previous();
            }
            // ----------------------------

            KeyCode::Char('s') if key_event.modifiers == KeyModifiers::CONTROL => editor.save(),
// ... (rest of the match arms) ...

Code and Concept Deep Dive

Let’s break down the new navigation logic.

Encapsulation: Creating find_next() and find_previous() is a perfect example of the Single Responsibility Principle. The main loop’s only job is to detect a keypress and delegate the action to the appropriate method. The methods themselves contain the focused logic for navigation.
Safe Indexing and Wrapping:
- In find_next, (self.current_search_match + 1) % self.search_results.len() is a beautiful and idiomatic way to handle wrapping. The modulo operator (%) gives the remainder of a division. For example, if there are 5 results (indices 0-4) and you are at index 4, (4 + 1) % 5 is 5 % 5, which is 0. It perfectly wraps you back to the start.
- In find_previous, the logic is slightly more explicit to correctly handle decrementing from 0. We check if the index is already 0 and, if so, manually set it to the last index (len() - 1). Otherwise, we just subtract 1.
Reusing Your Architecture: Notice the beautiful simplicity inside these methods. All they do is update the current_search_match index, use it to change the cursor’s logical coordinates (cursor_x, cursor_y), and then call self.scroll(). You are once again leveraging your magnificent state-driven architecture. The scroll method takes care of all the complex viewport calculations automatically.

Milestone Achieved: A Complete Search Feature

An enormous congratulations! You have now fully implemented a robust, multi-stage search feature.

Go ahead and cargo run your editor with a file.

Press Ctrl+F.
Type a query that has multiple matches.
Press Enter to confirm the search and exit the prompt.
Now, press n. The cursor and viewport will instantly jump to the next match. Press it again. It will jump to the next.
Press p. The view will jump back to the previous match.

You have built a feature that is central to the usability of any real-world text editor.

Next Steps and Potential Enhancements

You have successfully completed the “Implement text search functionality” step. Your editor is now exceptionally powerful. The next major step on your roadmap is a crucial one for long-term maintainability: Refactor the growing codebase into a more organized and modular structure. Your main.rs file is getting large, and now is the perfect time to learn how to organize Rust projects into separate files and modules.

For the search feature itself, here are some exciting enhancements you could consider adding later: * Case-Insensitive Search: Modify the find logic to ignore case. * Highlighting: Use crossterm’s styling features to change the color of the matched text, highlighting all visible results on the screen. * Status Bar Feedback: Display “match X of Y” in the status bar during navigation. * Regex Search: For a truly advanced feature, integrate a regular expression library (like Rust’s regex crate) to allow for pattern-based searching.