east_asian_width/

lib.rs

#![deny(missing_docs)]
//! # East Asian Width
//!
//! A Rust library for determining the display width of Unicode characters in East Asian contexts.
//! This is particularly useful for terminal applications, text editors, and other software that
//! needs to properly align text containing CJK (Chinese, Japanese, Korean) characters.
//!
//! ## Features
//!
//! - **Fast lookups**: Pre-generated lookup tables for O(1) character width determination
//! - **Unicode compliant**: Based on the official Unicode East Asian Width property
//! - **Flexible API**: Support for both simple and configurable width calculations
//! - **Zero dependencies**: No runtime dependencies for the core library
//!
//! ## Usage
//!
//! ### Basic Usage
//!
//! ```rust
//! use east_asian_width::{east_asian_width, east_asian_width_type, DisplayWidth};
//!
//! // Get the display width of a character
//! assert_eq!(east_asian_width('A' as u32), DisplayWidth::Narrow);  // Narrow/Neutral = 1
//! assert_eq!(east_asian_width('字' as u32), DisplayWidth::Wide); // Wide = 2
//!
//! // Convert to numeric values when needed
//! assert_eq!(east_asian_width('A' as u32).as_u8(), 1);
//! assert_eq!(east_asian_width('字' as u32).as_u8(), 2);
//!
//! // Get the East Asian Width category
//! assert_eq!(east_asian_width_type('A' as u32), "narrow");
//! assert_eq!(east_asian_width_type('字' as u32), "wide");
//! ```
//!
//! ### Handling Ambiguous Characters
//!
//! Some characters are classified as "ambiguous" and can be displayed as either narrow or wide
//! depending on the context. You can control this behavior:
//!
//! ```rust
//! use east_asian_width::{east_asian_width, DisplayWidth};
//!
//! let ambiguous_char = 0x00A1; // ¡ (inverted exclamation mark)
//!
//! // Default: ambiguous characters are treated as narrow (width 1)
//! assert_eq!(east_asian_width(ambiguous_char), DisplayWidth::Narrow);
//!
//! // Treat ambiguous characters as wide (width 2)
//! assert_eq!(east_asian_width((ambiguous_char, true)), DisplayWidth::Wide);
//!
//! // Convert to numeric values
//! assert_eq!(east_asian_width(ambiguous_char).as_u8(), 1);
//! assert_eq!(east_asian_width((ambiguous_char, true)).as_u8(), 2);
//! ```
//!
//! ## Character Categories
//!
//! The library recognizes six East Asian Width categories:
//!
//! - **Narrow (Na)**: Characters that are always narrow (width 1)
//! - **Neutral (N)**: Characters that don't have East Asian context (width 1)
//! - **Halfwidth (H)**: Characters that are narrow in East Asian context (width 1)
//! - **Ambiguous (A)**: Characters that can be narrow or wide depending on context
//! - **Wide (W)**: Characters that are always wide (width 2)
//! - **Fullwidth (F)**: Characters that are wide in East Asian context (width 2)

/// Error types and validation functions for East Asian Width operations.
pub mod error;

/// Contains the generated Unicode lookup tables and functions.
///
/// This module provides low-level access to the Unicode East Asian Width data
/// through pre-generated lookup functions. These functions are used internally
/// by the high-level API but can also be used directly for performance-critical code.
pub mod lookup;
use lookup::get_category;

// Re-export error types and validation
pub use error::{EastAsianWidthError, validate_code_point};

// Re-export lookup functions for compatibility
pub use lookup::{is_ambiguous, is_full_width, is_wide};

#[cfg(test)]
mod tests;

/// Represents the display width of a character in East Asian contexts
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DisplayWidth {
    /// Narrow character (width 1)
    Narrow = 1,
    /// Wide character (width 2)
    Wide = 2,
}

impl DisplayWidth {
    /// Returns the numeric width value
    pub const fn as_u8(self) -> u8 {
        self as u8
    }

    /// Returns the numeric width value as usize (common for string operations)
    pub const fn as_usize(self) -> usize {
        self as usize
    }
}

impl From<DisplayWidth> for u8 {
    fn from(width: DisplayWidth) -> Self {
        width.as_u8()
    }
}

impl From<DisplayWidth> for usize {
    fn from(width: DisplayWidth) -> Self {
        width.as_usize()
    }
}

/// Trait to allow different parameter types for the [`east_asian_width`] function.
///
/// This trait enables the function to accept either a simple `u32` code point or a tuple
/// `(u32, bool)` where the boolean indicates whether ambiguous characters should be treated as wide.
///
/// # Implementations
///
/// - `u32`: Treats ambiguous characters as narrow (width 1)
/// - `(u32, bool)`: Uses the boolean to determine ambiguous character handling
pub trait EastAsianWidthInput {
    /// Returns the Unicode code point.
    fn code_point(&self) -> u32;

    /// Returns whether ambiguous characters should be treated as wide.
    fn ambiguous_as_wide(&self) -> bool;
}

impl EastAsianWidthInput for u32 {
    fn code_point(&self) -> u32 {
        *self
    }

    fn ambiguous_as_wide(&self) -> bool {
        false
    }
}

impl EastAsianWidthInput for (u32, bool) {
    fn code_point(&self) -> u32 {
        self.0
    }

    fn ambiguous_as_wide(&self) -> bool {
        self.1
    }
}

/// Returns the East Asian Width category for a Unicode code point
///
/// # Arguments
/// * `code_point` - A Unicode code point (0-0x10FFFF)
///
/// # Returns
/// The category as a string: "ambiguous", "fullwidth", "halfwidth", "neutral", "narrow", or "wide"
///
/// # Panics
/// Panics if the code point is outside the valid Unicode range
pub fn east_asian_width_type(code_point: u32) -> &'static str {
    validate_code_point(code_point).expect("Invalid Unicode code point");
    get_category(code_point)
}

/// Fallible version of `east_asian_width_type`
///
/// # Arguments
/// * `code_point` - A Unicode code point (0-0x10FFFF)
///
/// # Returns
/// * `Ok(category)` - The category as a string
/// * `Err(EastAsianWidthError)` - If the code point is invalid
pub fn try_east_asian_width_type(code_point: u32) -> Result<&'static str, EastAsianWidthError> {
    validate_code_point(code_point)?;
    Ok(get_category(code_point))
}

/// Returns the display width of a Unicode code point in East Asian contexts
///
/// # Arguments
/// * `input` - Either a `u32` code point or `(u32, bool)` tuple where bool indicates ambiguous_as_wide
///
/// # Returns
/// * `DisplayWidth::Wide` for wide/fullwidth characters (and ambiguous if `ambiguous_as_wide` is true)
/// * `DisplayWidth::Narrow` for all other characters
///
/// # Examples
/// ```
/// use east_asian_width::{east_asian_width, DisplayWidth};
///
/// // Basic usage with just code point
/// assert_eq!(east_asian_width(0x5B57), DisplayWidth::Wide); // '字' is wide
/// assert_eq!(east_asian_width(0x5B57).as_u8(), 2); // Convert to numeric value
///
/// // With ambiguous_as_wide option
/// assert_eq!(east_asian_width((0x00A1, true)), DisplayWidth::Wide);  // ambiguous as wide
/// assert_eq!(east_asian_width((0x00A1, false)), DisplayWidth::Narrow); // ambiguous as narrow
/// ```
///
/// # Panics
/// Panics if the code point is outside the valid Unicode range
pub fn east_asian_width<T: EastAsianWidthInput>(input: T) -> DisplayWidth {
    try_east_asian_width(input).expect("Invalid Unicode code point")
}

/// Fallible version of `east_asian_width`
///
/// # Arguments
/// * `input` - Either a `u32` code point or `(u32, bool)` tuple where bool indicates ambiguous_as_wide
///
/// # Returns
/// * `Ok(DisplayWidth)` - The display width (Narrow or Wide)
/// * `Err(EastAsianWidthError)` - If the code point is invalid
///
/// # Examples
/// ```
/// use east_asian_width::{try_east_asian_width, DisplayWidth};
///
/// // Valid code points
/// assert_eq!(try_east_asian_width(0x5B57).unwrap(), DisplayWidth::Wide); // '字' is wide
/// assert_eq!(try_east_asian_width((0x00A1, true)).unwrap(), DisplayWidth::Wide);  // ambiguous as wide
/// assert_eq!(try_east_asian_width(0x5B57).unwrap().as_u8(), 2); // Convert to numeric
///
/// // Invalid code point
/// assert!(try_east_asian_width(0x110000).is_err());
/// ```
pub fn try_east_asian_width<T: EastAsianWidthInput>(
    input: T,
) -> Result<DisplayWidth, EastAsianWidthError> {
    let code_point = input.code_point();
    validate_code_point(code_point)?;

    Ok(
        if is_full_width(code_point)
            || is_wide(code_point)
            || (input.ambiguous_as_wide() && is_ambiguous(code_point))
        {
            DisplayWidth::Wide
        } else {
            DisplayWidth::Narrow
        },
    )
}