### Implementing Custom PinyinMapDict in Java

Source: https://context7.com/promeg/tinypinyin/llms.txt

Demonstrates how to create a custom dictionary by extending PinyinMapDict and implementing the mapping() method to provide word-to-pinyin mappings. Includes examples for basic usage and loading from a file.

```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinMapDict;
import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// 基本用法
PinyinMapDict cityDict = new PinyinMapDict() {
    @Override
    public Map<String, String[]> mapping() {
        HashMap<String, String[]> map = new HashMap<>();
        // Key: 词语, Value: 拼音数组（每个字一个元素）
        map.put("重庆", new String[]{"CHONG", "QING"});
        map.put("厦门", new String[]{"XIA", "MEN"});
        map.put("六安", new String[]{"LU", "AN"});
        return map;
    }
};

Pinyin.init(Pinyin.newConfig().with(cityDict));

// 测试结果
String result1 = Pinyin.toPinyin("重庆市", " ");  // 返回 "CHONG QING SHI"
String result2 = Pinyin.toPinyin("厦门大学", " ");  // 返回 "XIA MEN DA XUE"

// 从文件加载词典
public class FilePinyinDict extends PinyinMapDict {
    private Map<String, String[]> dict = new HashMap<>();

    public FilePinyinDict(String filePath) {
        // 从文件加载词典
        // 文件格式: CHONG'QING 重庆 (拼音用'分隔，拼音和词用空格分隔)
        try (BufferedReader reader = new BufferedReader(new FileReader(filePath))) {
            String line;
            while ((line = reader.readLine()) != null) {
                String[] parts = line.split("\\s+");
                if (parts.length == 2) {
                    String[] pinyins = parts[0].split("'");
                    dict.put(parts[1], pinyins);
                }
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Override
    public Map<String, String[]> mapping() {
        return dict;
    }
}
```

--------------------------------

### Append Custom Dictionaries with Pinyin.add

Source: https://context7.com/promeg/tinypinyin/llms.txt

Demonstrates how to add custom word-to-pinyin mappings to an existing TinyPinyin configuration. This method allows for dynamic dictionary updates after initial setup.

```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinMapDict;
import java.util.HashMap;
import java.util.Map;

Pinyin.init(Pinyin.newConfig()
    .with(new PinyinMapDict() {
        @Override
        public Map<String, String[]> mapping() {
            HashMap<String, String[]> map = new HashMap<>();
            map.put("重庆", new String[]{"CHONG", "QING"});
            return map;
        }
    }));

Pinyin.add(new PinyinMapDict() {
    @Override
    public Map<String, String[]> mapping() {
        HashMap<String, String[]> map = new HashMap<>();
        map.put("长安", new String[]{"CHANG", "AN"});
        map.put("单于", new String[]{"CHAN", "YU"});
        return map;
    }
});

String result1 = Pinyin.toPinyin("重庆", " ");
String result2 = Pinyin.toPinyin("长安", " ");
String result3 = Pinyin.toPinyin("单于", " ");
```

--------------------------------

### Creating Custom Android Asset Dictionaries

Source: https://context7.com/promeg/tinypinyin/llms.txt

Explains how to create a custom dictionary for Android applications by extending AndroidAssetDict and specifying an asset file. The format of the asset file is detailed, along with an example of a custom dictionary implementation.

```java
import com.github.promeg.tinypinyin.android.asset.lexicons.AndroidAssetDict;
import android.content.Context;
import java.util.Map;

// 自定义 Asset 词典
public class MyAssetDict extends AndroidAssetDict {

    private static volatile MyAssetDict singleton = null;

    private MyAssetDict(Context context) {
        super(context);
    }

    @Override
    protected String assetFileName() {
        // 返回 assets 目录下的文件名
        return "my_dictionary.txt";
    }

    public static MyAssetDict getInstance(Context context) {
        if (context == null) {
            throw new IllegalArgumentException("context == null");
        }
        if (singleton == null) {
            synchronized (MyAssetDict.class) {
                if (singleton == null) {
                    singleton = new MyAssetDict(context);
                }
            }
        }
        return singleton;
    }
}

// assets/my_dictionary.txt 文件格式示例:
// CHONG'QING 重庆
// XIA'MEN 厦门
// CHANG'AN 长安
// LU'AN 六安

// 使用自定义词典
Pinyin.init(Pinyin.newConfig()
    .with(MyAssetDict.getInstance(context)));
```

--------------------------------

### Using Built-in CnCityDict for Chinese City Names (Java & Android)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Utilizes the pre-built CnCityDict for accurate pinyin conversion of Chinese city names. Provides initialization examples for both Java and Android environments, including Gradle dependencies.

```java
// ========== Java 版本 ==========
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.tinypinyin.lexicons.java.cncity.CnCityDict;

// 添加 Gradle 依赖
// compile 'com.github.promeg:tinypinyin-lexicons-java-cncity:2.0.3'

// 初始化（单例模式）
Pinyin.init(Pinyin.newConfig().with(CnCityDict.getInstance()));

// 测试城市名拼音
String result1 = Pinyin.toPinyin("重庆", " ");    // 返回 "CHONG QING"
String result2 = Pinyin.toPinyin("厦门", " ");    // 返回 "XIA MEN"
String result3 = Pinyin.toPinyin("六安", " ");    // 返回 "LU AN"
String result4 = Pinyin.toPinyin("大埔", " ");    // 返回 "DA BU"

// ========== Android 版本 ==========
import com.github.promeg.tinypinyin.lexicons.android.cncity.CnCityDict;
import android.content.Context;

// 添加 Gradle 依赖
// compile 'com.github.promeg:tinypinyin-lexicons-android-cncity:2.0.3'

// 在 Activity 或 Application 中初始化
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // 使用 Context 初始化
        Pinyin.init(Pinyin.newConfig()
            .with(CnCityDict.getInstance(getApplicationContext())));
    }
}

// 之后可以正常使用
String cityPinyin = Pinyin.toPinyin("重庆市", " ");
```

--------------------------------

### Initialize and Use Custom Dictionaries (Java)

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Demonstrates how to initialize TinyPinyin with custom dictionaries, including pre-built city dictionaries and user-defined mappings for handling multi-tone characters. This allows for more accurate and context-aware Pinyin conversion.

```Java
// Add Chinese city dictionary
Pinyin.init(Pinyin.newConfig().with(CnCityDict.getInstance());

// Add custom dictionary
Pinyin.init(Pinyin.newConfig()
            .with(new PinyinMapDict() {
                @Override
                public Map<String, String[]> mapping() {
                    HashMap<String, String[]> map = new HashMap<String, String[]>();
                    map.put("重庆",  new String[]{"CHONG", "QING"});
                    return map;
                }
            }));
```

--------------------------------

### TinyPinyin Integration and Usage

Source: https://context7.com/promeg/tinypinyin/llms.txt

This section details the typical integration pattern for TinyPinyin, including initialization and basic conversion.

```APIDOC
## Initialization and Basic Usage

### Description
This outlines the typical integration pattern for TinyPinyin, including initialization with dictionaries and performing basic Pinyin conversion.

### Method
`Pinyin.init(Context context, String... dictPaths)` and `Pinyin.toPinyin(String text)`

### Endpoint
N/A (Library usage)

### Parameters
#### Initialization Parameters
- **context** (Context) - Required - The Android application context.
- **dictPaths** (String...) - Optional - Paths to custom dictionaries to load.

#### `toPinyin` Parameters
- **text** (String) - Required - The Chinese text to convert to Pinyin.

### Request Example
```java
// Initialize with default dictionaries
Pinyin.init(this);

// Initialize with custom dictionaries
Pinyin.init(this, "path/to/my/dict.txt");

// Convert Chinese text to Pinyin
String pinyin = Pinyin.toPinyin("你好世界"); // Output: ni hao shi jie
```

### Response
#### Success Response (String)
- **pinyin** (String) - The converted Pinyin string.

#### Response Example
```
ni hao shi jie
```
```

--------------------------------

### Run Unit and Integration Tests (Gradle)

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Provides the Gradle command to execute various tests for TinyPinyin, including unit tests for the core library, lexicon modules, and Android integration tests. This ensures the correctness and functionality of the library.

```Groovy
./gradlew clean build :lib:test :tinypinyin-lexicons-android-cncity:test :tinypinyin-android-asset-lexicons:test :android-sample:connectedAndroidTest
```

--------------------------------

### Pinyin.init(Config config)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Initializes the Pinyin library with a configuration object, allowing for custom dictionary injection.

```APIDOC
## METHOD Pinyin.init(Config config)

### Description
Configures the library with custom dictionaries for polyphonic character resolution. Dictionaries are prioritized in the order they are added.

### Parameters
#### Parameters
- **config** (Config) - Required - The configuration object containing dictionary mappings.

### Example
```java
Pinyin.init(Pinyin.newConfig().with(CnCityDict.getInstance()));
```
```

--------------------------------

### Initialize and Configure Dictionaries

Source: https://context7.com/promeg/tinypinyin/llms.txt

Configures TinyPinyin with custom dictionaries or built-in modules to handle polyphonic characters correctly. Dictionaries are processed in the order they are added.

```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinMapDict;
import java.util.HashMap;
import java.util.Map;

Pinyin.init(Pinyin.newConfig()
    .with(new PinyinMapDict() {
        @Override
        public Map<String, String[]> mapping() {
            HashMap<String, String[]> map = new HashMap<>();
            map.put("重庆", new String[]{"CHONG", "QING"});
            return map;
        }
    }));
```

--------------------------------

### Initialize TinyPinyin with Dictionary (Java)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Initializes the TinyPinyin library with a specified dictionary, such as CnCityDict. This is typically done at application startup to prepare for Pinyin conversions. Ensure the dictionary is available and correctly configured.

```java
Pinyin.init(Pinyin.Dict.CN);
// Or with a custom dictionary:
Pinyin.init(new CnCityDict());
```

--------------------------------

### Implement Custom Dictionary via PinyinDict Interface

Source: https://context7.com/promeg/tinypinyin/llms.txt

Explains how to create a custom dictionary by implementing the PinyinDict interface, providing full control over word definitions and their corresponding pinyin arrays.

```java
import com.github.promeg.pinyinhelper.PinyinDict;
import java.util.Set;
import java.util.HashSet;

public class CustomDict implements PinyinDict {
    @Override
    public Set<String> words() {
        Set<String> wordSet = new HashSet<>();
        wordSet.add("重庆");
        wordSet.add("长安");
        return wordSet;
    }

    @Override
    public String[] toPinyin(String word) {
        switch (word) {
            case "重庆":
                return new String[]{"CHONG", "QING"};
            case "长安":
                return new String[]{"CHANG", "AN"};
            default:
                return null;
        }
    }
}

Pinyin.init(Pinyin.newConfig().with(new CustomDict()));
String result = Pinyin.toPinyin("重庆长安", " ");
```

--------------------------------

### Run Performance Benchmarks (Gradle)

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Details the Gradle command to run JMH benchmarks for TinyPinyin, comparing its performance against Pinyin4J for character-to-Pinyin conversion, string-to-Pinyin conversion, and Chinese character detection. The results are generated in a report.

```Groovy
./gradlew jmh
```

--------------------------------

### Dictionary Configuration API

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Methods for initializing the Pinyin engine with custom or pre-built dictionaries.

```APIDOC
## Dictionary Configuration API

### Description
Allows the configuration of the Pinyin engine by injecting custom dictionaries or pre-built city dictionaries to improve accuracy for specific terms or polyphonic characters.

### Method
- `Pinyin.init(PinyinConfig config)`

### Parameters
#### Request Body
- **config** (PinyinConfig) - Required - Configuration object built using `Pinyin.newConfig()`.

### Request Example
```java
// Adding a custom dictionary
Pinyin.init(Pinyin.newConfig()
            .with(new PinyinMapDict() {
                @Override
                public Map<String, String[]> mapping() {
                    HashMap<String, String[]> map = new HashMap<String, String[]>();
                    map.put("重庆",  new String[]{"CHONG", "QING"});
                    return map;
                }
            }));
```

### Response
#### Success Response (void)
- **Status** (void) - Initializes the static Pinyin engine with the provided dictionary configuration.
```

--------------------------------

### Add TinyPinyin Dependency to Project (Gradle)

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Shows how to include the TinyPinyin library and its optional lexicon modules in a Java or Android project using Gradle. It specifies repositories and lists the core package and lexicon dependencies.

```Groovy
buildscript {
  repositories {
    maven {
      url 'https://maven.aliyun.com/repository/public'
    }
    mavenCentral()
  }

  dependencies {
    compile 'com.github.promeg:tinypinyin:2.0.3' // TinyPinyin core package, approx. 80KB

    compile 'com.github.promeg:tinypinyin-lexicons-android-cncity:2.0.3' // Optional, Chinese city dictionary for Android

    compile 'com.github.promeg:tinypinyin-lexicons-java-cncity:2.0.3' // Optional, Chinese city dictionary for Java
  }
}
```

--------------------------------

### Override Pinyin with PinyinRules

Source: https://context7.com/promeg/tinypinyin/llms.txt

Shows how to use PinyinRules to apply temporary, high-priority pinyin overrides for specific characters or strings without modifying the global dictionary.

```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinRules;

String default1 = Pinyin.toPinyin('嗯');
PinyinRules rules = new PinyinRules().add('嗯', "EN");
String custom1 = Pinyin.toPinyin('嗯', rules);

String default2 = Pinyin.toPinyin("长春", "");
PinyinRules cityRules = new PinyinRules().add("长春", "CHANGCHUN");
String custom2 = Pinyin.toPinyin("长春", "", cityRules);

PinyinRules multiRules = new PinyinRules()
    .add('嗯', "EN")
    .add("重庆", "CHONGQING")
    .add("长春", "CHANGCHUN");

String rulesResult = Pinyin.toPinyin("重庆", "", new PinyinRules().add("重庆", "CHONGQING"));
```

--------------------------------

### Pinyin.add(PinyinDict dict) - Append Dictionary

Source: https://context7.com/promeg/tinypinyin/llms.txt

Appends a dictionary to the initialized Pinyin instance. For multiple dictionaries, it's recommended to use Pinyin.init(Config) for better performance.

```APIDOC
## Pinyin.add(PinyinDict dict) - Append Dictionary

### Description
Appends a dictionary to the initialized Pinyin instance. For multiple dictionaries, it's recommended to use `Pinyin.init(Config)` for better performance.

### Method
```java
Pinyin.add(PinyinDict dict)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dict** (PinyinDict) - Required - The dictionary to append.

### Request Example
```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinMapDict;
import java.util.HashMap;
import java.util.Map;

// Initialize with a base dictionary
Pinyin.init(Pinyin.newConfig()
    .with(new PinyinMapDict() {
        @Override
        public Map<String, String[]> mapping() {
            HashMap<String, String[]> map = new HashMap<>();
            map.put("重庆", new String[]{"CHONG", "QING"});
            return map;
        }
    }));

// Append a new dictionary
Pinyin.add(new PinyinMapDict() {
    @Override
    public Map<String, String[]> mapping() {
        HashMap<String, String[]> map = new HashMap<>();
        map.put("长安", new String[]{"CHANG", "AN"});
        map.put("单于", new String[]{"CHAN", "YU"});
        return map;
    }
});

// Test results
String result1 = Pinyin.toPinyin("重庆", " ");  // Returns "CHONG QING"
String result2 = Pinyin.toPinyin("长安", " ");  // Returns "CHANG AN"
String result3 = Pinyin.toPinyin("单于", " ");  // Returns "CHAN YU"
```

### Response
This method does not return a value directly but modifies the internal state of the Pinyin instance.

#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Convert Single Character to Pinyin

Source: https://context7.com/promeg/tinypinyin/llms.txt

Demonstrates converting individual characters to uppercase Pinyin. Non-Chinese characters are returned as-is, and the method can be used to extract initials from strings.

```java
import com.github.promeg.pinyinhelper.Pinyin;

String pinyin1 = Pinyin.toPinyin('中');  // "ZHONG"
String result1 = Pinyin.toPinyin('A');   // "A"

public static String getFirstLetters(String chinese) {
    StringBuilder sb = new StringBuilder();
    for (char c : chinese.toCharArray()) {
        if (Pinyin.isChinese(c)) {
            sb.append(Pinyin.toPinyin(c).charAt(0));
        }
    }
    return sb.toString();
}
```

--------------------------------

### Handle Multi-syllable Words with Custom Rules (Java)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Provides mechanisms to handle special cases of multi-syllable words by adding custom dictionaries or temporarily overriding rules. This ensures accurate Pinyin conversion for specific business requirements or ambiguous characters.

```java
// Add custom word mapping
PinyinMapDict customDict = new PinyinMapDict();
customDict.put("重庆", "chong qing");
Pinyin.addPinyinMapDict(customDict);

// Or use PinyinRules for temporary overrides
Pinyin.addPinyinRule(new PinyinRules() {
    @Override
    public String convert(String word) {
        if ("重庆".equals(word)) {
            return "chong qing";
        }
        return null;
    }
});
```

--------------------------------

### Convert Chinese Characters to Pinyin (Java)

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Provides methods to convert individual Chinese characters to their Pinyin representation. It also includes a utility to check if a character is a Chinese character. The conversion produces uppercase Pinyin without tones.

```Java
/**
 * If c is a Chinese character, returns uppercase Pinyin; otherwise, returns String.valueOf(c)
 */
String Pinyin.toPinyin(char c)

/**
 * Returns true if c is a Chinese character, otherwise returns false
 */
boolean Pinyin.isChinese(char c)

/**
 * Converts the input string to Pinyin, using the previously set user dictionary. Inserts a separator between characters.
 */
String toPinyin(String str, String separator)
```

--------------------------------

### Handling Multi-syllable Words and Custom Dictionaries

Source: https://context7.com/promeg/tinypinyin/llms.txt

This section covers advanced usage for handling multi-syllable words, custom dictionaries, and rule overrides.

```APIDOC
## Advanced Usage: Multi-syllable Words and Customization

### Description
This section details how to handle multi-syllable words, use custom dictionaries, and apply temporary rule overrides for specific Pinyin conversions.

### Method
`Pinyin.addCustomDict(PinyinMapDict dict)` and `PinyinRules.addRule(String regex, String replacement)`

### Endpoint
N/A (Library usage)

### Parameters
#### `addCustomDict` Parameters
- **dict** (PinyinMapDict) - Required - A custom dictionary implementing `PinyinMapDict`.

#### `addRule` Parameters
- **regex** (String) - Required - The regular expression to match.
- **replacement** (String) - Required - The replacement string for the matched regex.

### Request Example
```java
// Add a custom dictionary for specific names
Pinyin.addCustomDict(new PinyinMapDict() {
    @Override
    public Map<String, String> loadMapDict() {
        Map<String, String> map = new HashMap<>();
        map.put("重庆", "chong qing"); // Example for a city name
        return map;
    }
});

// Add a temporary rule for a specific word
PinyinRules.addRule("\u56fd\u5bb6", "guo jia"); // Example: override '国家'

// Convert text with custom rules applied
String pinyinWithCustom = Pinyin.toPinyin("重庆市的国家"); // Output: chong qing shi guo jia
```

### Response
#### Success Response (String)
- **pinyinWithCustom** (String) - The converted Pinyin string with custom rules applied.

#### Response Example
```
chong qing shi guo jia
```
```

--------------------------------

### Pinyin.toPinyin(String str, String separator)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Converts an entire string to Pinyin, allowing for a custom separator between character Pinyin results.

```APIDOC
## METHOD Pinyin.toPinyin(String str, String separator)

### Description
Converts a full string to Pinyin. It uses configured dictionaries to handle polyphonic characters and inserts the specified separator between each character's Pinyin.

### Parameters
#### Parameters
- **str** (String) - Required - The string to convert.
- **separator** (String) - Required - The string to insert between Pinyin results.

### Response
- **String** - The converted Pinyin string.

### Example
```java
String result = Pinyin.toPinyin("中国", " "); // Returns "ZHONG GUO"
```
```

--------------------------------

### PinyinDict Interface - Custom Dictionary Interface

Source: https://context7.com/promeg/tinypinyin/llms.txt

PinyinDict is the base interface for dictionaries, defining essential methods. The implementation class PinyinMapDict is typically used for convenience.

```APIDOC
## PinyinDict Interface - Custom Dictionary Interface

### Description
PinyinDict is the base interface for dictionaries, defining essential methods. The implementation class `PinyinMapDict` is typically used for convenience.

### Method
```java
public interface PinyinDict {
    Set<String> words();
    String[] toPinyin(String word);
}
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinDict;
import java.util.Set;
import java.util.HashSet;

// Implement the PinyinDict interface
public class CustomDict implements PinyinDict {

    @Override
    public Set<String> words() {
        // Return all words contained in the dictionary
        Set<String> wordSet = new HashSet<>();
        wordSet.add("重庆");
        wordSet.add("长安");
        return wordSet;
    }

    @Override
    public String[] toPinyin(String word) {
        // Return the Pinyin array corresponding to the word
        switch (word) {
            case "重庆":
                return new String[]{"CHONG", "QING"};
            case "长安":
                return new String[]{"CHANG", "AN"};
            default:
                return null;
        }
    }
}

// Using the custom dictionary
Pinyin.init(Pinyin.newConfig().with(new CustomDict()));
String result = Pinyin.toPinyin("重庆长安", " ");  // Returns "CHONG QING CHANG AN"
```

### Response
This section describes how to use a custom dictionary with the Pinyin library.

#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Convert String to Pinyin with Separators

Source: https://context7.com/promeg/tinypinyin/llms.txt

Converts full strings to Pinyin with customizable separators. This is useful for generating search indexes or formatted Pinyin output.

```java
import com.github.promeg.pinyinhelper.Pinyin;

String result1 = Pinyin.toPinyin("中国", " "); // "ZHONG GUO"
String result2 = Pinyin.toPinyin("中国", "");  // "ZHONGGUO"

public static String generateSearchIndex(String text) {
    return Pinyin.toPinyin(text, "").toLowerCase();
}
```

--------------------------------

### PinyinRules - Custom Pinyin Rules

Source: https://context7.com/promeg/tinypinyin/llms.txt

PinyinRules provides a way to temporarily override Pinyin conversions with the highest priority, useful for special cases without affecting global configuration.

```APIDOC
## PinyinRules - Custom Pinyin Rules

### Description
PinyinRules provides a way to temporarily override Pinyin conversions with the highest priority. This is useful for special cases where you need to modify the Pinyin for certain characters or words without affecting the global configuration.

### Method
```java
PinyinRules rules = new PinyinRules().add(key, value);
Pinyin.toPinyin(characterOrWord, separator, rules);
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (Character or String) - Required - The character or word to override.
- **value** (String) - Required - The custom Pinyin value.

### Request Example
```java
import com.github.promeg.pinyinhelper.Pinyin;
import com.github.promeg.pinyinhelper.PinyinRules;

// Single character rule override
// Default Pinyin for '嗯' is "NG"
String default1 = Pinyin.toPinyin('嗯');  // Returns "NG"

// Using custom rules for override
PinyinRules rules = new PinyinRules().add('嗯', "EN");
String custom1 = Pinyin.toPinyin('嗯', rules);  // Returns "EN"

// String rule override
String default2 = Pinyin.toPinyin("长春", "");  // Returns "ZHANGCHUN" (Incorrect)

PinyinRules cityRules = new PinyinRules().add("长春", "CHANGCHUN");
String custom2 = Pinyin.toPinyin("长春", "", cityRules);  // Returns "CHANGCHUN" (Correct)

// Chaining multiple rules
PinyinRules multiRules = new PinyinRules()
    .add('嗯', "EN")
    .add("重庆", "CHONGQING")
    .add("长春", "CHANGCHUN");

// PinyinRules have higher priority than dictionaries
Pinyin.init(Pinyin.newConfig()
    .with(new PinyinMapDict() {
        @Override
        public Map<String, String[]> mapping() {
            HashMap<String, String[]> map = new HashMap<>();
            map.put("重庆", new String[]{"NOT", "MATCH"});  // This will be overridden by rules
            return map;
        }
    }));

String dictResult = Pinyin.toPinyin("重庆", "");                      // Returns "NOTMATCH"
String rulesResult = Pinyin.toPinyin("重庆", "",
    new PinyinRules().add("重庆", "CHONGQING"));                      // Returns "CHONGQING"
```

### Response
Returns the Pinyin string based on the applied rules.

#### Success Response (200)
- **pinyinString** (String) - The converted Pinyin string.

#### Response Example
```json
{
  "pinyinString": "EN"
}
```
```

--------------------------------

### Pinyin.toPinyin(char c)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Converts a single character to its uppercase Pinyin representation. Returns the character itself if it is not a Chinese character.

```APIDOC
## METHOD Pinyin.toPinyin(char c)

### Description
Converts a single character to its uppercase Pinyin representation. If the character is not a Chinese character, it returns the character as a string.

### Parameters
#### Path Parameters
- **c** (char) - Required - The character to convert.

### Response
- **String** - The uppercase Pinyin string or the original character.

### Example
```java
String pinyin = Pinyin.toPinyin('中'); // Returns "ZHONG"
```
```

--------------------------------

### Convert Chinese to Pinyin (Java)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Converts a given Chinese string into its Pinyin representation. This method is the core functionality for generating Pinyin for search, sorting, or indexing. It handles multi-syllable words and can be customized for specific needs.

```java
String chinese = "你好世界";
String pinyin = Pinyin.toPinyin(chinese, " "); // "ni hao shi jie"
```

--------------------------------

### Pinyin Conversion API

Source: https://github.com/promeg/tinypinyin/blob/master/README.md

Core methods for converting individual characters or strings to Pinyin and checking if a character is Chinese.

```APIDOC
## Pinyin Conversion API

### Description
Provides utility methods to convert Chinese characters into uppercase Pinyin strings without tone marks and to validate Chinese characters.

### Methods
- `Pinyin.toPinyin(char c)`: Converts a single character to Pinyin.
- `Pinyin.isChinese(char c)`: Checks if a character is a Chinese character.
- `Pinyin.toPinyin(String str, String separator)`: Converts a string to Pinyin with a custom separator.

### Parameters
#### Method: toPinyin(char c)
- **c** (char) - Required - The character to convert.

#### Method: isChinese(char c)
- **c** (char) - Required - The character to check.

#### Method: toPinyin(String str, String separator)
- **str** (String) - Required - The string to convert.
- **separator** (String) - Required - The delimiter to insert between characters.

### Request Example
```java
String pinyin = Pinyin.toPinyin('中'); // Returns "ZHONG"
boolean isChinese = Pinyin.isChinese('中'); // Returns true
String fullPinyin = Pinyin.toPinyin("中国", "-"); // Returns "ZHONG-GUO"
```

### Response
#### Success Response (String/Boolean)
- **Result** (String/Boolean) - Returns the uppercase Pinyin string or a boolean indicating if the input is a Chinese character.
```

--------------------------------

### Pinyin.isChinese(char c)

Source: https://context7.com/promeg/tinypinyin/llms.txt

Checks if a given character is a valid Chinese character (Simplified or Traditional).

```APIDOC
## METHOD Pinyin.isChinese(char c)

### Description
Determines if the provided character is a Chinese character. This method is highly optimized for performance.

### Parameters
#### Parameters
- **c** (char) - Required - The character to check.

### Response
- **boolean** - True if the character is Chinese, false otherwise.

### Example
```java
boolean isChinese = Pinyin.isChinese('中'); // Returns true
```
```

--------------------------------

### Validate Chinese Characters

Source: https://context7.com/promeg/tinypinyin/llms.txt

Provides methods to check if a character is a Chinese character or if a string contains Chinese, supporting both simplified and traditional characters.

```java
import com.github.promeg.pinyinhelper.Pinyin;

boolean isChinese = Pinyin.isChinese('中'); // true

public static int countChineseChars(String text) {
    int count = 0;
    for (char c : text.toCharArray()) {
        if (Pinyin.isChinese(c)) {
            count++;
        }
    }
    return count;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.