arcweight 0.3.0

//! # Prelude
//!
//! Convenient re-exports of commonly used types and functions.
//!
//! ## Overview
//!
//! The prelude module provides a curated collection of the most frequently used
//! items from ArcWeight, allowing you to get started quickly with a single import:
//!
//! ```
//! use arcweight::prelude::*;
//! ```
//!
//! This import brings all essential types, traits, and functions into scope,
//! minimizing boilerplate while avoiding namespace pollution with rarely-used items.
//!
//! ## Contents
//!
//! ### Core Types
//!
//! | Category | Items |
//! |----------|-------|
//! | FST Types | [`VectorFst`], [`ConstFst`], [`CompactFst`] |
//! | Arc Type | [`Arc`] for representing transitions |
//! | Traits | [`Fst`], [`MutableFst`], [`ExpandedFst`] |
//! | Identifiers | [`StateId`], [`Label`], [`NO_STATE_ID`], [`NO_LABEL`] |
//!
//! ### Semirings
//!
//! All major semiring types and traits:
//!
//! | Category | Items |
//! |----------|-------|
//! | Common Weights | [`TropicalWeight`], [`ProbabilityWeight`], [`BooleanWeight`] |
//! | Additional Weights | [`LogWeight`], [`RealWeight`], [`ProductWeight`], [`StringWeight`] |
//! | Semiring Traits | [`Semiring`], [`StarSemiring`], [`DivisibleSemiring`] |
//!
//! ### Algorithms
//!
//! Essential FST algorithms with typical complexity bounds:
//!
//! | Operation | Functions | Complexity |
//! |-----------|-----------|------------|
//! | Composition | [`compose()`], [`compose_default()`] | $`O(\|V_1\| \cdot \|V_2\| \cdot D_1 \cdot D_2)`$ |
//! | Concatenation | [`concat()`] | $`O(\|V\| + \|E\|)`$ |
//! | Union | [`union()`] | $`O(\|V\| + \|E\|)`$ |
//! | Closure | [`closure()`], [`closure_plus()`] | $`O(\|V\| + \|E\|)`$ |
//! | Determinization | [`determinize()`] | $`O(2^{\|V\|})`$ worst case |
//! | Minimization | [`minimize()`], [`minimize_hopcroft()`] | $`O(\|V\| \log \|V\|)`$ |
//! | Epsilon Removal | [`remove_epsilons()`] | $`O(\|V\|^2 + \|V\| \cdot \|E\|)`$ |
//! | Shortest Path | [`shortest_path()`] | $`O(\|V\| \log \|V\| + \|E\|)`$ |
//!
//! ### I/O Operations
//!
//! File format support:
//!
//! | Format | Read | Write |
//! |--------|------|-------|
//! | Text | [`read_text()`] | [`write_text()`] |
//! | OpenFST | [`read_openfst()`] | [`write_openfst()`] |
//! | Binary (serde) | [`read_binary()`] | [`write_binary()`] |
//!
//! ### Properties and Utilities
//!
//! - **Property analysis:** [`compute_properties()`], [`FstProperties`], [`PropertyFlags`]
//! - **Symbol tables:** [`SymbolTable`] for label-to-string mappings
//! - **Path utilities:** [`FstPath`], [`PathIterExt`] for path extraction
//! - **Error handling:** [`Error`], [`Result`] types
//! - **Numeric traits:** [`Zero`], [`One`] from num-traits
//!
//! ## Examples
//!
//! ### Basic FST Construction
//!
//! ```
//! use arcweight::prelude::*;
//!
//! let mut fst = VectorFst::<TropicalWeight>::new();
//! let s0 = fst.add_state();
//! let s1 = fst.add_state();
//!
//! fst.set_start(s0);
//! fst.set_final(s1, TropicalWeight::one());
//! fst.add_arc(s0, Arc::new(1, 2, TropicalWeight::new(0.5), s1));
//! ```
//!
//! ### Algorithm Chaining
//!
//! ```
//! use arcweight::prelude::*;
//!
//! fn process_fst(fst: &VectorFst<TropicalWeight>) -> Result<VectorFst<TropicalWeight>> {
//!     // Chain multiple operations
//!     let deterministic: VectorFst<TropicalWeight> = determinize(fst)?;
//!     let minimal: VectorFst<TropicalWeight> = minimize(&deterministic)?;
//!     let reversed: VectorFst<TropicalWeight> = reverse(&minimal)?;
//!     Ok(reversed)
//! }
//! ```
//!
//! ### Working with Different Semirings
//!
//! ```
//! use arcweight::prelude::*;
//!
//! // Boolean semiring for unweighted FSTs
//! let bool_fst = VectorFst::<BooleanWeight>::new();
//!
//! // Probability semiring for probabilistic models
//! let prob_fst = VectorFst::<ProbabilityWeight>::new();
//!
//! // Log semiring for numerical stability
//! let log_fst = VectorFst::<LogWeight>::new();
//! ```
//!
//! ## Design Philosophy
//!
//! The prelude is designed to include items that are:
//!
//! 1. **Frequently used:** Core types needed in most FST programs
//! 2. **Unambiguous:** No naming conflicts with common Rust items
//! 3. **Essential:** Fundamental to working with the library
//!
//! More specialized items remain in their respective modules to avoid
//! namespace pollution while keeping the prelude focused and ergonomic.

pub use num_traits::{One, Zero};

pub use crate::{
    // algorithms
    algorithms::{
        arc_sort, arc_sum, arc_unique, closure, closure_plus, compose, compose_default, concat,
        condense, connect, decode, decode_linear_fst, decode_linear_fst_input,
        decode_linear_fst_output, determinize, encode, isomorphic, minimize, minimize_hopcroft,
        partition, project_input, project_output, prune, remove_epsilons, reverse, reweight,
        shortest_distance, shortest_path, shortest_path_single, state_sort, topsort, union,
        weight_convert, ArcSortType, ComposeFilter, DefaultComposeFilter, EncodeTable,
        ReweightType, ShortestPathConfig, StateSortType,
    },

    // core types
    arc::{Arc, ArcIterator},
    // fst implementations
    fst::{CompactFst, ConstFst, VectorFst},

    fst::{ExpandedFst, Fst, Label, MutableFst, StateId, NO_LABEL, NO_STATE_ID},

    // i/o
    io::{read_openfst, read_text, write_openfst, write_text},

    // optimization
    optimization::{
        optimize_for_performance, prefetch_cache_line, AccessPattern, ArcPool, CacheMetadata,
        OptimizationRecommendation, OptimizedFst, SimdOps,
    },

    // properties
    properties::{compute_properties, FstProperties, PropertyFlags},

    // semirings
    semiring::{
        BooleanWeight, DivisibleSemiring, IntegerWeight, InvertibleSemiring, LogWeight, MaxWeight,
        MinWeight, NaturallyOrderedSemiring, ProbabilityWeight, ProductWeight, RealWeight,
        Semiring, SemiringProperties, StarSemiring, StringWeight, TropicalWeight,
    },

    // utilities
    utils::{FstPath, PathIterExt, SymbolTable},

    // error handling
    Error,
    Result,
};

#[cfg(feature = "serde")]
pub use crate::io::{read_binary, write_binary};