Utility Functions

/**
 * Compare two Chinese strings by their Pinyin pronunciation
 * @param hanA - First Chinese string to compare
 * @param hanB - Second Chinese string to compare  
 * @returns -1 if hanA < hanB, 0 if equal, 1 if hanA > hanB (lexicographic order)
 */
function compare(hanA: string, hanB: string): number;

import pinyin, { compare } from "pinyin";

// Basic comparison
console.log(compare("北京", "上海"));
// Result: -1 (Beijing comes before Shanghai alphabetically in Pinyin)

console.log(compare("你好", "你好"));
// Result: 0 (identical strings)

console.log(compare("中国", "美国"));
// Result: 1 (China comes after America alphabetically in Pinyin)

// Sorting Chinese strings by Pinyin
const cities = ["北京", "上海", "广州", "深圳", "杭州"];
cities.sort(compare);
console.log(cities);
// Result: ["北京", "广州", "杭州", "上海", "深圳"] (sorted by Pinyin)

// Using with Array.sort for complex data
const users = [
  { name: "王小明", age: 25 },
  { name: "李小红", age: 30 },
  { name: "陈大华", age: 28 }
];

users.sort((a, b) => compare(a.name, b.name));
console.log(users.map(u => u.name));
// Result: Names sorted by Pinyin pronunciation

/**
 * Compact multi-dimensional Pinyin arrays into all possible combinations
 * @param arr - Multi-dimensional array of Pinyin pronunciations
 * @returns Array of arrays containing all possible pronunciation combinations
 */
function compact(arr: string[][]): string[][];

import { compact } from "pinyin";

// Basic compacting
const pinyinResult = [["nǐ"], ["hǎo", "hào"], ["ma", "má", "mǎ"]];
console.log(compact(pinyinResult));
// Result: [
//   ["nǐ", "hǎo", "ma"], ["nǐ", "hǎo", "má"], ["nǐ", "hǎo", "mǎ"],
//   ["nǐ", "hào", "ma"], ["nǐ", "hào", "má"], ["nǐ", "hào", "mǎ"]
// ]

// Single pronunciation per character
const simple = [["zhōng"], ["xīn"]];
console.log(compact(simple));
// Result: [["zhōng", "xīn"]]

// Empty or single arrays
console.log(compact([]));
// Result: []

console.log(compact([["hello"]]));
// Result: [["hello"]]

import pinyin from "pinyin";

// Using compact option in main function
console.log(pinyin("你好吗", { 
  heteronym: true, 
  compact: true 
}));
// Same result as: compact(pinyin("你好吗", { heteronym: true }))

import { compare } from "pinyin";

// Sort function for Chinese names
function sortChineseNames(names: string[]): string[] {
  return names.slice().sort(compare);
}

// Sort objects by Chinese property
function sortByChineseName<T extends { name: string }>(items: T[]): T[] {
  return items.slice().sort((a, b) => compare(a.name, b.name));
}

// Usage
const names = ["张三", "李四", "王五", "赵六"];
console.log(sortChineseNames(names));

const products = [
  { name: "苹果", price: 5 },
  { name: "香蕉", price: 3 },
  { name: "橙子", price: 4 }
];
console.log(sortByChineseName(products));

import pinyin, { compact } from "pinyin";

function getAllPronunciations(text: string): string[][] {
  const pinyinResult = pinyin(text, { heteronym: true });
  return compact(pinyinResult);
}

// Find all ways to pronounce ambiguous text
const combinations = getAllPronunciations("中行");
console.log(combinations);
// Result: [["zhōng", "háng"], ["zhōng", "xíng"], ["zhòng", "háng"], ["zhòng", "xíng"]]

// Count pronunciation variations
function countPronunciations(text: string): number {
  return getAllPronunciations(text).length;
}

console.log(countPronunciations("中行"));  // 4 combinations
console.log(countPronunciations("你好"));  // 1 combination (no ambiguity)

import pinyin, { compare } from "pinyin";

// Create search index with Pinyin
function createSearchIndex(texts: string[]) {
  return texts.map(text => ({
    original: text,
    pinyin: pinyin(text, { style: "normal" }).flat().join(""),
    pinyinTones: pinyin(text).flat().join("")
  }));
}

// Binary search in sorted Chinese text
function binarySearchChinese(sortedArray: string[], target: string): number {
  let left = 0;
  let right = sortedArray.length - 1;
  
  while (left <= right) {
    const mid = Math.floor((left + right) / 2);
    const comparison = compare(sortedArray[mid], target);
    
    if (comparison === 0) return mid;
    if (comparison < 0) left = mid + 1;
    else right = mid - 1;
  }
  
  return -1;
}

// Usage
const sortedCities = ["北京", "广州", "杭州", "上海", "深圳"];
console.log(binarySearchChinese(sortedCities, "杭州")); // Returns index

// Efficient for one-time comparisons
compare("北京", "上海");

// For sorting large arrays, consider pre-computing Pinyin
const items = ["北京", "上海", "广州", "深圳"];

// Less efficient - computes Pinyin repeatedly
items.sort(compare);

// More efficient for large datasets - pre-compute Pinyin
const itemsWithPinyin = items.map(item => ({
  original: item,
  pinyin: pinyin(item).flat().join("")
}));

itemsWithPinyin.sort((a, b) => a.pinyin.localeCompare(b.pinyin));
const sorted = itemsWithPinyin.map(item => item.original);

// Small number of combinations
compact([["a"], ["b", "c"]]);  // 2 combinations

// Large number of combinations - use carefully
compact([["a", "b"], ["c", "d"], ["e", "f"], ["g", "h"]]);  // 16 combinations

// Very large - consider memory impact
const manyOptions = Array(5).fill(["a", "b", "c", "d"]);
compact(manyOptions);  // 1024 combinations!