os_essentials 0.0.3

//! This module provides utility functions for converting between `usize`, `i32`, and string representations.
//! It includes methods for converting `usize` to a string, converting a string to a `usize`, and converting 
//! a non-negative `i32` to a `usize`.

/// Converts a `usize` number into a string slice (`&'static str`).
///
/// This function manually converts the digits of a `usize` into a string representation stored in a static buffer.
/// It handles the case where `num` is zero and reverses the digits to ensure correct order in the final string.
/// 
/// # Example
/// 
/// ```rust
/// let num = 12345;
/// let result = usize_to_str(num);
/// assert_eq!(result, "12345");
/// ```
pub fn usize_to_str(num: usize) -> &'static str {
    static mut BUFFER: [u8; 20] = [0; 20];
    let mut i = 0;

    if num == 0 {
        unsafe {
            BUFFER[i] = b'0';
            i += 1;
        }
    } else {
        let mut n = num;
        while n > 0 {
            unsafe {
                BUFFER[i] = b'0' + (n % 10) as u8;
                n /= 10;
                i += 1;
            }
        }
    }

    // Reverse the digits in the buffer to get the correct order
    for j in 0..i / 2 {
        unsafe {
            let temp = BUFFER[j];
            BUFFER[j] = BUFFER[i - 1 - j];
            BUFFER[i - 1 - j] = temp;
        }
    }

    unsafe {
        core::str::from_utf8_unchecked(&BUFFER[..i])
    }
}

/// Converts a string slice (`&str`) into a `usize`, returning `None` if the string is invalid.
///
/// This function assumes that the string contains only digits. If any non-digit characters are encountered, it will
/// return `None`. The conversion uses safe methods to prevent overflow.
///
/// # Example
///
/// ```rust
/// let s = "12345";
/// let result = str_to_usize(s);
/// assert_eq!(result, Some(12345));
/// ```
///
/// # Errors
///
/// Returns `None` if the string contains any non-digit characters or if the conversion overflows.
pub fn str_to_usize(s: &str) -> Option<usize> {
    let mut result: usize = 0;

    for byte in s.as_bytes() {
        // Ensure the byte is a valid digit
        if *byte < b'0' || *byte > b'9' {
            return None;
        }
        // Handle overflow by using `checked_*` methods
        result = result.checked_mul(10)?.checked_add((byte - b'0') as usize)?;
    }

    Some(result)
}

/// Converts a non-negative `i32` to a `usize`, returning `None` if the number is negative.
///
/// This function safely converts a non-negative `i32` value to a `usize`. If the number is negative, it returns `None`.
/// 
/// # Example
///
/// ```rust
/// let num = 123;
/// let result = i32_to_usize(num);
/// assert_eq!(result, Some(123));
/// ```
///
/// # Errors
///
/// Returns `None` if the input number is negative.
pub fn i32_to_usize(num: i32) -> Option<usize> {
    if num < 0 {
        return None; // Return `None` for negative numbers
    }
    Some(num as usize) // Safe conversion since the number is non-negative
}