pinyin-toolkit

    Deterministic Chinese Pinyin normalization and text matching toolkit for MoonBit

    pinyin
    chinese
    text
    normalization
    matching
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    3 months ago
    Downloads
    31

    No dependencies

    #MoonBit Pinyin Toolkit

    This package provides deterministic Unicode Pinyin reading lookup, validated phrase overrides, mixed-text conversion, traceable search keys, and bounded explainable matching for MoonBit applications.

    The package uses Unicode 17.0 Unihan kMandarin and kHanyuPinyin data. The data provenance and split licensing are documented in the repository README. Context-dependent polyphone inference is represented as explicit caller phrase overrides rather than inferred silently.

    AlignmentIntegrity

    pub struct AlignmentIntegrity {
    left_covered_value : Int
    right_covered_value : Int
    step_count_value : Int
    total_cost_value : Double
    full_coverage_value : Bool
    } derive(Eq,
    Debug
    )

    Facts proven by validating alignment coverage, costs, and counters.

    AlignmentIntegrity::has_full_coverage

    fn AlignmentIntegrity::has_full_coverage(self : AlignmentIntegrity) -> Bool

    AlignmentIntegrity::left_covered

    fn AlignmentIntegrity::left_covered(self : AlignmentIntegrity) -> Int

    AlignmentIntegrity::right_covered

    fn AlignmentIntegrity::right_covered(self : AlignmentIntegrity) -> Int

    AlignmentIntegrity::steps

    fn AlignmentIntegrity::steps(self : AlignmentIntegrity) -> Int

    AlignmentIntegrity::total_cost

    fn AlignmentIntegrity::total_cost(self : AlignmentIntegrity) -> Double

    AlignmentKind

    pub(all) enum AlignmentKind {
    AlignmentMatch
    AlignmentInsertion
    AlignmentDeletion
    AlignmentSubstitution
    AlignmentEquivalence
    } derive(Eq,
    Debug
    )

    Classification of one deterministic alignment step.

    AlignmentStep

    pub struct AlignmentStep {
    kind_value : AlignmentKind
    left_start_value : Int
    left_end_value : Int
    right_start_value : Int
    right_end_value : Int
    left_fragment_value : String
    right_fragment_value : String
    cost_value : Double
    } derive(Eq,
    Debug
    )

    One immutable step in a normalized Pinyin alignment.

    AlignmentStep::cost

    fn AlignmentStep::cost(self : AlignmentStep) -> Double

    AlignmentStep::kind

    AlignmentStep::left_end

    fn AlignmentStep::left_end(self : AlignmentStep) -> Int

    AlignmentStep::left_fragment

    fn AlignmentStep::left_fragment(self : AlignmentStep) -> String

    AlignmentStep::left_start

    fn AlignmentStep::left_start(self : AlignmentStep) -> Int

    AlignmentStep::right_end

    fn AlignmentStep::right_end(self : AlignmentStep) -> Int

    AlignmentStep::right_fragment

    fn AlignmentStep::right_fragment(self : AlignmentStep) -> String

    AlignmentStep::right_start

    fn AlignmentStep::right_start(self : AlignmentStep) -> Int

    AmbiguityPolicy

    pub(all) enum AmbiguityPolicy {
    SelectFirstReading
    PreserveAllReadings
    RejectAmbiguous
    } derive(Eq,
    Debug
    )

    Controls how multiple documented readings are exposed.

    BatchItem

    pub struct BatchItem {
    identifier_value : String
    source_value : String
    } derive(Eq,
    Debug
    )

    One validated batch input with a caller-controlled stable identifier.

    BatchItem::identifier

    fn BatchItem::identifier(self : BatchItem) -> String

    BatchItem::source

    fn BatchItem::source(self : BatchItem) -> String

    BatchItemResult

    pub struct BatchItemResult {
    item_value : BatchItem
    outcome_value : BatchOutcome
    } derive(Eq,
    Debug
    )

    One auditable batch output in the same position as its input.

    BatchItemResult::conversion

    BatchItemResult::error

    BatchItemResult::is_success

    fn BatchItemResult::is_success(self : BatchItemResult) -> Bool

    BatchItemResult::item

    BatchItemResult::outcome

    BatchOutcome

    pub(all) enum BatchOutcome {
    BatchSucceeded(ConversionResult)
    BatchFailed(PinyinError)
    } derive(Eq,
    Debug
    )

    Per-item outcome; failures do not discard successful neighbors.

    BatchResult

    pub struct BatchResult {
    item_values : Array[BatchItemResult]
    summary_value : ConversionSummary
    } derive(Eq,
    Debug
    )

    Ordered per-item outcomes plus a precomputed summary.

    BatchResult::items

    BatchResult::summary

    ConversionIntegrity

    pub struct ConversionIntegrity {
    source_scalar_value : Int
    covered_scalar_value : Int
    dropped_scalar_value : Int
    token_value : Int
    candidate_value : Int
    diagnostic_value : Int
    } derive(Eq,
    Debug
    )

    Facts proven by validating one structured conversion result.

    ConversionIntegrity::covered_scalars

    fn ConversionIntegrity::covered_scalars(self : ConversionIntegrity) -> Int

    ConversionIntegrity::diagnostics

    fn ConversionIntegrity::diagnostics(self : ConversionIntegrity) -> Int

    ConversionIntegrity::dropped_scalars

    fn ConversionIntegrity::dropped_scalars(self : ConversionIntegrity) -> Int

    ConversionIntegrity::has_full_coverage

    fn ConversionIntegrity::has_full_coverage(self : ConversionIntegrity) -> Bool

    ConversionIntegrity::source_scalars

    fn ConversionIntegrity::source_scalars(self : ConversionIntegrity) -> Int

    ConversionIntegrity::tokens

    fn ConversionIntegrity::tokens(self : ConversionIntegrity) -> Int

    ConversionIntegrity::validated_candidates

    fn ConversionIntegrity::validated_candidates(self : ConversionIntegrity) -> Int

    ConversionResult

    pub struct ConversionResult {
    source_value : String
    rendered_value : String
    token_values : Array[ConvertedToken]
    diagnostic_values : Array[Diagnostic]
    } derive(Eq,
    Debug
    )

    Structured conversion result with output and decision evidence.

    ConversionResult::diagnostics

    ConversionResult::rendered

    fn ConversionResult::rendered(self : ConversionResult) -> String

    ConversionResult::source

    fn ConversionResult::source(self : ConversionResult) -> String

    ConversionResult::tokens

    ConversionStats

    pub struct ConversionStats {
    source_scalar_value : Int
    output_token_value : Int
    pinyin_token_value : Int
    literal_token_value : Int
    phrase_decision_value : Int
    unicode_decision_value : Int
    preserved_unknown_value : Int
    diagnostic_value : Int
    ambiguous_diagnostic_value : Int
    } derive(Eq,
    Debug
    )

    Counts derived from one immutable conversion result.

    ConversionStats::ambiguous_diagnostics

    fn ConversionStats::ambiguous_diagnostics(self : ConversionStats) -> Int

    ConversionStats::diagnostics

    fn ConversionStats::diagnostics(self : ConversionStats) -> Int

    ConversionStats::literal_tokens

    fn ConversionStats::literal_tokens(self : ConversionStats) -> Int

    ConversionStats::output_tokens

    fn ConversionStats::output_tokens(self : ConversionStats) -> Int

    ConversionStats::phrase_decisions

    fn ConversionStats::phrase_decisions(self : ConversionStats) -> Int

    ConversionStats::pinyin_tokens

    fn ConversionStats::pinyin_tokens(self : ConversionStats) -> Int

    ConversionStats::preserved_unknown

    fn ConversionStats::preserved_unknown(self : ConversionStats) -> Int

    ConversionStats::source_scalars

    fn ConversionStats::source_scalars(self : ConversionStats) -> Int

    ConversionStats::unicode_decisions

    fn ConversionStats::unicode_decisions(self : ConversionStats) -> Int

    ConversionSummary

    pub struct ConversionSummary {
    total_value : Int
    succeeded_value : Int
    failed_value : Int
    unknown_failure_value : Int
    ambiguous_failure_value : Int
    rendered_token_value : Int
    diagnostic_value : Int
    } derive(Eq,
    Debug
    )

    Aggregate conversion counts derived from item outcomes.

    ConversionSummary::ambiguous_failures

    fn ConversionSummary::ambiguous_failures(self : ConversionSummary) -> Int

    ConversionSummary::diagnostics

    fn ConversionSummary::diagnostics(self : ConversionSummary) -> Int

    ConversionSummary::failed

    fn ConversionSummary::failed(self : ConversionSummary) -> Int

    ConversionSummary::rendered_tokens

    fn ConversionSummary::rendered_tokens(self : ConversionSummary) -> Int

    ConversionSummary::succeeded

    fn ConversionSummary::succeeded(self : ConversionSummary) -> Int

    ConversionSummary::total

    fn ConversionSummary::total(self : ConversionSummary) -> Int

    ConversionSummary::unknown_failures

    fn ConversionSummary::unknown_failures(self : ConversionSummary) -> Int

    ConvertOptions

    pub struct ConvertOptions {
    output_style : ToneStyle
    token_separator : String
    output_case : TextCase
    unknown_behavior : UnknownPolicy
    ambiguity_behavior : AmbiguityPolicy
    } derive(Eq,
    Debug
    )

    Immutable options shared by conversion and rendering operations.

    ConvertOptions::ambiguity_policy

    fn ConvertOptions::ambiguity_policy(self : ConvertOptions) -> AmbiguityPolicy

    ConvertOptions::separator

    fn ConvertOptions::separator(self : ConvertOptions) -> String

    ConvertOptions::text_case

    fn ConvertOptions::text_case(self : ConvertOptions) -> TextCase

    ConvertOptions::tone_style

    fn ConvertOptions::tone_style(self : ConvertOptions) -> ToneStyle

    ConvertOptions::unknown_policy

    fn ConvertOptions::unknown_policy(self : ConvertOptions) -> UnknownPolicy

    ConvertedToken

    pub struct ConvertedToken {
    original_value : String
    rendered_value : String
    token_kind : TokenKind
    decision_value : DecisionSource
    source_span : SourceSpan
    candidate_values : Array[String]
    } derive(Eq,
    Debug
    )

    One auditable output token tied to a scalar span in the source.

    ConvertedToken::candidates

    fn ConvertedToken::candidates(self : ConvertedToken) -> Array[String]

    ConvertedToken::decision_source

    fn ConvertedToken::decision_source(self : ConvertedToken) -> DecisionSource

    ConvertedToken::kind

    ConvertedToken::original

    fn ConvertedToken::original(self : ConvertedToken) -> String

    ConvertedToken::rendered

    fn ConvertedToken::rendered(self : ConvertedToken) -> String

    ConvertedToken::span

    DatasetStats

    pub struct DatasetStats {
    code_point_count : Int
    reading_count : Int
    ambiguous_count : Int
    maximum_reading_count : Int
    first_code_value : Int
    last_code_value : Int
    } derive(Eq,
    Debug
    )

    Counts and boundaries proven by a full generated-data validation pass.

    DatasetStats::ambiguous_code_points

    fn DatasetStats::ambiguous_code_points(self : DatasetStats) -> Int

    DatasetStats::code_points

    fn DatasetStats::code_points(self : DatasetStats) -> Int

    DatasetStats::first_code_point

    fn DatasetStats::first_code_point(self : DatasetStats) -> Int

    DatasetStats::last_code_point

    fn DatasetStats::last_code_point(self : DatasetStats) -> Int

    DatasetStats::maximum_readings_per_code_point

    fn DatasetStats::maximum_readings_per_code_point(self : DatasetStats) -> Int

    DatasetStats::readings

    fn DatasetStats::readings(self : DatasetStats) -> Int

    DecisionSource

    pub(all) enum DecisionSource {
    PhraseLexicon
    UnicodeReading
    UnknownPreserved
    } derive(Eq,
    Debug
    )

    Diagnostic

    pub struct Diagnostic {
    code_value : String
    message_value : String
    source_span : SourceSpan?
    } derive(Eq,
    Debug
    )

    Structured warning or decision note emitted by an operation.

    Diagnostic::code

    fn Diagnostic::code(self : Diagnostic) -> String

    Diagnostic::message

    fn Diagnostic::message(self : Diagnostic) -> String

    Diagnostic::span

    fn Diagnostic::span(self : Diagnostic) -> SourceSpan?

    DistanceResult

    pub struct DistanceResult {
    total_value : Double
    insertion_count : Int
    deletion_count : Int
    substitution_count : Int
    equivalence_count : Int
    } derive(Eq,
    Debug
    )

    Weighted distance and operation counts for auditability.

    DistanceResult::cost

    fn DistanceResult::cost(self : DistanceResult) -> Double

    DistanceResult::deletions

    fn DistanceResult::deletions(self : DistanceResult) -> Int

    DistanceResult::equivalences

    fn DistanceResult::equivalences(self : DistanceResult) -> Int

    DistanceResult::insertions

    fn DistanceResult::insertions(self : DistanceResult) -> Int

    DistanceResult::operations

    fn DistanceResult::operations(self : DistanceResult) -> Int

    DistanceResult::substitutions

    fn DistanceResult::substitutions(self : DistanceResult) -> Int

    FuzzyProfile

    pub struct FuzzyProfile {
    insertion_value : Double
    deletion_value : Double
    substitution_value : Double
    equivalence_value : Double
    rule_values : FuzzyRules
    } derive(Eq,
    Debug
    )

    Validated edit costs and equivalence rules.

    FuzzyProfile::deletion_cost

    fn FuzzyProfile::deletion_cost(self : FuzzyProfile) -> Double

    FuzzyProfile::equivalence_cost

    fn FuzzyProfile::equivalence_cost(self : FuzzyProfile) -> Double

    FuzzyProfile::insertion_cost

    fn FuzzyProfile::insertion_cost(self : FuzzyProfile) -> Double

    FuzzyProfile::rules

    fn FuzzyProfile::rules(self : FuzzyProfile) -> FuzzyRules

    FuzzyProfile::substitution_cost

    fn FuzzyProfile::substitution_cost(self : FuzzyProfile) -> Double

    FuzzyRules

    pub struct FuzzyRules {
    zh_z_enabled : Bool
    ch_c_enabled : Bool
    sh_s_enabled : Bool
    n_l_enabled : Bool
    } derive(Eq,
    Debug
    )

    Switches for common Pinyin input confusions.

    FuzzyRules::ch_c_enabled

    fn FuzzyRules::ch_c_enabled(self : FuzzyRules) -> Bool

    FuzzyRules::n_l_enabled

    fn FuzzyRules::n_l_enabled(self : FuzzyRules) -> Bool

    FuzzyRules::sh_s_enabled

    fn FuzzyRules::sh_s_enabled(self : FuzzyRules) -> Bool

    FuzzyRules::zh_z_enabled

    fn FuzzyRules::zh_z_enabled(self : FuzzyRules) -> Bool

    IndexKey

    pub struct IndexKey {
    key_text : String
    profile_value : IndexProfile
    segment_values : Array[IndexSegment]
    } derive(Eq,
    Debug
    )

    A normalized key plus auditable source mapping.

    IndexKey::key

    fn IndexKey::key(self : IndexKey) -> String

    IndexKey::profile

    fn IndexKey::profile(self : IndexKey) -> IndexProfile

    IndexKey::segments

    fn IndexKey::segments(self : IndexKey) -> Array[IndexSegment]

    IndexProfile

    pub(all) enum IndexProfile {
    ExactNormalized
    FullPinyin
    Initials
    Compact
    } derive(Eq,
    Debug
    )

    Selects one deterministic search-key representation.

    IndexSegment

    pub struct IndexSegment {
    value_text : String
    source_span : SourceSpan
    source_kind : TokenKind
    } derive(Eq,
    Debug
    )

    One search-key fragment tied to its original source span.

    IndexSegment::kind

    fn IndexSegment::kind(self : IndexSegment) -> TokenKind

    IndexSegment::span

    IndexSegment::value

    fn IndexSegment::value(self : IndexSegment) -> String

    Lexicon

    pub struct Lexicon {
    nodes : Array[LexiconNode]
    values : Array[LexiconEntry]
    }

    Immutable phrase resolver backed by a flattened Trie.

    Lexicon::longest_match

    fn Lexicon::longest_match(self : Lexicon, source : Array[Int], start : Int) -> LexiconMatch?

    Returns the longest phrase beginning at a scalar offset.

    LexiconBuilder

    pub struct LexiconBuilder {
    values : Array[LexiconEntry]
    }

    Mutable construction surface with validation on every insertion.

    LexiconBuilder::add

    fn LexiconBuilder::add(self : LexiconBuilder, phrase : String, readings : Array[String]) -> Result[Unit, PinyinError]

    Adds one phrase after validating scalar and reading counts.

    LexiconBuilder::build

    Freezes entries into deterministic Trie nodes.

    LexiconBuilder::new

    LexiconEntry

    type LexiconEntry derive(Eq,
    Debug
    )

    LexiconMatch

    pub struct LexiconMatch {
    phrase_value : String
    consumed : Int
    reading_values : Array[Syllable]
    } derive(Eq,
    Debug
    )

    Evidence returned for one longest phrase match.

    LexiconMatch::length

    fn LexiconMatch::length(self : LexiconMatch) -> Int

    LexiconMatch::phrase

    fn LexiconMatch::phrase(self : LexiconMatch) -> String

    LexiconMatch::readings

    fn LexiconMatch::readings(self : LexiconMatch) -> Array[Syllable]

    LexiconNode

    type LexiconNode

    MatchCandidate

    pub struct MatchCandidate {
    label_text : String
    full_key_value : IndexKey
    initials_key_value : IndexKey
    } derive(Eq,
    Debug
    )

    Precomputed searchable representations for one caller-labelled value.

    MatchCandidate::full_key

    fn MatchCandidate::full_key(self : MatchCandidate) -> IndexKey

    MatchCandidate::initials_key

    fn MatchCandidate::initials_key(self : MatchCandidate) -> IndexKey

    MatchCandidate::label

    fn MatchCandidate::label(self : MatchCandidate) -> String

    MatchExplanation

    pub struct MatchExplanation {
    query_text : String
    full_key_text : String
    initials_key_text : String
    exact_value : Double
    prefix_value : Double
    initials_value : Double
    fuzzy_value : Double
    final_value : Double
    distance_value : DistanceResult
    } derive(Eq,
    Debug
    )

    Score components and fuzzy-distance evidence for one candidate.

    MatchExplanation::distance

    MatchExplanation::exact_component

    fn MatchExplanation::exact_component(self : MatchExplanation) -> Double

    MatchExplanation::full_key

    fn MatchExplanation::full_key(self : MatchExplanation) -> String

    MatchExplanation::fuzzy_component

    fn MatchExplanation::fuzzy_component(self : MatchExplanation) -> Double

    MatchExplanation::initials_component

    fn MatchExplanation::initials_component(self : MatchExplanation) -> Double

    MatchExplanation::initials_key

    fn MatchExplanation::initials_key(self : MatchExplanation) -> String

    MatchExplanation::prefix_component

    fn MatchExplanation::prefix_component(self : MatchExplanation) -> Double

    MatchExplanation::query

    fn MatchExplanation::query(self : MatchExplanation) -> String

    MatchExplanation::score

    fn MatchExplanation::score(self : MatchExplanation) -> Double

    Orthography

    pub(all) enum Orthography {
    PlainInput
    ToneNumberInput
    ToneMarkInput
    } derive(Eq,
    Debug
    )

    Records the notation recognized by the parser.

    PinyinAlignment

    pub struct PinyinAlignment {
    left_normalized_value : String
    right_normalized_value : String
    step_values : Array[AlignmentStep]
    total_cost_value : Double
    match_count : Int
    insertion_count : Int
    deletion_count : Int
    substitution_count : Int
    equivalence_count : Int
    } derive(Eq,
    Debug
    )

    Ordered edit evidence and aggregate operation counts.

    PinyinAlignment::deletions

    fn PinyinAlignment::deletions(self : PinyinAlignment) -> Int

    PinyinAlignment::equivalences

    fn PinyinAlignment::equivalences(self : PinyinAlignment) -> Int

    PinyinAlignment::insertions

    fn PinyinAlignment::insertions(self : PinyinAlignment) -> Int

    PinyinAlignment::left_normalized

    fn PinyinAlignment::left_normalized(self : PinyinAlignment) -> String

    PinyinAlignment::matches

    fn PinyinAlignment::matches(self : PinyinAlignment) -> Int

    PinyinAlignment::operations

    fn PinyinAlignment::operations(self : PinyinAlignment) -> Int

    PinyinAlignment::right_normalized

    fn PinyinAlignment::right_normalized(self : PinyinAlignment) -> String

    PinyinAlignment::steps

    PinyinAlignment::substitutions

    fn PinyinAlignment::substitutions(self : PinyinAlignment) -> Int

    PinyinAlignment::total_cost

    fn PinyinAlignment::total_cost(self : PinyinAlignment) -> Double

    PinyinError

    pub(all) enum PinyinError {
    InvalidSeparator(String)
    InvalidSyllable(String, String)
    UnknownCharacter(Int)
    AmbiguousCharacter(Int, Int)
    InvalidSourceSpan(Int, Int)
    InvalidLexiconEntry(String, String)
    ConflictingLexiconEntry(String)
    InvalidLexiconText(String)
    InvalidBatchItem(String, String)
    InvalidSearchDocument(String, String)
    InvalidSearchOptions(String, String)
    InvalidSearchQuery(String)
    InvalidVariantLimit(Int)
    InvalidConversionResult(String)
    InvalidAlignment(String)
    InvalidWeight(String, Double)
    InvalidGeneratedData(String)
    } derive(Eq,
    Debug
    )

    Stable errors returned by parsing, configuration, and conversion APIs.

    PinyinProcessor

    pub struct PinyinProcessor {
    lexicon_value : Lexicon
    conversion_value : ConvertOptions
    fuzzy_value : FuzzyProfile
    }

    Reusable immutable configuration for common toolkit operations.

    PinyinProcessor::candidate

    fn PinyinProcessor::candidate(self : PinyinProcessor, identifier : String, source : String) -> Result[MatchCandidate, PinyinError]

    PinyinProcessor::compare

    fn PinyinProcessor::compare(self : PinyinProcessor, left : String, right : String) -> Result[TextComparison, PinyinError]

    PinyinProcessor::conversion_options

    fn PinyinProcessor::conversion_options(self : PinyinProcessor) -> ConvertOptions

    PinyinProcessor::convert

    fn PinyinProcessor::convert(self : PinyinProcessor, source : String) -> Result[ConversionResult, PinyinError]

    PinyinProcessor::fuzzy_profile

    fn PinyinProcessor::fuzzy_profile(self : PinyinProcessor) -> FuzzyProfile

    PinyinProcessor::inspect

    fn PinyinProcessor::inspect(self : PinyinProcessor, source : String) -> ReadingInspection

    PinyinProcessor::variants

    fn PinyinProcessor::variants(self : PinyinProcessor, source : String, style : ToneStyle, separator : String, limit : Int) -> Result[VariantExpansion, PinyinError]

    RankedCandidate

    pub struct RankedCandidate {
    candidate_value : MatchCandidate
    explanation_value : MatchExplanation
    caller_position : Int
    } derive(Eq,
    Debug
    )

    One ranked result retaining the caller's original position.

    RankedCandidate::explanation

    RankedCandidate::label

    fn RankedCandidate::label(self : RankedCandidate) -> String

    RankedCandidate::original_position

    fn RankedCandidate::original_position(self : RankedCandidate) -> Int

    RankedCandidate::score

    fn RankedCandidate::score(self : RankedCandidate) -> Double

    ReadingInspection

    pub struct ReadingInspection {
    entry_values : Array[ScalarReadingEvidence]
    known_value : Int
    unknown_value : Int
    ambiguous_value : Int
    } derive(Eq,
    Debug
    )

    Ordered scalar evidence and aggregate lookup counts.

    ReadingInspection::ambiguous_scalars

    fn ReadingInspection::ambiguous_scalars(self : ReadingInspection) -> Int

    ReadingInspection::entries

    ReadingInspection::known_scalars

    fn ReadingInspection::known_scalars(self : ReadingInspection) -> Int

    ReadingInspection::total_scalars

    fn ReadingInspection::total_scalars(self : ReadingInspection) -> Int

    ReadingInspection::unknown_scalars

    fn ReadingInspection::unknown_scalars(self : ReadingInspection) -> Int

    ReadingSet

    pub struct ReadingSet {
    code_value : Int
    readings_value : Array[String]
    } derive(Eq,
    Debug
    )

    Readings attached to one Unicode scalar value.

    ReadingSet::code_point

    fn ReadingSet::code_point(self : ReadingSet) -> Int

    ReadingSet::is_ambiguous

    fn ReadingSet::is_ambiguous(self : ReadingSet) -> Bool

    ReadingSet::readings

    fn ReadingSet::readings(self : ReadingSet) -> Array[String]

    ScalarReadingEvidence

    pub struct ScalarReadingEvidence {
    code_value : Int
    original_value : String
    source_span : SourceSpan
    candidate_values : Array[String]
    } derive(Eq,
    Debug
    )

    Reading evidence for one Unicode scalar from the source text.

    ScalarReadingEvidence::candidates

    fn ScalarReadingEvidence::candidates(self : ScalarReadingEvidence) -> Array[String]

    ScalarReadingEvidence::code_point

    fn ScalarReadingEvidence::code_point(self : ScalarReadingEvidence) -> Int

    ScalarReadingEvidence::is_ambiguous

    fn ScalarReadingEvidence::is_ambiguous(self : ScalarReadingEvidence) -> Bool

    ScalarReadingEvidence::is_known

    fn ScalarReadingEvidence::is_known(self : ScalarReadingEvidence) -> Bool

    ScalarReadingEvidence::original

    fn ScalarReadingEvidence::original(self : ScalarReadingEvidence) -> String

    ScalarReadingEvidence::span

    SearchDocument

    type SearchDocument

    SearchHit

    pub struct SearchHit {
    identifier_value : String
    source_value : String
    explanation_value : MatchExplanation
    source_position : Int
    } derive(Eq,
    Debug
    )

    One ranked hit with source text and score evidence.

    SearchHit::explanation

    fn SearchHit::explanation(self : SearchHit) -> MatchExplanation

    SearchHit::identifier

    fn SearchHit::identifier(self : SearchHit) -> String

    SearchHit::original_position

    fn SearchHit::original_position(self : SearchHit) -> Int

    SearchHit::score

    fn SearchHit::score(self : SearchHit) -> Double

    SearchHit::source

    fn SearchHit::source(self : SearchHit) -> String

    SearchIndex

    pub struct SearchIndex {
    document_values : Array[SearchDocument]
    }

    Immutable collection of precomputed Pinyin match candidates.

    SearchIndex::length

    fn SearchIndex::length(self : SearchIndex) -> Int

    SearchIndex::search

    fn SearchIndex::search(self : SearchIndex, query : String, options : SearchOptions, profile : FuzzyProfile) -> Result[Array[SearchHit], PinyinError]

    Queries precomputed candidates with stable caller-order tie breaking.

    SearchIndexBuilder

    pub struct SearchIndexBuilder {
    document_values : Array[SearchDocument]
    }

    Mutable validated builder for a reusable search index.

    SearchIndexBuilder::add

    fn SearchIndexBuilder::add(self : SearchIndexBuilder, identifier : String, source : String, lexicon : Lexicon, options : ConvertOptions) -> Result[Unit, PinyinError]

    Converts and precomputes one document before inserting it.

    SearchIndexBuilder::build

    Freezes the current insertion order into an immutable index.

    SearchIndexBuilder::length

    fn SearchIndexBuilder::length(self : SearchIndexBuilder) -> Int

    SearchIndexBuilder::new

    SearchOptions

    pub struct SearchOptions {
    limit_value : Int
    minimum_score_value : Double
    } derive(Eq,
    Debug
    )

    Query limits and minimum accepted score.

    SearchOptions::limit

    fn SearchOptions::limit(self : SearchOptions) -> Int

    SearchOptions::minimum_score

    fn SearchOptions::minimum_score(self : SearchOptions) -> Double

    SourceSpan

    pub struct SourceSpan {
    start_offset : Int
    end_offset : Int
    } derive(Eq,
    Debug
    )

    Half-open character offsets in the caller's source text.

    SourceSpan::end

    fn SourceSpan::end(self : SourceSpan) -> Int

    SourceSpan::length

    fn SourceSpan::length(self : SourceSpan) -> Int

    SourceSpan::start

    fn SourceSpan::start(self : SourceSpan) -> Int

    Syllable

    pub struct Syllable {
    base_value : String
    initial_value : String
    final_value : String
    tone_value : Int
    input_form : Orthography
    } derive(Eq,
    Debug
    )

    A validated Pinyin syllable in canonical lowercase form.

    Syllable::final_part

    fn Syllable::final_part(self : Syllable) -> String

    Syllable::format

    fn Syllable::format(self : Syllable, style : ToneStyle, text_case : TextCase) -> String

    Syllable::initial

    fn Syllable::initial(self : Syllable) -> String

    Syllable::orthography

    fn Syllable::orthography(self : Syllable) -> Orthography

    Syllable::plain

    fn Syllable::plain(self : Syllable) -> String

    Syllable::tone_number

    fn Syllable::tone_number(self : Syllable) -> Int

    TextCase

    pub(all) enum TextCase {
    Lowercase
    Uppercase
    } derive(Eq,
    Debug
    )

    Controls casing after a syllable has been normalized.

    TextComparison

    pub struct TextComparison {
    left_result : ConversionResult
    right_result : ConversionResult
    left_key_value : String
    right_key_value : String
    left_initials_value : String
    right_initials_value : String
    distance_value : DistanceResult
    similarity_value : Double
    forward_score_value : MatchExplanation
    reverse_score_value : MatchExplanation
    } derive(Eq,
    Debug
    )

    Symmetric key comparison plus both original conversion results.

    TextComparison::distance

    TextComparison::forward_score

    fn TextComparison::forward_score(self : TextComparison) -> MatchExplanation

    TextComparison::left_conversion

    fn TextComparison::left_conversion(self : TextComparison) -> ConversionResult

    TextComparison::left_initials

    fn TextComparison::left_initials(self : TextComparison) -> String

    TextComparison::left_key

    fn TextComparison::left_key(self : TextComparison) -> String

    TextComparison::reverse_score

    fn TextComparison::reverse_score(self : TextComparison) -> MatchExplanation

    TextComparison::right_conversion

    fn TextComparison::right_conversion(self : TextComparison) -> ConversionResult

    TextComparison::right_initials

    fn TextComparison::right_initials(self : TextComparison) -> String

    TextComparison::right_key

    fn TextComparison::right_key(self : TextComparison) -> String

    TextComparison::same_full_pinyin

    fn TextComparison::same_full_pinyin(self : TextComparison) -> Bool

    TextComparison::same_initials

    fn TextComparison::same_initials(self : TextComparison) -> Bool

    TextComparison::similarity

    fn TextComparison::similarity(self : TextComparison) -> Double

    TokenKind

    pub(all) enum TokenKind {
    PinyinToken
    LiteralToken
    } derive(Eq,
    Debug
    )

    ToneStyle

    pub(all) enum ToneStyle {
    ToneMarks
    ToneNumbers
    PlainPinyin
    } derive(Eq,
    Debug
    )

    Selects the rendered representation of a Pinyin syllable.

    UnknownPolicy

    pub(all) enum UnknownPolicy {
    PreserveUnknown
    DropUnknown
    RejectUnknown
    } derive(Eq,
    Debug
    )

    Controls how text without a known Pinyin reading is handled.

    VariantExpansion

    pub struct VariantExpansion {
    variant_values : Array[String]
    truncated_value : Bool
    } derive(Eq,
    Debug
    )

    Bounded candidate strings produced from recorded token readings.

    VariantExpansion::generated

    fn VariantExpansion::generated(self : VariantExpansion) -> Int

    VariantExpansion::truncated

    fn VariantExpansion::truncated(self : VariantExpansion) -> Bool

    VariantExpansion::values

    fn VariantExpansion::values(self : VariantExpansion) -> Array[String]

    align_pinyin

    fn align_pinyin(left_input : String, right_input : String, profile : FuzzyProfile) -> PinyinAlignment

    Aligns two normalized Pinyin inputs with deterministic edit evidence.

    analyze_conversion

    fn analyze_conversion(result : ConversionResult) -> ConversionStats

    Summarizes token decisions without rerunning conversion.

    batch_item

    fn batch_item(identifier : String, source : String) -> Result[BatchItem, PinyinError]

    batch_report_json

    fn batch_report_json(result : BatchResult) -> String

    Produces stable compact JSON using a structured encoder.

    batch_report_text

    fn batch_report_text(result : BatchResult) -> String

    Produces a stable line-oriented report in caller input order.

    code_points_text

    fn code_points_text(values : Array[Int]) -> String

    Encodes Unicode scalar values as MoonBit strings.

    compare_texts

    fn compare_texts(left_source : String, right_source : String, lexicon : Lexicon, options : ConvertOptions, profile : FuzzyProfile) -> Result[TextComparison, PinyinError]

    Converts and compares two texts with the same explicit configuration.

    conversion_report_json

    fn conversion_report_json(result : ConversionResult) -> String

    Emits conversion tokens, decisions, candidates, spans, and diagnostics.

    convert_batch

    fn convert_batch(items : Array[BatchItem], lexicon : Lexicon, options : ConvertOptions) -> BatchResult

    Converts all items without short-circuiting after an item failure.

    convert_options

    fn convert_options(style : ToneStyle, separator : String, text_case : TextCase, unknown_policy : UnknownPolicy, ambiguity_policy : AmbiguityPolicy) -> Result[ConvertOptions, PinyinError]

    Builds a validated conversion configuration.

    convert_text

    fn convert_text(source : String, lexicon : Lexicon, options : ConvertOptions) -> Result[ConversionResult, PinyinError]

    Converts mixed text using phrase overrides before Unicode character lookup.

    default_convert_options

    fn default_convert_options() -> ConvertOptions

    Returns conservative display defaults without hiding ambiguity metadata.

    default_fuzzy_profile

    fn default_fuzzy_profile() -> FuzzyProfile

    default_fuzzy_rules

    fn default_fuzzy_rules() -> FuzzyRules

    default_pinyin_processor

    fn default_pinyin_processor() -> PinyinProcessor

    default_search_options

    fn default_search_options() -> SearchOptions

    diagnostic

    fn diagnostic(code : String, message : String, span : SourceSpan?) -> Diagnostic

    Creates a structured diagnostic without interpreting its message.

    expand_conversion_variants

    fn expand_conversion_variants(result : ConversionResult, style : ToneStyle, separator : String, limit : Int) -> Result[VariantExpansion, PinyinError]

    Expands recorded alternatives without performing contextual inference.

    fuzzy_profile

    fn fuzzy_profile(insertion : Double, deletion : Double, substitution : Double, equivalence : Double) -> Result[FuzzyProfile, PinyinError]

    Builds a profile with the standard Pinyin equivalence groups enabled.

    fuzzy_profile_with_rules

    fn fuzzy_profile_with_rules(insertion : Double, deletion : Double, substitution : Double, equivalence : Double, rules : FuzzyRules) -> Result[FuzzyProfile, PinyinError]

    Builds a profile with caller-selected Pinyin equivalence groups.

    fuzzy_rules

    fn fuzzy_rules(zh_z : Bool, ch_c : Bool, sh_s : Bool, n_l : Bool) -> FuzzyRules

    generate_index_key

    fn generate_index_key(converted : ConversionResult, profile : IndexProfile) -> IndexKey

    Generates a deterministic search key from an existing conversion result.

    inspect_text_readings

    fn inspect_text_readings(source : String) -> ReadingInspection

    Inspects Unicode readings without applying phrase or ambiguity policies.

    lexicon_from_text

    fn lexicon_from_text(text : String) -> Result[Lexicon, PinyinError]

    Imports the stable text format through the same LexiconBuilder validation.

    lexicon_to_text

    fn lexicon_to_text(lexicon : Lexicon) -> String

    Exports entries in stable insertion order for reviewable configuration.

    lookup_readings

    fn lookup_readings(code_point : Int) -> ReadingSet?

    Finds a sorted code point in the generated Unicode table.

    match_candidate

    fn match_candidate(label : String, converted : ConversionResult) -> MatchCandidate

    Builds search representations once for repeated queries.

    package_version

    fn package_version() -> String

    Return the package release version.

    parse_syllable

    fn parse_syllable(input : String) -> Result[Syllable, PinyinError]

    Parses plain, numbered, or precomposed tone-mark Pinyin.

    pinyin_processor

    fn pinyin_processor(lexicon : Lexicon, options : ConvertOptions, fuzzy : FuzzyProfile) -> PinyinProcessor

    rank_matches

    fn rank_matches(query : String, candidates : Array[MatchCandidate], profile : FuzzyProfile) -> Array[RankedCandidate]

    Ranks candidates by descending score and preserves caller order for ties.

    reading_inspection_report_json

    fn reading_inspection_report_json(inspection : ReadingInspection) -> String

    Emits source coverage and per-scalar Unicode reading candidates.

    score_match

    fn score_match(query_input : String, candidate : MatchCandidate, profile : FuzzyProfile) -> MatchExplanation

    Scores one candidate and returns independently inspectable components.

    search_hits_report_json

    fn search_hits_report_json(query : String, hits : Array[SearchHit]) -> String

    Emits ranked hits and all score components in stable order.

    search_options

    fn search_options(limit : Int, minimum_score : Double) -> Result[SearchOptions, PinyinError]

    select_reading

    fn select_reading(code_point : Int, policy : AmbiguityPolicy) -> Result[String, PinyinError]

    Selects a reading while making the ambiguity policy observable.

    source_span

    fn source_span(start : Int, end : Int) -> Result[SourceSpan, PinyinError]

    Creates a validated half-open source span.

    text_code_points

    fn text_code_points(text : String) -> Array[Int]

    Decodes UTF-16 storage into Unicode scalar values, preserving unpaired units.

    unihan_data_license

    fn unihan_data_license() -> String

    SPDX identifier governing bundled generated Unicode data.

    unihan_entry_total

    fn unihan_entry_total() -> Int

    Number of code points with at least one selected reading.

    unihan_source_sha256

    fn unihan_source_sha256() -> String

    SHA-256 of the exact official Unihan source archive.

    unihan_version

    fn unihan_version() -> String

    Unicode release used to generate the bundled reading tables.

    validate_conversion_result

    fn validate_conversion_result(result : ConversionResult) -> Result[ConversionIntegrity, PinyinError]

    Validates spans, token decisions, and candidate syllables without rerunning conversion.

    validate_pinyin_alignment

    fn validate_pinyin_alignment(alignment : PinyinAlignment, profile : FuzzyProfile) -> Result[AlignmentIntegrity, PinyinError]

    Validates path continuity, fragments, enabled rules, costs, and counters.

    validate_unihan_dataset

    fn validate_unihan_dataset() -> Result[DatasetStats, PinyinError]

    Validates every bundled code point and reading, then returns dataset facts.

    weighted_pinyin_distance

    fn weighted_pinyin_distance(left_input : String, right_input : String, profile : FuzzyProfile) -> DistanceResult

    Computes weighted Levenshtein distance with optional Pinyin initial rules.