convert_to_spaces/

lib.rs

/*
Convert tabs to spaces
implementation by Radim Kolar <hsn@sendmail.cz> 2025
https://gitlab.com/hsn10/convert-to-spaces

This is free and unencumbered software released into the public domain.
SPDX-License-Identifier: Unlicense OR CC0-1.0

For more information, please refer to <http://unlicense.org/>
*/

#![forbid(unsafe_code)]
#![forbid(missing_docs)]

//! # convert-to-spaces
//!
//! [![Crates.io](https://img.shields.io/crates/v/convert-to-spaces.svg)](https://crates.io/crates/convert-to-spaces)
//! [![License](https://img.shields.io/crates/l/convert-to-spaces)](https://unlicense.org)
//! [![MSRV](https://img.shields.io/crates/msrv/convert-to-spaces?logo=rust&label=MSRV&labelColor=orange)](https://blog.rust-lang.org/2021/10/21/Rust-1.56.0.html)
//! [![Docs.rs](https://docs.rs/convert-to-spaces/badge.svg)](https://docs.rs/convert-to-spaces)
//! [![Downloads](https://img.shields.io/crates/d/convert-to-spaces)](https://crates.io/crates/convert-to-spaces/versions)
//!
//! Convert tabs to spaces in a string, respecting tab stop logic.
//!
//! ## Overview
//!
//! `convert-to-spaces` is a lightweight Rust crate designed to precisely transform tab characters (`\t`)
//! into the appropriate number of spaces. Unlike simple find-and-replace, this crate correctly
//! applies **tab stop logic**, ensuring that text aligns to the next multiple of your specified tab size.
//! This is crucial for maintaining consistent indentation and code readability, mimicking the behavior
//! of modern text editors.
//!
//! Whether you're processing code, cleaning up text files, or preparing content for display,
//! `convert-to-spaces` helps standardize your whitespace.
//!
//! ## Features
//!
//! * **Accurate Tab Stop Conversion:** Converts `\t` characters into the correct number of spaces
//!     based on the current column position and a defined tab size.
//! * **Flexible Input:** Accepts any type that can be referenced as a string (`&str`, `String`, `&String`, etc.)
//!     using [`AsRef<str>`].
//! * **Configurable Tab Size:** Easily specify how many spaces each tab stop represents.
//! * **Lightweight:** No dependencies, focusing solely on efficient whitespace conversion.
//! * **MSRV 1.56:** Access to entire *Rust 2021 Edition*.
//! * **Public domain:** No need to give credits. Fully [free software](https://unlicense.org/).
//!
//! ## Installation
//!
//! Add `convert-to-spaces` to your `Cargo.toml` file:
//!
//! ```toml
//! [dependencies]
//! convert-to-spaces = "0.1" # Use the latest version from crates.io
//! ```
//!
//! Then, run `cargo build` or `cargo update`.
//!
//! ## Usage
//!
//! The primary function provided by this crate is [`convert_to_spaces`].
//!
//! Here's how to use it:
//!
//! ```rust
//! use convert_to_spaces::convert_to_spaces;
//!
//! fn main() {
//!     // Example 1: Basic conversion with a tab size of 4
//!     let input1 = "fn main() {\n\tprintln!(\"Hello, world!\");\n}";
//!     let output1 = convert_to_spaces(input1, 4);
//!     println!("Input:\n{}", input1);
//!     println!("Output (tab size 4):\n{}", output1);
//!     // Expected output:
//!     // fn main() {
//!     //     println!("Hello, world!");
//!     // }
//!
//!     println!("--------------------");
//!
//!     // Example 2: Text that doesn't start at column 0
//!     let input2 = "    Some text\taligned"; // 4 spaces before "Some text"
//!     let output2 = convert_to_spaces(input2, 8);
//!     println!("Input:\n{}", input2);
//!     println!("Output (tab size 8):\n{}", output2);
//!     // Expected output:
//!     //     Some text       aligned
//!     // ("Some text" is 9 chars. current_column=4+9=13. Next multiple of 8 after 13 is 16. Need 16-13=3 spaces)
//!
//!     println!("--------------------");
//!
//!     // Example 3: Zero tab size (effectively removes tabs)
//!     let input3 = "Tab\tremoved";
//!     let output3 = convert_to_spaces(input3, 0);
//!     println!("Input:\n{}", input3);
//!     println!("Output (tab size 0):\n{}", output3);
//!     // Expected output:
//!     // Tabremoved
//! }
//! ```
//!
//! ## License
//!
//! This is free and unencumbered software released into the **public domain**.
//!
//! You may use, modify, distribute, and contribute to this code without restriction. To the extent possible under law, the author(s) of this work waive all copyright and related rights.
//!
//! Licensed under [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/) OR [Unlicense](http://unlicense.org/).
//!
//! ![Unlicense logo](https://unlicense.org/pd-icon.png)

/// Converts tabs in a string to a specified number of spaces, respecting tab stop logic.
///
/// Each tab character (`\t`) will advance the text to the next multiple of the
/// `tab_size`. The number of spaces inserted will vary depending on the
/// current column position.
///
/// # Arguments
///
/// * `input` - The string-like reference (`AsRef<str>`) to convert. This allows
///             passing `&str`, `String`, `&String`, etc.
/// * `tab_size` - The size of a tab stop. If 0, tabs are effectively removed.
///
/// # Returns
///
/// A `String` with all tab characters (`\t`) correctly replaced by spaces
/// according to tab stop rules.
///
/// # Examples
///
/// ```
/// use convert_to_spaces::convert_to_spaces;
///
/// assert_eq!(convert_to_spaces("SPACE\tTAB", 4), "SPACE   TAB");
/// assert_eq!(convert_to_spaces("\tHello", 4), "    Hello");
/// assert_eq!(convert_to_spaces("Line 1\n\tLine 2", 2), "Line 1\n  Line 2");
/// assert_eq!(convert_to_spaces(String::from("MyString\t"), 8), "MyString        ");
/// assert_eq!(convert_to_spaces("No tabs here", 4), "No tabs here");
/// ```
pub fn convert_to_spaces<S: AsRef<str>>(input: S, tab_size: usize) -> String {
   let input_str = input.as_ref();

   // If tab_size is 0, a tab will insert 0 spaces, effectively removing tabs.
   if tab_size == 0 {
      return input_str.replace('\t', "");
   }

   let mut result = String::new();
   let mut current_column = 0;

   for char_code in input_str.chars() {
      match char_code {
         '\t' => {
            // Calculate how many spaces are needed to reach the next tab stop
            let spaces_to_add = tab_size - (current_column % tab_size);
            for _ in 0..spaces_to_add {
               result.push(' ');
            }
            current_column += spaces_to_add;
         }
         '\n' => {
            // Reset column count for a new line
            result.push('\n');
            current_column = 0;
         }
         c => {
            // For other characters, simply append and increment column count
            result.push(c);
            // NOTE: This assumes character width is 1. For actual wide/emoji characters,
            // `current_column` would need to be based on grapheme clusters
            // and their display widths (e.g., using `unicode-width` crate).
            current_column += 1;
         }
      }
   }

   result
}

#[cfg(test)]
#[path = "lib_tests.rs"]
mod tests;