# Kana/ASCII Conversion Utility
Kana conversion utilities to convert Japanese katakana and hiragana, along
with ASCII characters, into full-width (zenkaku) or half-width (hankaku) forms.
There are various requirements around storing data, reporting, user presentation,
etc. with regard to Japanese scripts and ASCII characters. With many services,
data must be sent in a particular format (for example, some financial services require
all katakana to be sent as half-width, single-byte (hankaku) characters with kanji and
ASCII being sent in full-width, double-byte (zenkaku) characters). In other use cases,
data is stored as all double-byte (zenkaku) characters, awaiting transformation as required
by separate utilities. This library aims to help in these conversions, making
storing and sending Japanese characters easier.
## Terminology
Since various terms are used for Japanese character representation, which can be confusing, this
list is provided to clarify the definitions:
| Half-width kana | Katakana characters which are represented by a single byte |
| Full-width kana | Katakana characters which are represented by two bytes |
| Single-byte | Characters whose values are stored in a single byte (half-width katakana, normal ASCII)
| Double-byte | Characters whose values are stored in two bytes (full-width katakana, hiragana, kanji, double-byte ASCII)
| Hankaku (半角) | The Japanese term for "half-width". Same definition as "Single-byte".
| Zenkaku (全角) | The Japanese term for "full-width". Same definition as "Double-byte".
| Katakana (カタカナ)| The Japanese Katakana character set, which can be stored in wither one byte (half-width) or two (full-width) |
| Hiragana (ひらがな)| The Japanese Hiragana character set, which can only be stored as a two-byte value |
| Kanji (漢字) | The Japanese Kanji characters, which can only be stored as a two-byte value |
| Romaji (ローマ字) | Literally "Roman letters", the set of characters used to represent Japanese words in Latin alphabetical format (using ASCII characters). |
| ASCII | The standard ASCII character set, which is usually stored in one-byte, but also has a two-byte version for Japanese "Romaji" representation |
# Usage
Simply add to your `Cargo.toml`:
```$xslt
[dependencies]
kana-conversion = "0.1"
```
and use in your rust code:
```$xslt
extern crate kana_conversion;
use kana_conversion::to_double_byte;
```
# Conversion Functions
The "to_double_byte" function takes a string slice to convert and a mode. If `AsciiOnly` is
selected, only normal ASCII chars will be converted to double-byte (zenkaku), while if `KanaOnly`
is selected, only half-width (hankaku) katakana will convert, while `KanaAndAscii` will convert both.
The return is an owned String which holds double-byte (zenkaku) characters, converted as specified by
the `mode`.
# License
Licensed under:
* MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
# Contribution
Contributions are welcome, and will be subject to the regulations presented in the license indicated above.