textflow-rs 0.2.4

Bounded no_std Unicode text layout, bidi shaping, line breaking, and caret positioning for Rust
Documentation
//! Bounded `no_std` Unicode text layout and shaping.
//!
//! [`TextFlow`] provides borrowed line layout with explicit width, height, and spacing metrics.
//! The optional shaping pipeline adds bidirectional text, font fallback, safe line breaking,
//! positioned glyphs, visual runs, and caret positions through caller-owned buffers.
//!
//! # Line layout
//!
//! ```
//! use textflow::TextFlow;
//!
//! let text = "A small UI can still set type well.";
//! let lines = TextFlow::new(text, 12)
//!     .map(|line| line.text())
//!     .collect::<Vec<_>>();
//!
//! assert_eq!(lines, ["A small UI", "can still", "set type", "well."]);
//! ```

#![no_std]

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(test)]
extern crate std;

use crate::line::Lines;

#[cfg(feature = "shaping")]
pub use crate::layout::{
    Alignment, LayoutError, LayoutScratch, Overflow, ParagraphLayout, WrapMode,
};
pub use crate::line::Line;

#[cfg(feature = "shaping")]
use crate::bidi::{BaseDirection, Direction};
#[cfg(feature = "shaping")]
use crate::layout::LayoutOptions;
#[cfg(all(feature = "alloc", feature = "shaping"))]
use crate::shaping::Typeface;
#[cfg(feature = "shaping")]
use crate::shaping::{FlowPoint, FontFeature};
#[cfg(feature = "shaping")]
use crate::unicode::LineBreakProvider;
#[cfg(all(feature = "alloc", feature = "shaping"))]
use crate::workspace::{LayoutOutput, TextWorkspace, WorkspaceError};

#[cfg(feature = "bidi")]
mod buffer;
mod line;
mod properties;

#[cfg(feature = "bidi")]
pub mod bidi;
#[cfg(feature = "shaping")]
pub mod layout;
#[cfg(feature = "shaping")]
pub mod shaping;
#[cfg(any(
    feature = "script-arabic",
    feature = "script-thai",
    feature = "script-devanagari"
))]
pub use crate::shaping::scripts;
#[cfg(not(feature = "unicode"))]
mod unicode;
#[cfg(feature = "unicode")]
pub mod unicode;
#[cfg(all(feature = "alloc", feature = "shaping"))]
pub mod workspace;

pub struct TextFlow<'a> {
    #[cfg(feature = "shaping")]
    text: &'a str,
    #[cfg(feature = "shaping")]
    max_width: usize,
    #[cfg(feature = "shaping")]
    width: Option<usize>,
    line_height: usize,
    line_spacing: usize,
    lines: Lines<'a>,
    #[cfg(feature = "shaping")]
    base_direction: BaseDirection,
    #[cfg(feature = "shaping")]
    features: &'a [FontFeature],
    #[cfg(feature = "shaping")]
    origin: FlowPoint,
    #[cfg(feature = "shaping")]
    wrap: WrapMode,
    #[cfg(feature = "shaping")]
    line_break_provider: Option<&'a dyn LineBreakProvider>,
    #[cfg(feature = "shaping")]
    letter_spacing: i32,
    #[cfg(feature = "shaping")]
    word_spacing: i32,
    #[cfg(feature = "shaping")]
    alignment: Alignment,
    #[cfg(feature = "shaping")]
    max_lines: usize,
    #[cfg(feature = "shaping")]
    overflow: Overflow,
}

impl<'a> TextFlow<'a> {
    pub fn new(text: &'a str, max_width: usize) -> Self {
        TextFlow {
            #[cfg(feature = "shaping")]
            text,
            #[cfg(feature = "shaping")]
            max_width,
            #[cfg(feature = "shaping")]
            width: Some(max_width),
            line_height: 0,
            line_spacing: 0,
            lines: Lines::new(text, max_width, 4),
            #[cfg(feature = "shaping")]
            base_direction: BaseDirection::Auto,
            #[cfg(feature = "shaping")]
            features: &[],
            #[cfg(feature = "shaping")]
            origin: FlowPoint { x: 0, y: 0 },
            #[cfg(feature = "shaping")]
            wrap: WrapMode::Word,
            #[cfg(feature = "shaping")]
            line_break_provider: None,
            #[cfg(feature = "shaping")]
            letter_spacing: 0,
            #[cfg(feature = "shaping")]
            word_spacing: 0,
            #[cfg(feature = "shaping")]
            alignment: Alignment::Start,
            #[cfg(feature = "shaping")]
            max_lines: usize::MAX,
            #[cfg(feature = "shaping")]
            overflow: Overflow::Clip,
        }
    }

    pub const fn with_line_height(mut self, line_height: usize) -> Self {
        self.line_height = line_height;
        self
    }

    pub const fn with_line_spacing(mut self, line_spacing: usize) -> Self {
        self.line_spacing = line_spacing;
        self
    }

    #[cfg(feature = "shaping")]
    /// Sets the width used for alignment and overflow without changing line breaks.
    pub const fn with_width(mut self, width: usize) -> Self {
        self.width = Some(width);
        self
    }

    #[cfg(feature = "shaping")]
    /// Removes the width used for alignment and overflow without changing line breaks.
    pub const fn without_width(mut self) -> Self {
        self.width = None;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_direction(mut self, direction: BaseDirection) -> Self {
        self.base_direction = direction;
        self
    }

    #[cfg(feature = "shaping")]
    pub fn with_features(mut self, features: &'a [FontFeature]) -> Self {
        self.features = features;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_origin(mut self, origin: FlowPoint) -> Self {
        self.origin = origin;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_wrap(mut self, wrap: WrapMode) -> Self {
        self.wrap = wrap;
        self
    }

    #[cfg(feature = "shaping")]
    /// Adds application-defined line breaks without transferring ownership.
    pub const fn with_line_break_provider(mut self, provider: &'a dyn LineBreakProvider) -> Self {
        self.line_break_provider = Some(provider);
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_letter_spacing(mut self, spacing: i32) -> Self {
        self.letter_spacing = spacing;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_word_spacing(mut self, spacing: i32) -> Self {
        self.word_spacing = spacing;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_alignment(mut self, alignment: Alignment) -> Self {
        self.alignment = alignment;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_max_lines(mut self, max_lines: usize) -> Self {
        self.max_lines = max_lines;
        self
    }

    #[cfg(feature = "shaping")]
    pub const fn with_overflow(mut self, overflow: Overflow) -> Self {
        self.overflow = overflow;
        self
    }

    #[cfg(feature = "shaping")]
    /// Lays out a paragraph with fixed-capacity stack or static scratch storage.
    pub fn layout_with_scratch<
        'scratch,
        const RUNS: usize,
        const GLYPHS: usize,
        const LINES: usize,
        const CARETS: usize,
    >(
        &self,
        typefaces: &[&dyn crate::shaping::Typeface],
        scratch: &'scratch mut LayoutScratch<RUNS, GLYPHS, LINES, CARETS>,
    ) -> Result<ParagraphLayout<'scratch>, LayoutError> {
        scratch.layout(self, typefaces)
    }

    #[cfg(all(feature = "alloc", feature = "shaping"))]
    /// Lays out a paragraph into caller-owned output using reusable private storage.
    pub fn layout_into<'output>(
        &self,
        typefaces: &[&dyn Typeface],
        workspace: &mut TextWorkspace,
        output: &'output mut LayoutOutput<'_>,
    ) -> Result<ParagraphLayout<'output>, WorkspaceError> {
        let result = workspace.layout_into(self, typefaces, output)?;
        Ok(output.layout(result))
    }

    #[cfg(feature = "shaping")]
    fn layout_options(
        &self,
        line_advance: i32,
        direction: Direction,
        width: Option<i32>,
    ) -> LayoutOptions {
        let options = LayoutOptions::new(line_advance)
            .with_origin(self.origin)
            .with_spacing(layout::TextSpacing {
                letter: self.letter_spacing,
                word: self.word_spacing,
            })
            .with_alignment(self.alignment)
            .with_direction(direction)
            .with_max_lines(self.max_lines)
            .with_overflow(self.overflow);
        match width {
            Some(width) => options.with_width(width),
            None => options,
        }
    }
}

impl<'a> Iterator for TextFlow<'a> {
    type Item = Line<'a>;

    fn next(&mut self) -> Option<Self::Item> {
        let mut line = self.lines.next()?;
        line.set_metrics(self.line_height, self.line_spacing);
        Some(line)
    }
}