Owned vs Borrowed API Design

In this lesson, you will learn how to decide whether your functions should demand ownership of data or accept a temporary borrow, balancing API flexibility with performance.

The Architect’s Choice

When designing a function, you often face a crossroads: do you ask the caller to give you the data (taking ownership), or do you ask the caller to let you peek at it (borrowing)?

Taking Ownership (T)

Taking ownership is appropriate when your function needs to transform, store, or destroy the data. By taking ownership, you gain full control, but you force the caller to "give up" their copy. If the caller needed that data later, they must clone it before calling your function, which can be expensive.

fn process_string(s: String) {
    // We own 's', we can modify or drop it freely.
    println!("Processing: {}", s);
}

Borrowing (&T)

Borrowing is the "gentle" approach. It is ideal for functions that only need to read data or compute a result from it. This is usually the default choice because it avoids unnecessary allocations.

fn inspect_string(s: &str) {
    // We only read 's', leaving the caller's instance intact.
    println!("Inspecting: {}", s);
}

Finding the Balance

To make your API ergonomic, consider these heuristics:

1. Prefer borrowing for read-only tasks: It allows callers to pass in references without worrying about losing their data.
2. Accept ownership for transformation: If you are building a new data structure from an input, taking ownership allows you to move the data rather than cloning it, which is significantly faster.
3. Use Into<T> for ultimate flexibility: You can write a function that accepts impl Into<String>. This allows the caller to pass either a &str (which the function clones) or a String (which the function consumes), letting them decide the performance trade-off.

Ultimately, your API design dictates the lifecycle of data in your program. If you take ownership, you define the "end" of an object's life. If you borrow, you extend its utility without demanding the caller relinquish control.

Key Takeaway: Design your APIs to borrow by default for maximum performance, and reserve ownership for scenarios where you need to transform, store, or consume the input data.