pinyin

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 17, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package pinyin converts Chinese characters to pinyin readings.

It is a pure-Go port of the getpinyin.c library, covering the entire CJK Unified Ideographs basic block (U+4E00–U+9FA5, 20,812 characters). Multi-tone characters (多音字) are supported: all readings are stored and can be retrieved individually or flattened.

Basic usage:

// Simple conversion (first reading per character)
fmt.Println(pinyin.Convert("你好世界"))
// Output: ni hao shi jie

// Keep non-Chinese characters
fmt.Println(pinyin.Convert("Hello世界", pinyin.WithKeepNonCJK(true)))
// Output: Hello shi jie

// Get all readings for multi-tone characters
for _, readings := range pinyin.ConvertAll("重庆") {
    fmt.Println(readings)
}
// [chong]
// [qing]

// Single character lookup
fmt.Println(pinyin.Pinyin('乐'))  // "le luo yao yue"
fmt.Println(pinyin.PinyinFirst('乐'))  // "le"

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Convert

func Convert(s string, opts ...Option) string

Convert converts a Chinese string to pinyin. Each Chinese character is replaced by its first pinyin reading; non-Chinese characters are dropped unless WithKeepNonCJK(true) is set. Consecutive non-CJK characters are kept as a single group. Readings are separated by a space (configurable via WithSeparator).

func ConvertAll

func ConvertAll(s string, opts ...Option) [][]string

ConvertAll converts a Chinese string to pinyin, returning all possible readings for each character. Non-Chinese characters produce a single-element slice containing the character itself (if WithKeepNonCJK is true) or are skipped.

func ConvertSlice

func ConvertSlice(s string, opts ...Option) []string

ConvertSlice converts a Chinese string to a slice of pinyin readings, one element per character (using the first reading for multi-tone chars). Non-Chinese characters are skipped unless WithKeepNonCJK is true, in which case consecutive non-CJK characters are grouped into a single element.

func Count

func Count() int

Count returns the number of characters in the data set.

func HasPinyin

func HasPinyin(r rune) bool

HasPinyin reports whether the character has a known pinyin reading.

func IsCJK

func IsCJK(r rune) bool

IsCJK reports whether r is in the CJK Unified Ideographs basic block (U+4E00–U+9FA5).

func Pinyin

func Pinyin(r rune) string

Pinyin returns all pinyin readings for a single Chinese character, separated by spaces. Returns empty string for non-CJK characters.

func PinyinAll

func PinyinAll(r rune) []string

PinyinAll returns all pinyin readings as a slice for a character. Returns nil for non-CJK characters.

func PinyinFirst

func PinyinFirst(r rune) string

PinyinFirst returns the first (primary) pinyin reading for a character. Returns empty string for non-CJK characters.

Types

type Option

type Option func(*config)

Option configures Convert / ConvertAll behavior.

func WithAllTones

func WithAllTones(all bool) Option

WithAllTones makes Convert return all readings for multi-tone characters (joined by the separator), instead of just the first reading.

func WithHyphenSeparator

func WithHyphenSeparator() Option

WithHyphenSeparator is a shortcut for WithSeparator("-").

func WithKeepNonCJK

func WithKeepNonCJK(keep bool) Option

WithKeepNonCJK keeps non-Chinese characters (letters, digits, punctuation) in the output instead of dropping them.

func WithNoSeparator

func WithNoSeparator() Option

WithNoSeparator is a shortcut for WithSeparator("").

func WithSeparator

func WithSeparator(sep string) Option

WithSeparator sets the separator between pinyin readings. Default is a single space.

func WithTitleCase

func WithTitleCase(title bool) Option

WithTitleCase converts pinyin output to title case (first letter uppercase).

func WithUnderscoreSeparator

func WithUnderscoreSeparator() Option

WithUnderscoreSeparator is a shortcut for WithSeparator("_").

func WithUppercase

func WithUppercase(upper bool) Option

WithUppercase converts all pinyin output to uppercase.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL