Struct Cusip 

pub struct Cusip { /* private fields */ }

A validated CUSIP (or CINS) number (ANSI X9.6).

A Cusip can only be created by Cusip::parse (or the explicitly unchecked Cusip::from_bytes_unchecked), so a value of this type is a proof that the 9 characters form a structurally valid CUSIP with a correct check digit. It stores the identifier inline as [u8; 9], is Copy, and allocates nothing.

Examples

use regit_identifiers::Cusip;

let cusip = Cusip::parse("037833100").unwrap();
assert_eq!(cusip.issuer(), "037833");
assert_eq!(cusip.issue(), "10");
assert_eq!(cusip.check_digit(), '0');
assert_eq!(cusip.as_str(), "037833100");

Implementations

impl Cusip

pub const LENGTH: usize = 9

The number of characters in a CUSIP.

pub fn parse(s: &str) -> Result<Self, ValidationError>

Parses and fully validates a CUSIP.

Validation is strict and, in order: the input must be exactly 9 characters; characters 1–8 must each be drawn from the body alphabet [A-Z0-9*@#] and character 9 must be an ASCII digit; and the check digit must equal the value recomputed from the eight-character body.

Errors

• ValidationError::WrongLength if the input is not 9 characters.
• ValidationError::InvalidCharacter if a character falls outside the set its position allows (this also rejects lower-case input and any non-ASCII character).
• ValidationError::BadCheckDigit if the supplied check digit does not match the recomputed one.

Examples

use regit_identifiers::Cusip;
use regit_identifiers::errors::ValidationError;

assert!(Cusip::parse("037833100").is_ok());

// A single wrong digit is caught, not silently accepted.
assert_eq!(
    Cusip::parse("037833101"),
    Err(ValidationError::BadCheckDigit { expected: '0', found: '1' }),
);

pub fn validate(s: &str) -> Result<(), ValidationError>

Validates a CUSIP without constructing one.

Equivalent to Cusip::parse(s).map(|_| ()); use it when only the verdict is needed.

Errors

Returns the same ValidationError variants as Cusip::parse.

Examples

use regit_identifiers::Cusip;

assert!(Cusip::validate("037833100").is_ok());
assert!(Cusip::validate("037833101").is_err());

pub const fn from_bytes_unchecked(bytes: [u8; 9]) -> Self

Wraps 9 raw bytes as a Cusip without any validation.

The caller asserts that bytes holds the 9 ASCII characters of a valid CUSIP. This exists for reconstructing a Cusip from bytes that were validated earlier; prefer Cusip::parse for any untrusted input.

Examples

use regit_identifiers::Cusip;

let cusip = Cusip::from_bytes_unchecked(*b"037833100");
assert_eq!(cusip.as_str(), "037833100");

pub fn as_str(&self) -> &str

Returns the CUSIP as a string slice.

Examples

use regit_identifiers::Cusip;

assert_eq!(Cusip::parse("037833100").unwrap().as_str(), "037833100");

pub fn as_bytes(&self) -> &[u8]

Returns the CUSIP as its 9 raw ASCII bytes.

Examples

use regit_identifiers::Cusip;

assert_eq!(Cusip::parse("037833100").unwrap().as_bytes(), b"037833100");

pub fn issuer(&self) -> &str

Returns the six-character issuer segment, characters 1–6.

Examples

use regit_identifiers::Cusip;

assert_eq!(Cusip::parse("037833100").unwrap().issuer(), "037833");

pub fn issue(&self) -> &str

Returns the two-character issue segment, characters 7–8.

Examples

use regit_identifiers::Cusip;

assert_eq!(Cusip::parse("037833100").unwrap().issue(), "10");

pub fn check_digit(&self) -> char

Returns the check digit, character 9.

Examples

use regit_identifiers::Cusip;

assert_eq!(Cusip::parse("037833100").unwrap().check_digit(), '0');

pub fn is_cins(&self) -> bool

Returns true if this identifier is a CINS number.

A CINS (CUSIP International Numbering System) number is structurally a CUSIP — same length, same alphabet, same check-digit algorithm — and is distinguished solely by its first character being a letter, where a domestic CUSIP always starts with a digit.

Examples

use regit_identifiers::Cusip;

// A domestic CUSIP starts with a digit.
assert!(!Cusip::parse("037833100").unwrap().is_cins());

pub fn is_domestic(&self) -> bool

Returns true if this is a domestic (US/Canada) CUSIP — the complement of Cusip::is_cins.

The discrimination rule is the leading character: a domestic CUSIP starts with a digit, a CINS with a letter.

Examples

use regit_identifiers::Cusip;

assert!(Cusip::parse("037833100").unwrap().is_domestic());

pub fn cins_region(&self) -> Option<&'static str>

Returns the CINS issuing region of this identifier, if it is a CINS.

The leading letter of a CINS number designates its issuing region per the CINS table; for a domestic CUSIP (which starts with a digit) this returns None. A leading letter outside the assigned table likewise returns None.

Examples

use regit_identifiers::Cusip;

// A domestic CUSIP has no CINS region.
assert_eq!(Cusip::parse("037833100").unwrap().cins_region(), None);

Trait Implementations

impl AsRef<str> for Cusip

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Cusip

fn clone(&self) -> Cusip

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Cusip

impl Debug for Cusip

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Cusip

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Cusip

impl FromStr for Cusip

type Err = ValidationError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Cusip

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Cusip

fn eq(&self, other: &Cusip) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Cusip