rust_iso9362 0.1.0

ISO 9362 (Business Identifier Code, also known as the SWIFT/BIC code) defines a standard format for identifying business parties – in particular banks and financial institutions – in financial transactions. This crate parses, validates and decomposes BIC codes into their component parts.
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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# rust_iso/iso9362

A rust crate providing ISO 9362 (Business Identifier Code / BIC, a.k.a. SWIFT
code) parsing and validation.

## What is ISO 9362

> ISO 9362 is an international standard for Business Identifier Codes (BIC), a
> standard published by the International Organization for Standardization (ISO)
> as a way to uniquely identify banks and financial institutions worldwide. The
> BIC is also known as the SWIFT code, SWIFT-BIC, or SWIFT address.
>
> A BIC is 8 or 11 characters long and is made up of:
> * Business party prefix – four alphabetic characters identifying the business
>   party (institution / bank code).
> * Country code – two alphabetic characters, the ISO 3166-1 alpha-2 code of the
>   country in which the business party is located.
> * Business party suffix – two alphanumeric characters (the location code).
> * Branch code – an optional three alphanumeric characters identifying a
>   specific branch; `XXX`, or its absence, denotes the primary office.
>
> *-- [Wikipedia](https://en.wikipedia.org/wiki/ISO_9362)*

Unlike ISO 3166, ISO 9362 does not define a fixed, enumerable dataset (the full
registry of assigned BICs is maintained by SWIFT), so this crate is a
**parser / validator** that decomposes a BIC into its component parts.

| Position | Part                       | Length | Charset    |
|----------|----------------------------|--------|------------|
| 1–4      | Business party prefix      | 4      | `A-Z`      |
| 5–6      | Country code (ISO 3166-1)  | 2      | `A-Z`      |
| 7–8      | Business party suffix      | 2      | `A-Z0-9`   |
| 9–11     | Branch code (optional)     | 3      | `A-Z0-9`   |

## Installing

``` toml
[dependencies]
rust_iso9362 = "0.1.0"
```

## Features

* `serde` — implements `Serialize`/`Deserialize` for `BIC`. A `BIC` serialises
  to its canonical code string and deserialises case-insensitively via
  `BIC::parse`. Enable with:

  ``` toml
  rust_iso9362 = { version = "0.1.0", features = ["serde"] }
  ```

* `iso3166` — adds `BIC::country()`, which resolves the embedded ISO 3166-1
  country code to a `rust_iso3166::CountryCode` using the
  [`rust_iso3166`](https://crates.io/crates/rust_iso3166) crate.

* `cli` — builds the `iso9362` command-line lookup tool (pulls in
  `prettytable-rs`). Off by default; install with
  `cargo install rust_iso9362 --features cli`.

The minimum supported Rust version is 1.85.

## Using

``` rust
// Parse + validate (returns Option)
let bic = rust_iso9362::parse("DEUTDEFF500").unwrap();

// Or get a Result with a descriptive error
let bic = rust_iso9362::BIC::parse("DEUTDEFF500").unwrap();

assert_eq!(bic.business_party_prefix(), "DEUT"); // a.k.a. bank_code()
assert_eq!(bic.country_code(), "DE");
assert_eq!(bic.business_party_suffix(), "FF");   // a.k.a. location_code()
assert_eq!(bic.branch_code(), Some("500"));
assert_eq!(bic.bic8(), "DEUTDEFF");
assert_eq!(bic.bic11(), "DEUTDEFF500");
assert!(!bic.is_primary_office());

// 8-character BICs identify the primary office
let bic = rust_iso9362::BIC::parse("DEUTDEFF").unwrap();
assert_eq!(bic.branch_code(), None);
assert!(bic.is_primary_office());
assert_eq!(bic.bic11(), "DEUTDEFFXXX");

// Cheap validity check
assert!(rust_iso9362::is_valid("NEDSZAJJXXX"));
assert!(!rust_iso9362::is_valid("123"));

// FromStr is implemented too
let bic: rust_iso9362::BIC = "DEUTDEFF".parse().unwrap();

// With the `iso3166` feature:
// let country = bic.country().unwrap();
// assert_eq!(country.alpha3, "DEU");
```

Data sample:

``` rust
BIC {
    code: "DEUTDEFF500",
    // business_party_prefix: "DEUT",
    // country_code:          "DE",
    // business_party_suffix: "FF",
    // branch_code:           Some("500"),
}
```

## Contributing

Feel free to submit a pull request or create an issue.
or request to [rust-iso](https://github.com/rust-iso)

## License

rust-iso/rust_iso9362 is licensed under the Apache-2.0 license.

## Source(s)

* [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362) by [Wikipedia](http://www.wikipedia.org)
* [www.iso.org](https://www.iso.org/standard/60390.html)