Struct bsn1::IdRef

source ·

pub struct IdRef { /* private fields */ }

Expand description

IdRef is a wrapper of [u8] representing Identifier.

The user can access the inner slice via AsRef implementation.

This struct is Unsized, and the user will usually use a reference to it.

Implementations§

source §

impl IdRef

source

pub fn parse<'a>(bytes: &mut &'a [u8]) -> Result<&'a Self, Error>

Parses bytes starting with identifier octets and provides a reference to IdRef.

This function ignores extra octet(s) at the end if any.

On success, bytes will be updated to point the next octet of IdRef; otehrwise, bytes will not be updated.

§Warnings

ASN.1 reserves some universal identifier numbers and they should not be used, however, this function ignores the rule. For example, number 15 (0x0f) is reserved for now, but this functions returns Ok.

§Examples

use bsn1::IdRef;

// Serialize an 'identifier' representing 'utf8-string'
let id = IdRef::utf8_string();
let mut serialized = Vec::from(id.as_ref());

// Deserialize.
{
    let mut serialized: &[u8] = &serialized[..];
    let deserialized = IdRef::parse(&mut serialized).unwrap();
    assert_eq!(id, deserialized);
    assert_eq!(serialized.len(), 0);
}

// Extra octets at the end does not affect the result.
serialized.push(0x00);
serialized.push(0x01);
{
    let mut serialized: &[u8] = &serialized[..];
    let deserialized = IdRef::parse(&mut serialized).unwrap();
    assert_eq!(id, deserialized);
    assert_eq!(serialized, &[0x00, 0x01]);
}

source

pub fn parse_mut<'a>(bytes: &mut &'a mut [u8]) -> Result<&'a mut Self, Error>

Parses bytes starting with identifier, and provides a mutable reference to IdRef.

This function ignores extra octet(s) at the end if any.

On success, bytes will be updated to point the next octet of IdRef; otehrwise, bytes will not be updated.

§Warnings

ASN.1 reserves some universal identifier numbers and they should not be used, however, this function ignores the rule. For example, number 15 (0x0f) is reserved for now, but this functions returns Ok.

§Examples

use bsn1::{ClassTag, IdRef};

// Serialize an 'identifier' representing 'utf8-string'
let id = IdRef::utf8_string();
let mut serialized = Vec::from(id.as_ref());

// Deserialize.
{
    let mut serialized: &mut [u8] = &mut serialized[..];
    let deserialized = IdRef::parse_mut(&mut serialized).unwrap();
    assert_eq!(id, deserialized);
    assert_eq!(serialized.len(), 0);

    deserialized.set_class(ClassTag::Private);
}

// Now, `serialized` is changed.
// Deserialize again, and the result is not same to before.
{
    let mut serialized: &mut [u8] = &mut serialized[..];
    let deserialized = IdRef::parse_mut(&mut serialized).unwrap();
    assert_ne!(id, deserialized);
    assert_eq!(serialized, &serialized[..]);
}

source

pub const unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self

Provides a reference from bytes without any check. bytes must not include any extra octets.

If it is not sure whether bytes is valid octets as an identifer, use parse instead.

§Safety

The behaviour is undefined if the format of bytes is invalid as ‘identifier octets’.

§Examples

use bsn1::IdRef;

let id = IdRef::eoc();
let serialized = id.as_ref();
let deserialized = unsafe { IdRef::from_bytes_unchecked(serialized) };
assert_eq!(id, deserialized);

source

pub unsafe fn from_mut_bytes_unchecked(bytes: &mut [u8]) -> &mut Self

Provides a mutable reference from bytes without any check. bytes must not include any extra octet.

If it is not sure whether bytes is valid octets as an identifer, use parse_mut instead.

§Safety

The behaviour is undefined if the format of bytes is bad as ‘identifier octets’.

§Examples

use bsn1::{ClassTag, IdRef};

// Serialize and deserialize `id` representing 'EOC'.
let id = IdRef::eoc();
let mut serialized: Vec<u8> = Vec::from(id.as_ref());
let deserialized = unsafe { IdRef::from_mut_bytes_unchecked(&mut serialized[..]) };

// `deserialized` is same to `id` and the class is 'universal'.
assert_eq!(id, deserialized);
assert_eq!(ClassTag::Universal, deserialized.class());

// Update deserialized
deserialized.set_class(ClassTag::Application);

assert_ne!(id, deserialized);
assert_eq!(ClassTag::Application, deserialized.class());

// `serialized` was changed as well.
assert_ne!(id.as_ref(), &serialized[..]);

source

pub const fn eoc() -> &'static Self

Provides a reference to IdRef representing ‘Universal EOC’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::eoc();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x00, id.number().unwrap().get());

source

pub const fn boolean() -> &'static Self

Provides a reference to IdRef representing ‘Universal Boolean’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::boolean();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x01, id.number().unwrap().get());

source

pub const fn integer() -> &'static Self

Provides a reference to IdRef representing ‘Universal Integer’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::integer();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x02, id.number().unwrap().get());

source

pub const fn octet_string() -> &'static Self

Provides a reference to IdRef representing ‘Universal Octet String’ with primitive flag.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::octet_string();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x04, id.number().unwrap().get());

source

pub const fn octet_string_constructed() -> &'static Self

Provides a reference to IdRef representing ‘Universal Octet String’ with constructed flag.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::octet_string_constructed();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Constructed, id.pc());
assert_eq!(0x04, id.number().unwrap().get());

source

pub const fn null() -> &'static Self

Provides a reference to IdRef representing ‘Universal Null’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::null();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x05, id.number().unwrap().get());

source

pub const fn real() -> &'static Self

Provides a reference to IdRef representing ‘Universal Real’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::real();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x09, id.number().unwrap().get());

source

pub const fn utf8_string() -> &'static Self

Provides a reference to IdRef representing ‘Universal UTF8 String’ with primitive flag.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::utf8_string();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Primitive, id.pc());
assert_eq!(0x0c, id.number().unwrap().get());

source

pub const fn utf8_string_constructed() -> &'static Self

Provides a reference to IdRef representing ‘Universal UTF8 String’ with constructed flag.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::utf8_string_constructed();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Constructed, id.pc());
assert_eq!(0x0c, id.number().unwrap().get());

source

pub const fn sequence() -> &'static Self

Provides a reference to IdRef representing ‘Universal Sequence’ or ‘Universal Sequence of’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::sequence();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Constructed, id.pc());
assert_eq!(0x10, id.number().unwrap().get());

source

pub const fn set() -> &'static Self

Provides a reference to IdRef representing ‘Universal Set’ or ‘Universal Set of’.

§Examples

use bsn1::{ClassTag, IdRef, PCTag};

let id = IdRef::set();

assert_eq!(ClassTag::Universal, id.class());
assert_eq!(PCTag::Constructed, id.pc());
assert_eq!(0x11, id.number().unwrap().get());

source

pub const fn len(&self) -> usize

Returns the byte count of the inner bytes.

§Examples

use bsn1::IdRef;

// Id of Universal Integer is [0x02]. It is 1 byte long.
let id = IdRef::integer();
assert_eq!(id.len(), 1);

source

pub const fn class(&self) -> ClassTag

Returns the ClassTag of self.

§Examples

use bsn1::{ClassTag, IdRef};

// 'EOC' is defined as Universal class.
let eoc = IdRef::eoc();
assert_eq!(ClassTag::Universal, eoc.class());

source

pub const fn is_universal(&self) -> bool

Returns true if self is ‘Universal class’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Universal, PCTag::Primitive, 0_u8.into());
assert_eq!(true, id.is_universal());

source

pub const fn is_application(&self) -> bool

Returns true if self is ‘Application class’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Application, PCTag::Primitive, 0_u8.into());
assert_eq!(true, id.is_application());

source

pub const fn is_context_specific(&self) -> bool

Returns true if self is ‘Context Specific class’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::ContextSpecific, PCTag::Primitive, 0_u8.into());
assert_eq!(true, id.is_context_specific());

source

pub const fn is_private(&self) -> bool

Returns true if self is ‘Private class’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Private, PCTag::Primitive, 0_u8.into());
assert_eq!(true, id.is_private());

source

pub const fn pc(&self) -> PCTag

Returns the Primitive/Constructed flag of self.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Universal, PCTag::Primitive, 0_u8.into());
assert_eq!(PCTag::Primitive, id.pc());

let id = Id::new(ClassTag::Application, PCTag::Constructed, 1_u8.into());
assert_eq!(PCTag::Constructed, id.pc());

source

pub const fn is_primitive(&self) -> bool

Returns true if self is flagged as ‘Primitive’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Universal, PCTag::Primitive, 0_u8.into());
assert_eq!(true, id.is_primitive());

source

pub const fn is_constructed(&self) -> bool

Returns true if self is flagged as ‘Constructed’, or false.

§Examples

use bsn1::{ClassTag, Id, PCTag};

// 'Id' implements 'Deref<Target = IdRef>'.
let id = Id::new(ClassTag::Universal, PCTag::Constructed, 0_u8.into());
assert_eq!(true, id.is_constructed());

source

pub fn number(&self) -> Result<TagNumber, Error>

Returns the number of self unless overflow.

§Examples

use bsn1::{ClassTag, Id, IdRef, PCTag};
use std::ops::Deref;

let id = Id::new(ClassTag::Application, PCTag::Primitive, 49_u8.into());
let idref: &IdRef = id.deref();
assert_eq!(49, idref.number().unwrap().get());

source

pub fn set_class(&mut self, cls: ClassTag)

Update the class of self.

§Examples

use bsn1::{ClassTag, IdRef};

// Creates a '&mut IdRef' representing 'Universal Integer'.
let mut bytes = Vec::from(IdRef::integer().as_ref());
let idref = IdRef::parse_mut(&mut &mut bytes[..]).unwrap();

assert_eq!(ClassTag::Universal, idref.class());

idref.set_class(ClassTag::Application);
assert_eq!(ClassTag::Application, idref.class());

source

pub fn set_pc(&mut self, pc: PCTag)

Update the Primitive/Constructed flag of self.

§Examples

use bsn1::{PCTag, IdRef};

let id = IdRef::integer();
let mut serialized = Vec::from(id.as_ref());
let deserialized = IdRef::parse_mut(&mut &mut serialized[..]).unwrap();

// 'Integer' is primitive.
assert_eq!(PCTag::Primitive, deserialized.pc());

// Force to change into constructed.
deserialized.set_pc(PCTag::Constructed);
assert_eq!(PCTag::Constructed, deserialized.pc());