Struct bcder::decode::Constructed

pub struct Constructed<'a, S: 'a> { /* private fields */ }

The content octets of a constructed value.

You will only ever receive a mutable reference to a value of this type as an argument to a closure provided to some function. The closure will have to process all content of the constructed value.

Since constructed values consist of a sequence of values, the methods allow you to process these values one by one. The most basic of these are take_value and take_opt_value which process exactly one value or up to one value. A number of convenience functions exists on top of them for commonly encountered types and cases.

Because the caller of your closure checks whether all content has been advanced over and raising an error of not, you only need to read as many values as you expected to be present and can simply return when you think you are done.

Implementations

impl<'a, S: Source + 'a> Constructed<'a, S>

General Management

pub fn decode<F, T>(source: S, mode: Mode, op: F) -> Result<T, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Decode a source as a constructed content.

The function will start decoding of source in the given mode. It will pass a constructed content value to the closure op which has to process all the content and return a result or error.

This function is identical to calling Mode::decode.

pub fn mode(&self) -> Mode

Returns the encoding mode used by the value.

pub fn set_mode(&mut self, mode: Mode)

Sets the encoding mode to be used for the value.

impl<'a, S: Source + 'a> Constructed<'a, S>

Processing Contained Values

The methods in this section each process one value of the constructed value’s content.

pub fn take_value<F, T>(&mut self, op: F) -> Result<T, S::Err>where
    F: FnOnce(Tag, &mut Content<'_, S>) -> Result<T, S::Err>,

Process one value of content.

The closure op receives the tag and content of the next value and must process it completely, advancing to the content’s end.

Upon success, the method returns the closure’s return value. The method returns a malformed error if there isn’t at least one more value available. It also returns an error if the closure returns one or if reading from the source fails.

pub fn take_opt_value<F, T>(&mut self, op: F) -> Result<Option<T>, S::Err>where
    F: FnOnce(Tag, &mut Content<'_, S>) -> Result<T, S::Err>,

Processes an optional value.

If there is at least one more value available, the closure op is given the tag and content of that value and must process it completely, advancing to the end of its content. If the closure succeeds, its return value is returned as ‘some’ result.

If there are no more values available, the method returns Ok(None). It returns an error if the closure returns one or if reading from the source fails.

pub fn take_value_if<F, T>(&mut self, expected: Tag, op: F) -> Result<T, S::Err>where
    F: FnOnce(&mut Content<'_, S>) -> Result<T, S::Err>,

Processes a value with the given tag.

If the next value has the tag expected, its content is being given to the closure which has to process it completely and return whatever is being returned upon success.

The method will return a malformed error if it encounters any other tag or the end of the value. It will also return an error if the closure returns an error or doesn’t process the complete values, or if accessing the underlying source fails.

pub fn take_opt_value_if<F, T>(
    &mut self,
    expected: Tag,
    op: F
) -> Result<Option<T>, S::Err>where
    F: FnOnce(&mut Content<'_, S>) -> Result<T, S::Err>,

Processes an optional value with the given tag.

If the next value has the tag expected, its content is being given to the closure which has to process it completely and return whatever is to be returned as some value.

If the next value has a different tag or if the end of the value has been reached, the method returns Ok(None). It will return an error if the closure fails or doesn’t process the complete value, or if accessing the underlying source fails.

pub fn take_constructed<F, T>(&mut self, op: F) -> Result<T, S::Err>where
    F: FnOnce(Tag, &mut Constructed<'_, S>) -> Result<T, S::Err>,

Process a constructed value.

If the next value is a constructed value, its tag and content are being given to the closure op which has to process it completely. If it succeeds, its return value is returned.

If the next value is not a constructed value or there is no next value or if the closure doesn’t process the next value completely, a malformed error is returned. An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_opt_constructed<F, T>(&mut self, op: F) -> Result<Option<T>, S::Err>where
    F: FnOnce(Tag, &mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes an optional constructed value.

If the next value is a constructed value, its tag and content are being given to the closure op which has to process it completely. If it succeeds, its return value is returned as some value.

If the end of the value has been reached, the method returns Ok(None).

If the next value is not a constructed value or if the closure doesn’t process the next value completely, a malformed error is returned. An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_constructed_if<F, T>(
    &mut self,
    expected: Tag,
    op: F
) -> Result<T, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes a constructed value with a required tag.

If the next value is a constructed value with a tag equal to expected, its content is given to the closure op which has to process it completely. If the closure succeeds, its return value is returned.

If the next value is not constructed or has a different tag, if the end of the value has been reached, or if the closure does not process the contained value’s content completely, a malformed error is returned. An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_opt_constructed_if<F, T>(
    &mut self,
    expected: Tag,
    op: F
) -> Result<Option<T>, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes an optional constructed value if it has a given tag.

If the next value is a constructed value with a tag equal to expected, its content is given to the closure op which has to process it completely. If the closure succeeds, its return value is returned.

If the next value is not constructed, does not have the expected tag, or the end of this value has been reached, the method returns Ok(None). It returns a malformed error if the closure does not process the content of the next value fully.

An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_primitive<F, T>(&mut self, op: F) -> Result<T, S::Err>where
    F: FnOnce(Tag, &mut Primitive<'_, S>) -> Result<T, S::Err>,

Processes a primitive value.

If the next value is primitive, its tag and content are given to the closure op which has to process it fully. Upon success, the closure’s return value is returned.

If the next value is not primitive, if the end of value has been reached, or if the closure fails to process the next value’s content fully, a malformed error is returned. An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_opt_primitive<F, T>(&mut self, op: F) -> Result<Option<T>, S::Err>where
    F: FnOnce(Tag, &mut Primitive<'_, S>) -> Result<T, S::Err>,

Processes an optional primitive value.

If the next value is primitive, its tag and content are given to the closure op which has to process it fully. Upon success, the closure’s return value is returned.

If the next value is not primitive or if the end of value has been reached, Ok(None) is returned. If the closure fails to process the next value’s content fully, a malformed error is returned. An error is also returned if the closure returns one or if accessing the underlying source fails.

pub fn take_primitive_if<F, T>(
    &mut self,
    expected: Tag,
    op: F
) -> Result<T, S::Err>where
    F: FnOnce(&mut Primitive<'_, S>) -> Result<T, S::Err>,

Processes a primitive value if it has the right tag.

If the next value is a primitive and its tag matches expected, its content is given to the closure op which has to process it completely or return an error, either of which is returned.

The method returns a malformed error if there is no next value, if the next value is not a primitive, if it doesn’t have the right tag, or if the closure doesn’t advance over the complete content. If access to the underlying source fails, an error is returned, too.

pub fn take_opt_primitive_if<F, T>(
    &mut self,
    expected: Tag,
    op: F
) -> Result<Option<T>, S::Err>where
    F: FnOnce(&mut Primitive<'_, S>) -> Result<T, S::Err>,

Processes an optional primitive value of a given tag.

If the next value is a primitive and its tag matches expected, its content is given to the closure op which has to process it completely or return an error, either of which is returned.

If the end of this value has been reached, if the next value is not a primitive or if its tag doesn’t match, the method returns Ok(None). If the closure doesn’t process the next value’s content fully the method returns a malformed error. If access to the underlying source fails, it returns an appropriate error.

pub fn capture<F>(&mut self, op: F) -> Result<Captured, S::Err>where
    F: FnOnce(&mut Constructed<'_, CaptureSource<'_, LimitedSource<S>>>) -> Result<(), S::Err>,

Captures content for later processing

The method gives a representation of the content to the closure op. If it succeeds, it returns whatever the closure advanced over as a Captured value.

The closure may process no, one, several, or all values of this value’s content.

If the closure returns an error, this error is returned.

pub fn capture_one(&mut self) -> Result<Captured, S::Err>

Captures one value for later processing

The method takes the next value from this value’s content, whatever it its, end returns its encoded form as a Captured value.

If there is no next value, a malformed error is returned. If access to the underlying source fails, an appropriate error is returned.

pub fn capture_all(&mut self) -> Result<Captured, S::Err>

Captures all remaining content for later processing.

The method takes all remaining values from this value’s content and returns their encoded form in a Bytes value.

pub fn skip_all(&mut self) -> Result<(), S::Err>

Skips over all remaining content.

pub fn skip_one(&mut self) -> Result<Option<()>, S::Err>

Attempts to skip over the next value.

If there is a next value, returns Ok(Some(())), if the end of value has already been reached, returns Ok(None).

impl<'a, S: Source + 'a> Constructed<'a, S>

Processing Standard Values

These methods provide short-cuts for processing fundamental values in their standard form. That is, the values use their regular tag and encoding.

pub fn take_bool(&mut self) -> Result<bool, S::Err>

Processes and returns a mandatory boolean value.

pub fn take_opt_bool(&mut self) -> Result<Option<bool>, S::Err>

Processes and returns an optional boolean value.

pub fn take_null(&mut self) -> Result<(), S::Err>

Processes a mandatory NULL value.

pub fn take_opt_null(&mut self) -> Result<(), S::Err>

Processes an optional NULL value.

pub fn take_u8(&mut self) -> Result<u8, S::Err>

Processes a mandatory INTEGER value of the u8 range.

If the integer value is less than 0 or greater than 255, a malformed error is returned.

pub fn take_opt_u8(&mut self) -> Result<Option<u8>, S::Err>

Processes an optional INTEGER value of the u8 range.

If the integer value is less than 0 or greater than 255, a malformed error is returned.

pub fn skip_u8_if(&mut self, expected: u8) -> Result<(), S::Err>

Skips over a mandatory INTEGER if it has the given value.

If the next value is an integer but of a different value, returns a malformed error.

pub fn skip_opt_u8_if(&mut self, expected: u8) -> Result<(), S::Err>

Skips over an optional INTEGER if it has the given value.

If the next value is an integer but of a different value, returns a malformed error.

pub fn take_u16(&mut self) -> Result<u16, S::Err>

Processes a mandatory INTEGER value of the u16 range.

If the integer value is less than 0 or greater than 65535, a malformed error is returned.

pub fn take_opt_u16(&mut self) -> Result<Option<u16>, S::Err>

Processes an optional INTEGER value of the u16 range.

If the integer value is less than 0 or greater than 65535, a malformed error is returned.

pub fn take_u32(&mut self) -> Result<u32, S::Err>

Processes a mandatory INTEGER value of the u32 range.

If the integer value is less than 0 or greater than 2^32-1, a malformed error is returned.

pub fn take_opt_u32(&mut self) -> Result<Option<u32>, S::Err>

Processes a optional INTEGER value of the u32 range.

If the integer value is less than 0 or greater than 2^32-1, a malformed error is returned.

pub fn take_u64(&mut self) -> Result<u64, S::Err>

Processes a mandatory INTEGER value of the u64 range.

If the integer value is less than 0 or greater than 2^64-1, a malformed error is returned.

pub fn take_opt_u64(&mut self) -> Result<Option<u64>, S::Err>

Processes a optional INTEGER value of the u64 range.

If the integer value is less than 0 or greater than 2^64-1, a malformed error is returned.

pub fn take_sequence<F, T>(&mut self, op: F) -> Result<T, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes a mandatory SEQUENCE value.

This is a shortcut for self.take_constructed(Tag::SEQUENCE, op).

pub fn take_opt_sequence<F, T>(&mut self, op: F) -> Result<Option<T>, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes an optional SEQUENCE value.

This is a shortcut for self.take_opt_constructed(Tag::SEQUENCE, op).

pub fn take_set<F, T>(&mut self, op: F) -> Result<T, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes a mandatory SET value.

This is a shortcut for self.take_constructed(Tag::SET, op).

pub fn take_opt_set<F, T>(&mut self, op: F) -> Result<Option<T>, S::Err>where
    F: FnOnce(&mut Constructed<'_, S>) -> Result<T, S::Err>,

Processes an optional SET value.

This is a shortcut for self.take_opt_constructed(Tag::SET, op).

Trait Implementations

impl<'a, S: Debug + 'a> Debug for Constructed<'a, S>

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

Formats the value using the given formatter.