Skip to main content

iso_7064/
lib.rs

1//! # A Rust implementation of ISO/IEC 7064:2003 Check character systems
2//!
3//! This crate provides `no_std`-compatible implementations of the check character
4//! (digit) systems specified by [ISO/IEC 7064:2003].
5//!
6//! [ISO/IEC 7064:2003]: https://www.iso.org/standard/31531.html
7//!
8//! ```rust
9//! use iso_7064::{MOD11_2, MOD1271_36};
10//!
11//! assert_eq!(MOD11_2.compute("079")?, ['X']);
12//! assert_eq!(MOD11_2.compute_lax("{0-7-9}"), ['X']);
13//!
14//! assert!(MOD11_2.verify("079X")?);
15//! assert!(MOD11_2.verify_lax("{0-7-9}[X]"));
16//! assert!(MOD11_2.verify_from_values([0, 7, 9, 10])?);
17//! assert!(!MOD11_2.verify_from_chars("0790".chars())?);
18//!
19//! # #[cfg(feature = "alloc")]
20//! # {
21//! let mut buf = String::from("ISO 79");
22//! MOD1271_36.protect_lax(&mut buf);
23//! assert_eq!(buf, "ISO 793W");
24//! # }
25//! # Ok::<_, Box<dyn core::error::Error>>(())
26//! ```
27//!
28//! This crate supports all the eight check character systems as shown below
29//! specified by the standard:
30//!
31//! | System                    | Type   | Input string            | Check character(s)                    |
32//! | ------------------------- | ------ | ----------------------- | ------------------------------------- |
33//! | ISO/IEC 7064, MOD 11-2    | Pure   | Numeric (`0-9`)         | 1 digit or `'X'` (`0-9X`)             |
34//! | ISO/IEC 7064, MOD 37-2    | Pure   | Alphanumeric (`0-9A-Z`) | 1 digit, letter, or `'*'` (`0-9A-Z*`) |
35//! | ISO/IEC 7064, MOD 97-10   | Pure   | Numeric (`0-9`)         | 2 digits (`0-9`)                      |
36//! | ISO/IEC 7064, MOD 661-26  | Pure   | Alphabetic (`A-Z`)      | 2 letters (`A-Z`)                     |
37//! | ISO/IEC 7064, MOD 1271-36 | Pure   | Alphanumeric (`0-9A-Z`) | 2 digits or letters (`0-9A-Z`)        |
38//! | ISO/IEC 7064, MOD 11,10   | Hybrid | Numeric (`0-9`)         | 1 digit (`0-9`)                       |
39//! | ISO/IEC 7064, MOD 27,26   | Hybrid | Alphabetic (`A-Z`)      | 1 letter (`A-Z`)                      |
40//! | ISO/IEC 7064, MOD 37,36   | Hybrid | Alphanumeric (`0-9A-Z`) | 1 digit or letter (`0-9A-Z`)          |
41//!
42//! This library also provides support, under the [`extra`] module, for the variant of
43//! MOD 97-10 used in the International Bank Account Number (IBAN). The `extra`
44//! module additionally supports other widely used check character algorithms
45//! besides those in ISO/IEC 7064, namely [Luhn] and [GS1].
46//!
47//! [Luhn]: https://en.wikipedia.org/wiki/Luhn_algorithm
48//! [GS1]: https://www.gs1.org/services/how-calculate-check-digit-manually
49//!
50//! The types under the [`system`], [`accumulator`], and [`charset`] modules provide the
51//! building blocks under the hood.
52//!
53//! ## Crate features
54//!
55//! - `alloc` (enabled by default) enables APIs operating over `String`.
56
57#![no_std]
58#![cfg_attr(docsrs, feature(doc_cfg))]
59
60pub mod accumulator;
61pub mod charset;
62pub mod extra;
63pub mod system;
64
65use system::System;
66
67/// The ISO/IEC 7064, MOD 11-2 pure system with a single check character.
68///
69/// See the [`System`] type for provided methods.
70pub const MOD11_2: system::Mod11_2 = System::with_charset(charset::NumericX, charset::NumericX);
71
72/// The ISO/IEC 7064, MOD 37-2 pure system with a single check character.
73///
74/// See the [`System`] type for provided methods.
75pub const MOD37_2: system::Mod37_2 =
76    System::with_charset(charset::AlphanumericAst, charset::AlphanumericAst);
77
78/// The ISO/IEC 7064, MOD 97-10 pure system with two check characters.
79///
80/// See the [`System`] type for provided methods.
81pub const MOD97_10: system::Mod97_10 = System::with_charset(charset::Numeric, charset::Numeric);
82
83/// The ISO/IEC 7064, MOD 661-26 pure system with two check characters.
84///
85/// See the [`System`] type for provided methods.
86pub const MOD661_26: system::Mod661_26 =
87    System::with_charset(charset::Alphabetic, charset::Alphabetic);
88
89/// The ISO/IEC 7064, MOD 1271-36 pure system with two check characters.
90///
91/// See the [`System`] type for provided methods.
92pub const MOD1271_36: system::Mod1271_36 =
93    System::with_charset(charset::Alphanumeric, charset::Alphanumeric);
94
95/// The ISO/IEC 7064, MOD 11,10 hybrid system.
96///
97/// See the [`System`] type for provided methods.
98pub const MOD11_10: system::Mod11_10 = System::with_charset(charset::Numeric, charset::Numeric);
99
100/// The ISO/IEC 7064, MOD 27,26 hybrid system.
101///
102/// See the [`System`] type for provided methods.
103pub const MOD27_26: system::Mod27_26 =
104    System::with_charset(charset::Alphabetic, charset::Alphabetic);
105
106/// The ISO/IEC 7064, MOD 37,36 hybrid system.
107///
108/// See the [`System`] type for provided methods.
109pub const MOD37_36: system::Mod37_36 =
110    System::with_charset(charset::Alphanumeric, charset::Alphanumeric);
111
112mod util {
113    #[cfg(test)]
114    use crate::{accumulator, charset, system};
115
116    #[inline(always)]
117    pub const fn spec_rem(lhs: u32, rhs: u32) -> u32 {
118        debug_assert!(lhs < rhs * 2);
119        if lhs < rhs { lhs } else { lhs - rhs }
120    }
121
122    #[cold]
123    pub const fn cold_rem(lhs: u32, rhs: u32) -> u32 {
124        lhs % rhs
125    }
126
127    #[cfg(test)]
128    pub fn accumulate_values(
129        acc: &mut impl accumulator::Accumulator,
130        values: impl IntoIterator<Item = u32>,
131    ) {
132        use accumulator::AccumulateResult;
133        for value in values {
134            assert_eq!(acc.accumulate(value), AccumulateResult::Processed);
135        }
136    }
137
138    #[cfg(test)]
139    pub fn prepared_inner<const N_CC: usize, Acc, Enc, Dec>(
140        sys: system::System<N_CC, Acc, Enc, Dec>,
141        valid: &[&str],
142        invalid: &[&str],
143    ) where
144        Acc: accumulator::Accumulator<Computed = [u32; N_CC]> + Default,
145        Enc: charset::Encoder,
146        Dec: charset::Decoder<Decoded: IntoIterator<Item = u32>>,
147    {
148        for &s in valid {
149            assert!(sys.verify(s).unwrap());
150            assert!(sys.verify_lax(s));
151            assert!(sys.verify_from_chars(s.chars()).unwrap());
152
153            let (u, cc) = s.split_at(s.len() - N_CC);
154            assert!(cc.chars().eq(sys.compute(u).unwrap()));
155            assert!(cc.chars().eq(sys.compute_lax(u)));
156            assert!(cc.chars().eq(sys.compute_from_chars(u.chars()).unwrap()));
157        }
158
159        for &s in invalid {
160            assert!(!sys.verify(s).unwrap());
161            assert!(!sys.verify_lax(s));
162            assert!(!sys.verify_from_chars(s.chars()).unwrap());
163
164            let (u, cc) = s.split_at(s.len() - N_CC);
165            assert!(!cc.chars().eq(sys.compute(u).unwrap()));
166            assert!(!cc.chars().eq(sys.compute_lax(u)));
167            assert!(!cc.chars().eq(sys.compute_from_chars(u.chars()).unwrap()));
168        }
169    }
170}
171
172#[cfg(test)]
173mod tests {
174    use super::*;
175
176    #[test]
177    fn examples_mod11_2() {
178        assert_eq!(MOD11_2.compute("0794").unwrap(), ['0']);
179        assert_eq!(MOD11_2.compute_lax("0794"), ['0']);
180        assert_eq!(MOD11_2.compute_lax("{0-7-9-4}"), ['0']);
181
182        assert!(MOD11_2.verify("07940").unwrap());
183        assert!(MOD11_2.verify_lax("07940"));
184        assert!(MOD11_2.verify_lax("{0-7-9-4}[0]"));
185
186        assert_eq!(MOD11_2.compute("079").unwrap(), ['X']);
187        assert_eq!(MOD11_2.compute_lax("079"), ['X']);
188        assert_eq!(MOD11_2.compute_lax("{0-7-9}"), ['X']);
189
190        assert!(MOD11_2.verify("079X").unwrap());
191        assert!(MOD11_2.verify_lax("079X"));
192        assert!(MOD11_2.verify_lax("{0-7-9}[X]"));
193    }
194
195    #[test]
196    fn examples_mod97_10() {
197        assert_eq!(MOD97_10.compute("794").unwrap(), ['4', '4']);
198        assert_eq!(MOD97_10.compute_lax("794"), ['4', '4']);
199        assert_eq!(MOD97_10.compute_lax("{7-9-4}"), ['4', '4']);
200
201        assert!(MOD97_10.verify("79444").unwrap());
202        assert!(MOD97_10.verify_lax("79444"));
203        assert!(MOD97_10.verify_lax("{7-9-4}[4, 4]"));
204    }
205
206    #[test]
207    fn examples_mod1271_36() {
208        assert_eq!(MOD1271_36.compute("ISO79").unwrap(), ['3', 'W']);
209        assert_eq!(MOD1271_36.compute_lax("ISO79"), ['3', 'W']);
210        assert_eq!(MOD1271_36.compute_lax("ISO 79"), ['3', 'W']);
211        assert_eq!(MOD1271_36.compute_lax("{I-S-O 7-9}"), ['3', 'W']);
212
213        assert!(MOD1271_36.verify("ISO793W").unwrap());
214        assert!(MOD1271_36.verify_lax("ISO793W"));
215        assert!(MOD1271_36.verify_lax("ISO 793W"));
216        assert!(MOD1271_36.verify_lax("{I-S-O 7-9}[3, W]"));
217    }
218
219    #[test]
220    fn examples_mod11_10() {
221        assert_eq!(MOD11_10.compute("0794").unwrap(), ['5']);
222        assert_eq!(MOD11_10.compute_lax("0794"), ['5']);
223        assert_eq!(MOD11_10.compute_lax("{0-7-9-4}"), ['5']);
224
225        assert!(MOD11_10.verify("07945").unwrap());
226        assert!(MOD11_10.verify_lax("07945"));
227        assert!(MOD11_10.verify_lax("{0-7-9-4}[5]"));
228    }
229
230    #[test]
231    fn prepared_mod11_2() {
232        let valid = &[
233            "5236022646915810116849",
234            "845064805931988",
235            "85304841090903666744",
236            "337688112X",
237            "92004002654",
238            "21030484337645X",
239            "41818941714",
240            "30465694",
241            "91184666177593810018",
242            "17541621184078843",
243            "43494101",
244            "11195647730159049192304",
245        ];
246
247        let invalid = &[
248            "1687459121",
249            "31888679450464",
250            "9188124336537439",
251            "42079822636786",
252            "771154512981690148767X",
253            "66246345130",
254            "671757580705",
255            "2387040463142667",
256            "44369839572905",
257            "527981147467713",
258            "81511264248755711569723",
259            "91229388880062347394",
260        ];
261
262        util::prepared_inner(MOD11_2, valid, invalid);
263    }
264
265    #[test]
266    fn prepared_mod37_2() {
267        let valid = &[
268            "PX4Z7MWY2YJ0LUGL29CUO",
269            "3B99E8TMZLCX77R7YIEX",
270            "TVBAUKJOL34ZZ4",
271            "L52HZG049GKPMXOQ9",
272            "E4EV3G1AEY1ISEAEQY",
273            "9C9AU99B19GBB7KD2U3V*",
274            "5AJQE3G82BEUD7Q41",
275            "5EV36MX8ZFI4",
276            "7G511LDGP53RN3QVDNB",
277            "V4RL7V4E7OMW",
278            "WV4XMAFC",
279            "JH5LGP0C",
280        ];
281
282        let invalid = &[
283            "KQATAYZTVO1LGYC7J",
284            "0G8F99YCK*",
285            "WN76K4IM16V",
286            "U80YBMPJF3L71BDXWM9G7Q",
287            "A36C7IR7FX9DA0FXU",
288            "P64AFP7S7W61I8Y2OZ*",
289            "XLME2YI2LB95QEMW9HV",
290            "8FNA95QY0NON8O5G8SZD7B8",
291            "H862IMPF6C5QT",
292            "16826SC2CUM",
293            "6LMBNSX15JL0",
294            "1RH1UQOSY5OQSJU28MUP0U*",
295        ];
296
297        util::prepared_inner(MOD37_2, valid, invalid);
298    }
299
300    #[test]
301    fn prepared_mod97_10() {
302        let valid = &[
303            "4331246445963138455002",
304            "2911233259",
305            "4764789672",
306            "43554844",
307            "05917435345034747416569",
308            "9366261837206291",
309            "262338921851557782765",
310            "922783905474546408679",
311            "93719954279014181",
312            "23516238132346714043",
313            "40563587767431",
314            "7752266839610",
315        ];
316
317        let invalid = &[
318            "09827197304756",
319            "4684723585",
320            "5490749315043",
321            "32956005",
322            "42985358018829090107143",
323            "2583231639143482",
324            "10057126",
325            "81005043673147533591",
326            "600389186253702",
327            "844911938825",
328            "4611232777673301",
329            "653007253600637706",
330        ];
331
332        util::prepared_inner(MOD97_10, valid, invalid);
333    }
334
335    #[test]
336    fn prepared_mod661_26() {
337        let valid = &[
338            "FSBULOLEILVNJ",
339            "SICFPGUUV",
340            "IRMQSMWHFDSXDXQPO",
341            "TIPHZXSSMPUZARRFTE",
342            "VNMVULKG",
343            "BQZPCJYDUCF",
344            "NCYUUZBBTAUNUL",
345            "BWJVHGTKIC",
346            "TFFJYFKEEGBWPEADDEA",
347            "SCYMCUKLL",
348            "PRBUNOAUIP",
349            "JJPSKEDMBKJZ",
350        ];
351
352        let invalid = &[
353            "QLMLVMME",
354            "JCCPQKYDCYCMGGKUDO",
355            "HZXWMOWXPAMLVGB",
356            "LQPRRTHTB",
357            "ZHFQHVETSNZLKQHGRWB",
358            "EOOKYXQARTHWUTSJJMOZT",
359            "ZWUWDYEPZNTSLQI",
360            "DKYEHWOZTHTGMBECYPV",
361            "BPJPJMZGASHRSNLZTWWRLZ",
362            "PIKGQNCQLEAYMTUVQULQQVC",
363            "SIIOQOBFIJMECNCMQBV",
364            "HGXBYJGF",
365        ];
366
367        util::prepared_inner(MOD661_26, valid, invalid);
368    }
369
370    #[test]
371    fn prepared_mod1271_36() {
372        let valid = &[
373            "7DJO6YKPZVNMZUCMY",
374            "2RAG0WGS40GUTZ0PZ",
375            "ZALU8MTOAARFAI",
376            "28ZGRKLKQ0I5NEXYRUYLCH4",
377            "YZY2BIE08YJ",
378            "M2K96UOWU8CUI9GL0",
379            "X7SPAGS8GTQULHV66CF2",
380            "IYOMJKMY2AVRQUC2Y8YDG",
381            "UY1QB886O1OI51YO",
382            "IAASX6SF4O7",
383            "XLBNR9KOETXV6SYTPJ1W",
384            "HHYOH4Y8L6W",
385        ];
386
387        let invalid = &[
388            "EOMS5TJROR7EAD823QS8ZC",
389            "HR0LI5NSSULBLI",
390            "HQB7BQP4CMKPSTGAV5VJA",
391            "39QYCR54",
392            "GQWTGSA4ED",
393            "96M4PEEYTONCB1N99O",
394            "3MAL1WQFYJXQ3N",
395            "9ZT8POIU26",
396            "C7OG52Y3MAI3ZFJ0BM87Y0",
397            "LS3Y9NFXCUUPSM06RVW06FQ",
398            "5XSPZWCPYHTEJK3A4I8O72Q",
399            "3M1ZN4WOJ8",
400        ];
401
402        util::prepared_inner(MOD1271_36, valid, invalid);
403    }
404
405    #[test]
406    fn prepared_mod11_10() {
407        let valid = &[
408            "72120953571944888637",
409            "630956234645",
410            "19090053234",
411            "6089258076",
412            "14436084789",
413            "439932244435432",
414            "35786443",
415            "8171133511285059261",
416            "13612873",
417            "76819644",
418            "6584712648951475",
419            "18273960618480754278247",
420        ];
421
422        let invalid = &[
423            "623644773245095632456",
424            "954353828",
425            "10097633924659319735",
426            "3439643114562420",
427            "324267175",
428            "569965205768369754942",
429            "26813819575426447116",
430            "320201360",
431            "996439490488298937425",
432            "2109782058833871",
433            "76377504913003",
434            "543551782",
435        ];
436
437        util::prepared_inner(MOD11_10, valid, invalid);
438    }
439
440    #[test]
441    fn prepared_mod27_26() {
442        let valid = &[
443            "DNWCSEWBUSMXUHMNVEC",
444            "FKNJRXARTPHMFSP",
445            "JLWVIPKDZKMRENSERY",
446            "ZRFJGLJRQLVOHJCCWKF",
447            "GHCIBFCYI",
448            "DMMWTSESBKAVQYFA",
449            "ZDMTSOWIXITFONEV",
450            "WXZNFPLKFAOPTSVMZBYXIXU",
451            "LXMBTJOXBJPL",
452            "JBVNWCIZRKRWPUGNFT",
453            "LHRXBWIVW",
454            "YZBROGVCIBDNNOFAB",
455        ];
456
457        let invalid = &[
458            "GFBZWRJEKNLGEIJIOWFEA",
459            "WQCJRWJVWIKIIKUBPNMEYD",
460            "PGWQIBTKRUUHDITSINFWWK",
461            "OROZGAHCJKJAKTV",
462            "NJHTTTHVEAHGSXFCHEW",
463            "PVKKNFOIRIECA",
464            "SESQRHGOFIQMWKNHGK",
465            "MRPLXNZN",
466            "YSLZRNMDHWPT",
467            "ESXAAHYPRHQBDQ",
468            "UCGXCPIZWCRJCIKIMSJVZK",
469            "QYFMMQPXIMLOAP",
470        ];
471
472        util::prepared_inner(MOD27_26, valid, invalid);
473    }
474
475    #[test]
476    fn prepared_mod37_36() {
477        let valid = &[
478            "6GBVUSQIFXCNTK41WO",
479            "D1VOWY4VV42I2",
480            "FQJA83FUO2Q2AOZ4NST0G2X",
481            "74EO6Z4EJL5IMNAQJPOVEYI",
482            "MSG9S4YXQ",
483            "SROAMRVX991KV",
484            "QH53EF8CSMHIZ69TS1HK",
485            "EN5EAXIRLW1DHR42YOR",
486            "UPFRXRSFEWR",
487            "A97XG2LJ4JLU9LLAJEMN",
488            "T4KGMICAHB08ZTPR",
489            "QEVA9ODUCO",
490        ];
491
492        let invalid = &[
493            "AP9A8MNRTZC59GLSXR",
494            "XX59GK1HUKTFZP5B",
495            "R8WYEAKDVJ4FMH",
496            "PR9LJ8DJE0L",
497            "5B8JO87TBSMMR1XN",
498            "KS27KRVNHG4NMQU3ON5",
499            "HEN88FTBS0GZBFMFXO",
500            "MV9VR3QH",
501            "ZWSFEZ8XFQ1XPGS18AWORFW",
502            "Y51MR7862PK",
503            "DWEG7LA6FMJ2CJGXMM",
504            "FU8SP3V1JOTICTZ",
505        ];
506
507        util::prepared_inner(MOD37_36, valid, invalid);
508    }
509}