asia 0.3.0

A Rust crate providing enums and conversions for Asian countries and their subregions, analogous to the Europe crate.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# Asia Crate

The **asia** crate provides a rich enumeration of Asian countries and their subregions, with functionality similar to the `europe` crate. It includes:

- A comprehensive `AsiaRegion` enum representing both individual countries and subdivided countries.
- Conversion traits to convert between `AsiaRegion` and standard ISO country codes.
- Round-trip conversions from `AsiaRegion` to `Country` (from a shared `country` crate) and back.
- Serialization/Deserialization (Serde) support for `AsiaRegion` and its subregions, including nested subregions like `ChinaRegion`, `IndiaRegion`, `JapanRegion`, and `IndonesiaRegion`.
- Exhaustive test suites ensuring correctness and stability.

## Features

- **No unsafe code**: The codebase is entirely safe Rust.
- **No `unwrap` or `expect`**: All error handling is done gracefully with `Result` and custom error types.
- **No `thiserror`**: Error handling is implemented manually for full control and consistency.

## Examples

Convert a `AsiaRegion` to a `Country`:

```rust
use asia::{AsiaRegion, Country};
use std::convert::TryInto;

let region = AsiaRegion::Japan(asia::JapanRegion::Hokkaido);
let country: Country = region.try_into().expect("Should map to Japan");
assert_eq!(country.to_string(), "Japan");
```

Convert a `Country` back to `AsiaRegion`:

```rust
use asia::{AsiaRegion, Country};
use std::convert::TryInto;

let country = Country::India;
let region: AsiaRegion = country.try_into().expect("Should map to India");
assert!(matches!(region, AsiaRegion::India(_)));
```

Serialize and deserialize `AsiaRegion` with JSON:

```rust
use asia::AsiaRegion;
use asia::ChinaRegion;
use serde_json;

let region = AsiaRegion::China(ChinaRegion::Beijing);
let json = serde_json::to_string(&region).expect("serialize");
assert!(json.contains("\"country\":\"China\""));
assert!(json.contains("\"region\":\"Beijing\""));

let deser: AsiaRegion = serde_json::from_str(&json).expect("deserialize");
assert_eq!(deser, region);
```

## Error Handling

When attempting conversions that are not possible (e.g., mapping a combined region like GCC States to a single `Country`), a custom error type `AsiaRegionConversionError` is returned, allowing you to handle these cases gracefully.

## Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/yourusername/asia/issues).

1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request

## License

This project is licensed under the MIT license. See [LICENSE](LICENSE) for details.