faststr

Crates.io Documentation Website License Build Status

faststr is a string library that try to avoid the cost of clone.

Why we need it?

In Rust, the String type is commonly used, but it has the following problems:

  1. In many scenarios in asynchronous Rust, we cannot determine when a String is dropped. For example, when we send a String through RPC/HTTP, we cannot explicitly mark the lifetime, thus we must clone it;
  2. Rust's asynchronous ecosystem is mainly based on Tokio, with network programming largely relying on bytes::Bytes. We can take advantage of Bytes to avoid cloning Strings, while better integrating with the Bytes ecosystem;
  3. Even in purely synchronous code, when the code is complex enough, marking the lifetime can greatly affect code readability and maintainability. In business development experience, there will often be multiple Strings from different sources combined into a single Struct for processing. In such situations, it's almost impossible to avoid cloning using lifetimes;
  4. Cloning a String is quite costly;

Therefore, we have created the FastStr type. By sacrificing immutability, we can avoid the overhead of cloning Strings and better integrate with Rust's asynchronous, microservice, and network programming ecosystems.

When should I use it?

  1. When you need to send a String through RPC/HTTP;
  2. When you read a String from a file or database or config;
  3. Everywhere when you don't need to mutate the String anymore;

How to migrate to FastStr?

FastStr implements From trait for various types, so you can easily migrate to FastStr by replacing String with FastStr and adding .into().

For example, if your API is something like this:

rust fn need_a_string(s: String)

You may change it to:

rust fn need_a_string<S: Into<FastStr>>(s: S)

This will not be a break change for users.

Features

Related Projects

Contributing

See CONTRIBUTING.md for more information.

All contributions are welcomed!

License

faststr is dual-licensed under the MIT license and the Apache License (Version 2.0).

See LICENSE-MIT and LICENSE-APACHE for details.

Credits

faststr copied and used some code from smol_str, which is also licensed under the MIT license and the Apache License (Version 2.0).

We really appreciate the work of smol_str team.

Community