Why is it discouraged to accept a reference &String, &Vec, or &Box as a function argument?

Question

I wrote some Rust code that takes a &String as an argument:

fn awesome_greeting(name: &String) {
    println!("Wow, you are awesome, {}!", name);
}

I've also written code that takes in a reference to a Vec or Box:

fn total_price(prices: &Vec<i32>) -> i32 {
    prices.iter().sum()
}

fn is_even(value: &Box<i32>) -> bool {
    **value % 2 == 0
}

However, I received some feedback that doing it like this isn't a good idea. Why not?

Answer 1

TL;DR: One can instead use &str, &[T] or &T to allow for more generic code.

---

1. One of the main reasons to use a String or a Vec is because they allow increasing or decreasing the capacity. However, when you accept an immutable reference, you cannot use any of those interesting methods on the Vec or String.

2. Accepting a &String, &Vec or &Box also requires the argument to be allocated on the heap before you can call the function. Accepting a &str allows a string literal (saved in the program data) and accepting a &[T] or &T allows a stack-allocated array or variable. Unnecessary allocation is a performance loss. This is usually exposed right away when you try to call these methods in a test or a main method:

   awesome_greeting(&String::from("Anna"));
   

   total_price(&vec![42, 13, 1337])
   

   is_even(&Box::new(42))
   

3. Another performance consideration is that &String, &Vec and &Box introduce an unnecessary layer of indirection as you have to dereference the &String to get a String and then perform a second dereference to end up at &str.

Instead, you should accept a string slice (&str), a slice (&[T]), or just a reference (&T). A &String, &Vec<T> or &Box<T> will be automatically coerced (via deref coercion) to a &str, &[T] or &T, respectively.

fn awesome_greeting(name: &str) {
    println!("Wow, you are awesome, {}!", name);
}

fn total_price(prices: &[i32]) -> i32 {
    prices.iter().sum()
}

fn is_even(value: &i32) -> bool {
    *value % 2 == 0
}

Now you can call these methods with a broader set of types. For example, awesome_greeting can be called with a string literal ("Anna") or an allocated String. total_price can be called with a reference to an array (&[1, 2, 3]) or an allocated Vec.

---

If you'd like to add or remove items from the String or Vec<T>, you can take a mutable reference (&mut String or &mut Vec<T>):

fn add_greeting_target(greeting: &mut String) {
    greeting.push_str("world!");
}

fn add_candy_prices(prices: &mut Vec<i32>) {
    prices.push(5);
    prices.push(25);
}

Specifically for slices, you can also accept a &mut [T] or &mut str. This allows you to mutate a specific value inside the slice, but you cannot change the number of items inside the slice (which means it's very restricted for strings):

fn reset_first_price(prices: &mut [i32]) {
    prices[0] = 0;
}

fn lowercase_first_ascii_character(s: &mut str) {
    if let Some(f) = s.get_mut(0..1) {
        f.make_ascii_lowercase();
    }
}

Answer 2

In addition to Shepmaster's answer, another reason to accept a &str (and similarly &[T] etc) is because of all of the other types besides String and &str that also satisfy Deref<Target = str>. One of the most notable examples is Cow<str>, which lets you be very flexible about whether you are dealing with owned or borrowed data.

If you have:

fn awesome_greeting(name: &String) {
    println!("Wow, you are awesome, {}!", name);
}

But you need to call it with a Cow<str>, you'll have to do this:

let c: Cow<str> = Cow::from("hello");
// Allocate an owned String from a str reference and then makes a reference to it anyway!
awesome_greeting(&c.to_string());

When you change the argument type to &str, you can use Cow seamlessly, without any unnecessary allocation, just like with String:

let c: Cow<str> = Cow::from("hello");
// Just pass the same reference along
awesome_greeting(&c);

let c: Cow<str> = Cow::from(String::from("hello"));
// Pass a reference to the owned string that you already have
awesome_greeting(&c);

Accepting &str makes calling your function more uniform and convenient, and the "easiest" way is now also the most efficient. These examples will also work with Cow<[T]> etc.

Answer 3

To reduce code duplication and allow reuse.

The recommendation is using &str over &String because &str also satisfies &String or other types that borrows underlying utf-8 values. This makes the function usable for both owned strings and the string slices but not the other way around:

use std::borrow::Cow;

fn greeting_one(name: &String) {
    println!("Wow, you are awesome, {}!", name);
}

fn greeting_two(name: &str) {
    println!("Wow, you are awesome, {}!", name);
}

fn main() {
    let s1 = "John Doe".to_string();
    let s2 = "Jenny Doe";
    let s3 = Cow::Borrowed("Sally Doe");
    let s4 = Cow::Owned("Sally Doe".to_string());

    greeting_one(&s1);
    // greeting_one(&s2);  // Does not compile
    // greeting_one(&s3);  // Does not compile
    greeting_one(&s4);
    
    greeting_two(&s1);
    greeting_two(s2);
    greeting_two(&s3);
    greeting_two(&s4);
}

Using vectors to manipulate text is never a good idea and does not even deserve discussion because you will loose all the sanity checks and performance optimizations the compiler provides.

String type uses vector internally anyway. Remember, Rust uses UTF-8 for strings for storage efficiency. If you use vector, you have to repeat all the hard work. Other than that, borrowing vectors or boxed values should be OK.

All these explanation becomes more clear if you understand the distinction between different string types.

What are the differences between Rust's `String` and `str`?

Answer 4

Because those types can be coerced, so if we use those types functions will accept less types:

1- a reference to String can be coerced to a str slice. For example create a function:

fn count_wovels(words:&String)->usize{
    let wovels_count=words.chars().into_iter().filter(|x|(*x=='a') | (*x=='e')| (*x=='i')| (*x=='o')|(*x=='u')).count();
    wovels_count
}

if you pass &str, it will not be accepted:

let name="yilmaz".to_string();
println!("{}",count_wovels(&name));
// this is not allowed because argument should be &String but we are passing str
// println!("{}",wovels("yilmaz"))

But if that function accepts &str instead

// words:&str
fn count_wovels(words:&str)->usize{ ... }

we can pass both types to the function

let name="yilmaz".to_string();
println!("{}",count_wovels(&name));
println!("{}",wovels("yilmaz"))

With this, our function can accept more types

2- Similary, a reference to Box &Box[T], will be coerced to the reference to the value inside the Box Box[&T]. for example

fn length(name:&Box<&str>){
    println!("lenght  {}",name.len())
}

this accepts only &Box<&str> type

let boxed_str=Box::new("Hello");
length(&boxed_str);

// expected reference `&Box<&str>` found reference `&'static str`
// length("hello")

If we pass &str as type, we can pass both types

3- Similar relation exists between ref to a Vec and ref to an array

fn square(nums:&Vec<i32>){
    for num in nums{
        println!("square of {} is {}",num,num*num)
    }
}
fn main(){
    let nums=vec![1,2,3,4,5];
    let nums_array=[1,2,3,4,5];
    // only &Vec<i32> is accepted
    square(&nums);
    // mismatched types: mismatched types expected reference `&Vec<i32>` found reference `&[{integer}; 5]`
    //square(&nums_array)
}

this will work for both types

fn square(nums:&[i32]){..}