rs-matter 0.2.0

/*
 *
 *    Copyright (c) 2025-2026 Project CHIP Authors
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

//! This module contains the base traits for the TLV builder framework, as well
//! as implementations of those traits for several built-in TLV types, like arrays,
//! octet strings, Utf8 strings, nullable and optional types.
//!
//! Note that putting aside those base builders, all other builders are expected to be
//! auto-generated by using the `idl_import` macro, rather than being typed by hand,
//! which is possible but very vberbose.
//!
//! The following is just an example of a builder for a struct TLV type `Foo` that has three fields:
//! ```ignore
//! pub struct FooBuilder<P, const F: usize> {
//!     p: P,
//! }
//!
//! impl<P> FooBuilder<P, 0>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
//!         p.writer().start_struct(tag)?;
//!
//!         Ok(Self { p })
//!     }
//!
//!     pub fn field1(mut self, value: i32) -> Result<FooBuilder<P, 1>, Error> {
//!         self.p.writer().i32(&TLVTag::Context(0), value)?;
//!
//!         Ok(FooBuilder {
//!             p: self.p,
//!         })
//!     }
//! }
//!
//! impl<P> FooBuilder<P, 1>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn field2(mut self, value: u8) -> Result<FooBuilder<P, 2>, Error> {
//!         value.to_tlv(&TLVTag::Context(1), self.p.writer())?;
//!
//!         Ok(FooBuilder {
//!             p: self.p,
//!         })
//!     }
//! }
//!
//! impl<P> FooBuilder<P, 2>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn field3(self) -> Result<BarBuilder<FooBuilder<P, 3>, 0>, Error> {
//!         BarBuilder::new(FooBuilder { p: self.p }, &TLVTag::Context(2))
//!     }
//! }
//!
//! impl<P> FooBuilder<P, 3>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn finish(mut self) -> Result<P, Error> {
//!         self.p.writer().end_container()?;
//!
//!         Ok(self.p)
//!     }
//! }
//!
//! impl<P, const F: usize> TLVBuilderParent for FooBuilder<P, F>
//! where
//!     P: TLVBuilderParent,
//! {
//!     type Write = P::Write;
//!
//!     fn writer(&mut self) -> &mut Self::Write {
//!         self.p.writer()
//!     }
//!
//!     fn into_writer(self) -> Self::Write {
//!         self.p.into_writer()
//!     }
//! }
//!
//! impl<P> TLVBuilder<P> for FooBuilder<P, 0>
//! where
//!     P: TLVBuilderParent,
//! {
//!     fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
//!         Self::new(parent, tag)
//!     }
//! }
//!
//! pub struct FooArrayBuilder<P> {
//!     p: P,
//! }
//!
//! impl<P> FooArrayBuilder<P>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
//!         p.writer().start_array(&tag)?;
//!
//!         Ok(Self { p })
//!     }
//!
//!     pub fn push(self) -> Result<FooBuilder<Self, 0>, Error> {
//!         FooBuilder::new(self, &TLVTag::Anonymous)
//!     }
//!
//!     pub fn end(mut self) -> Result<P, Error> {
//!         self.p.writer().end_container()?;
//!
//!         Ok(self.p)
//!     }
//! }
//!
//! impl<P> TLVBuilderParent for FooArrayBuilder<P>
//! where
//!     P: TLVBuilderParent,
//! {
//!     type Write = P::Write;
//!
//!     fn writer(&mut self) -> &mut Self::Write {
//!         self.p.writer()
//!     }
//!
//!     fn into_writer(self) -> Self::Write {
//!         self.p.into_writer()
//!     }
//! }
//!
//! impl<P> TLVBuilder<P> for FooArrayBuilder<P>
//! where
//!     P: TLVBuilderParent,
//! {
//!     fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
//!         Self::new(parent, tag)
//!     }
//! }
//!
//! pub struct BarBuilder<P, const F: usize> {
//!     p: P,
//! }
//!
//! impl<P> BarBuilder<P, 0>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
//!         p.writer().start_struct(tag)?;
//!
//!         Ok(Self { p })
//!     }
//!
//!     pub fn field1(mut self, value: i32) -> Result<BarBuilder<P, 1>, Error> {
//!         self.p.writer().i32(&TLVTag::Context(0), value)?;
//!
//!         Ok(BarBuilder {
//!             p: self.p,
//!         })
//!     }
//! }
//!
//! impl<P> BarBuilder<P, 1>
//! where
//!     P: TLVBuilderParent,
//! {
//!     pub fn finish(mut self) -> Result<P, Error> {
//!         self.p.writer().end_container()?;
//!
//!         Ok(self.p)
//!     }
//! }
//!
//! impl<P, const F: usize> TLVBuilderParent for BarBuilder<P, F>
//! where
//!     P: TLVBuilderParent,
//! {
//!     type Write = P::Write;
//!
//!     fn writer(&mut self) -> &mut Self::Write {
//!         self.p.writer()
//!     }
//!
//!     fn into_writer(self) -> Self::Write {
//!         self.p.into_writer()
//!     }
//! }
//!
//! impl<P> TLVBuilder<P> for BarBuilder<P, 0>
//! where
//!     P: TLVBuilderParent,
//! {
//!     fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
//!         Self::new(parent, tag)
//!     }
//! }
//!```

use core::marker::PhantomData;

use crate::error::Error;
use crate::tlv::{TLVTag, TLVWrite};

use super::{Nullable, Octets, ToTLV, Utf8Str};

/// The `TLVBuilder` trait is used to implement a TLV builder for a certain TLV type.
///
/// A TLV builder is a helper struct that allows for an ergonomic writing of its
/// corresponding TLV type into a `TLVWrite` trait implementation.
///
/// The TLV builders' implementation is zero-cost, in that it is completely erased to
/// raw TLV writes on the wrapped `TLVWrite` trait type by the compiler.
pub trait TLVBuilder<P>: Sized
where
    P: TLVBuilderParent,
{
    /// Create a new TLV builder for the given parent and tag.
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error>;

    /// Call a closure with the builder and return the result.
    fn with<F>(self, f: F) -> Result<P, Error>
    where
        F: FnOnce(Self) -> Result<P, Error>,
    {
        f(self)
    }

    /// Convert itself into a writer.
    ///
    /// Should be used when the user prefers to use the raw `TLVWrite`
    /// interface to write the TLV type.
    ///
    /// NOTE:
    /// Use this method with caution, as it will consume the builder!
    /// You are then on your own so as to write - using the parent's writer - the correct TLV data
    /// that is otherwise performed by the builder.
    fn unchecked_into_parent(self) -> P;
}

/// Each `TLVBuilder<P>` trait implementation has a parent - `P`
/// which should implement the `TLVBuilderParent` trait.
///
/// The `TLVBuilderParent` trait is used to provide a way for the
/// `TLVBuilder` to access the wrapped `TLVWrite` trait, as well as to model
/// the nesting of the TLV builders, for complex TLV types like structs-of-structs,
/// or arrays-of-structs and so on.
///
/// Also - by convention - once a `TLVBuilder` implementation has finished (ended),
/// it should return its parent type `P`. This provides for extra ertgonomics when
/// using the builder, as the user cannot "forget" to build the complete TLV type which
/// is expected.
#[cfg(not(feature = "defmt"))]
pub trait TLVBuilderParent: Sized + core::fmt::Debug {
    /// The type of the writer.
    type Write: TLVWrite;

    /// Return a mutable reference to the writer.
    fn writer(&mut self) -> &mut Self::Write;
}

#[cfg(feature = "defmt")]
pub trait TLVBuilderParent: Sized + core::fmt::Debug + defmt::Format {
    /// The type of the writer.
    type Write: TLVWrite;

    /// Return a mutable reference to the writer.
    fn writer(&mut self) -> &mut Self::Write;
}

/// A root-level TLV builder parent, that wraps a `TLVWrite` implementation.
pub struct TLVWriteParent<S, W>(S, W);

impl<S, W> TLVWriteParent<S, W> {
    /// Create a new `TLVWriteParent` for the given writer.
    pub const fn new(id: S, writer: W) -> Self {
        Self(id, writer)
    }
}

impl<S, W> core::fmt::Debug for TLVWriteParent<S, W>
where
    S: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.0)
    }
}

#[cfg(feature = "defmt")]
impl<S, W> defmt::Format for TLVWriteParent<S, W>
where
    S: core::fmt::Debug + defmt::Format,
{
    fn format(&self, fmt: defmt::Formatter) {
        defmt::write!(fmt, "{:?}", self.0);
    }
}

#[cfg(not(feature = "defmt"))]
impl<S, W> TLVBuilderParent for TLVWriteParent<S, W>
where
    S: core::fmt::Debug,
    W: TLVWrite,
{
    type Write = W;

    fn writer(&mut self) -> &mut Self::Write {
        &mut self.1
    }
}

#[cfg(feature = "defmt")]
impl<S, W> TLVBuilderParent for TLVWriteParent<S, W>
where
    S: core::fmt::Debug + defmt::Format,
    W: TLVWrite,
{
    type Write = W;

    fn writer(&mut self) -> &mut Self::Write {
        &mut self.1
    }
}

/// The `ToTLVBuilder` is a helper struct that allows for an ergonomic writing of
/// a TLV type that implements the `ToTLV` trait into a `TLVWrite` implementation.
///
/// This implementation is useful when the `T` type implements `ToTLV`.
///
/// Note that this implementation should be avoided when `T` has a large size, as it
/// needs the `T` instance to be materialized prior to writing into the TLV.
pub struct ToTLVBuilder<P, T> {
    parent: P,
    tag: TLVTag,
    _t: PhantomData<fn() -> T>,
}

impl<P, T> ToTLVBuilder<P, T>
where
    P: TLVBuilderParent,
    T: ToTLV + 'static,
{
    /// Create a new `ToTLVBuilder` for the given parent.
    pub fn new(parent: P, tag: &TLVTag) -> Self {
        Self {
            parent,
            tag: tag.clone(),
            _t: PhantomData,
        }
    }

    /// Write the TLV type into the writer.
    #[cfg(not(feature = "defmt"))]
    pub fn set(mut self, tlv: &T) -> Result<P, Error>
    where
        T: core::fmt::Debug,
    {
        #[cfg(feature = "log")]
        log::debug!("{:?}::TLV -> {:?} +", self, tlv);

        tlv.to_tlv(&self.tag, self.parent.writer())?;

        Ok(self.parent)
    }

    #[cfg(feature = "defmt")]
    pub fn set(mut self, tlv: &T) -> Result<P, Error>
    where
        T: core::fmt::Debug + defmt::Format,
    {
        defmt::debug!("{:?}::TLV[] -> {:?} +", self, tlv);

        tlv.to_tlv(&self.tag, self.parent.writer())?;

        Ok(self.parent)
    }
}

impl<P, T> core::fmt::Debug for ToTLVBuilder<P, T>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P, T> defmt::Format for ToTLVBuilder<P, T>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}", self.parent)
    }
}

impl<P, T> TLVBuilderParent for ToTLVBuilder<P, T>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P, T> TLVBuilder<P> for ToTLVBuilder<P, T>
where
    P: TLVBuilderParent,
    T: ToTLV + 'static,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Ok(Self::new(parent, tag))
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// The `ToTLVArrayBuilder` is a helper struct that allows for an ergonomic writing of
/// a TLV array into a `TLVWrite` implementation.
///
/// This implementation is useful when the `T` elements of the array implement `ToTLV`.
///
/// Note that this implementation should be avoided when `T` has a large size, as it
/// needs the `T` instances to be materialized prior to writing into the array.
pub struct ToTLVArrayBuilder<P, T> {
    _t: PhantomData<fn() -> T>,
    parent: P,
}

impl<P, T> ToTLVArrayBuilder<P, T>
where
    P: TLVBuilderParent,
    T: ToTLV + 'static,
{
    /// Create a new TLV array builder for the given parent and tag.
    pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
        p.writer().start_array(tag)?;

        Ok(Self {
            parent: p,
            _t: PhantomData,
        })
    }

    /// Push a new element into the array.
    #[cfg(not(feature = "defmt"))]
    pub fn push(mut self, tlv: &T) -> Result<Self, Error>
    where
        T: core::fmt::Debug,
    {
        #[cfg(feature = "log")]
        log::debug!("{:?}::TLV[] -> {:?} +", self, tlv);

        tlv.to_tlv(&TLVTag::Anonymous, self.parent.writer())?;

        Ok(self)
    }

    #[cfg(feature = "defmt")]
    pub fn push(mut self, tlv: &T) -> Result<Self, Error>
    where
        T: core::fmt::Debug + defmt::Format,
    {
        defmt::debug!("{:?}::TLV[] -> {:?} +", self, tlv);

        tlv.to_tlv(&TLVTag::Anonymous, self.parent.writer())?;

        Ok(self)
    }

    /// Finish the array and return the parent.
    pub fn end(mut self) -> Result<P, Error> {
        self.parent.writer().end_container()?;

        Ok(self.parent)
    }
}

impl<P, T> core::fmt::Debug for ToTLVArrayBuilder<P, T>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}[]", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P, T> defmt::Format for ToTLVArrayBuilder<P, T>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}[]", self.parent)
    }
}

impl<P, T> TLVBuilderParent for ToTLVArrayBuilder<P, T>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P, T> TLVBuilder<P> for ToTLVArrayBuilder<P, T>
where
    P: TLVBuilderParent,
    T: ToTLV + 'static,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Self::new(parent, tag)
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// A TLV builder for returning a Utf8 string value.
pub struct Utf8StrBuilder<P> {
    parent: P,
    tag: TLVTag,
}

impl<P> Utf8StrBuilder<P>
where
    P: TLVBuilderParent,
{
    /// Create a new `Utf8StrBuilder` for the given parent.
    pub fn new(parent: P, tag: &TLVTag) -> Self {
        Self {
            parent,
            tag: tag.clone(),
        }
    }

    /// Write the Utf8 string type into the writer.
    pub fn set(mut self, tlv: Utf8Str<'_>) -> Result<P, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::Utf8 -> {:?} +", self, tlv);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::Utf8 -> {:?} +", self, tlv);

        tlv.to_tlv(&self.tag, self.parent.writer())?;

        Ok(self.parent)
    }
}

impl<P> core::fmt::Debug for Utf8StrBuilder<P>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P> defmt::Format for Utf8StrBuilder<P>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}", self.parent)
    }
}

impl<P> TLVBuilderParent for Utf8StrBuilder<P>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P> TLVBuilder<P> for Utf8StrBuilder<P>
where
    P: TLVBuilderParent,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Ok(Self::new(parent, tag))
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// The `Utf8StrArrayBuilder` is a helper struct that allows for an ergonomic writing of
/// a TLV array containing Utf8 strings into a `TLVWrite` implementation.
pub struct Utf8StrArrayBuilder<P> {
    parent: P,
}

impl<P> Utf8StrArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    /// Create a new TLV Utf8 array builder for the given parent and tag.
    pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
        p.writer().start_array(tag)?;

        Ok(Self { parent: p })
    }

    /// Push a new Utf8 string into the array.
    pub fn push(mut self, tlv: Utf8Str<'_>) -> Result<Self, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::Utf8[] -> {:?} +", self, tlv);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::Utf8[] -> {:?} +", self, tlv);

        tlv.to_tlv(&TLVTag::Anonymous, self.parent.writer())?;

        Ok(self)
    }

    /// Finish the array and return the parent.
    pub fn end(mut self) -> Result<P, Error> {
        self.parent.writer().end_container()?;

        Ok(self.parent)
    }
}

impl<P> core::fmt::Debug for Utf8StrArrayBuilder<P>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}[]", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P> defmt::Format for Utf8StrArrayBuilder<P>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}[]", self.parent)
    }
}

impl<P> TLVBuilderParent for Utf8StrArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P> TLVBuilder<P> for Utf8StrArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Self::new(parent, tag)
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// A TLV builder for returning an octet string value.
pub struct OctetsBuilder<P> {
    parent: P,
    tag: TLVTag,
}

impl<P> OctetsBuilder<P>
where
    P: TLVBuilderParent,
{
    /// Create a new `OctetsBuilder` for the given parent.
    pub fn new(parent: P, tag: &TLVTag) -> Self {
        Self {
            parent,
            tag: tag.clone(),
        }
    }

    /// Write the TLV type into the writer.
    pub fn set(mut self, tlv: Octets<'_>) -> Result<P, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::Octets -> {:?} +", self, tlv);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::Octets -> {:?} +", self, tlv);

        tlv.to_tlv(&self.tag, self.parent.writer())?;

        Ok(self.parent)
    }
}

impl<P> core::fmt::Debug for OctetsBuilder<P>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P> defmt::Format for OctetsBuilder<P>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}", self.parent)
    }
}

impl<P> TLVBuilderParent for OctetsBuilder<P>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P> TLVBuilder<P> for OctetsBuilder<P>
where
    P: TLVBuilderParent,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Ok(Self::new(parent, tag))
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// The `OctetsArrayBuilder` is a helper struct that allows for an ergonomic writing of
/// a TLV array of octet strings into a `TLVWrite` implementation.
pub struct OctetsArrayBuilder<P> {
    parent: P,
}

impl<P> OctetsArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    /// Create a new octets TLV array builder for the given parent and tag.
    pub fn new(mut p: P, tag: &TLVTag) -> Result<Self, Error> {
        p.writer().start_array(tag)?;

        Ok(Self { parent: p })
    }

    /// Push a new octet string into the array.
    pub fn push(mut self, tlv: Octets<'_>) -> Result<Self, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::Octets[] -> {:?} +", self, tlv);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::Octets[] -> {:?} +", self, tlv);

        tlv.to_tlv(&TLVTag::Anonymous, self.parent.writer())?;

        Ok(self)
    }

    /// Finish the array and return the parent.
    pub fn end(mut self) -> Result<P, Error> {
        self.parent.writer().end_container()?;

        Ok(self.parent)
    }
}

impl<P> core::fmt::Debug for OctetsArrayBuilder<P>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}[]", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P> defmt::Format for OctetsArrayBuilder<P>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}[]", self.parent)
    }
}

impl<P> TLVBuilderParent for OctetsArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P> TLVBuilder<P> for OctetsArrayBuilder<P>
where
    P: TLVBuilderParent,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Self::new(parent, tag)
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// A builder for a nullable TLV type.
pub struct NullableBuilder<P, T> {
    parent: P,
    tag: TLVTag,
    _t: PhantomData<fn() -> T>,
}

impl<P, T> NullableBuilder<P, T>
where
    P: TLVBuilderParent,
    T: TLVBuilder<P>,
{
    /// Create a new nullable TLV builder for the given parent and tag.
    pub fn new(parent: P, tag: &TLVTag) -> Self {
        Self {
            parent,
            tag: tag.clone(),
            _t: PhantomData,
        }
    }

    /// Write a null value into the TLV and return the parent.
    pub fn null(mut self) -> Result<P, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::nullable -> null +", self);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::nullable -> null +", self);

        self.parent.writer().null(&self.tag)?;

        Ok(self.parent)
    }

    /// Create and return the builder for the non-null value.
    pub fn non_null(self) -> Result<T, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::nullable -> (not_null) +", self);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::nullable -> (not_null) +", self);

        T::new(self.parent, &self.tag)
    }

    /// If `condition` is `true`, call the closure with the non-null builder.
    /// If `condition` is `false`, write null and return the parent.
    pub fn with_non_null_if<F>(self, condition: bool, f: F) -> Result<P, Error>
    where
        F: FnOnce(T) -> Result<P, Error>,
    {
        if condition {
            f(self.non_null()?)
        } else {
            self.null()
        }
    }

    /// If the input is non-null, call the closure with the non-null builder and the input.
    /// If the input is null, write null and return the parent.
    pub fn with_non_null<I, F>(self, input: Nullable<I>, f: F) -> Result<P, Error>
    where
        F: FnOnce(&I, T) -> Result<P, Error>,
    {
        if let Some(input) = input.as_opt_ref() {
            f(input, self.non_null()?)
        } else {
            self.null()
        }
    }
}

impl<P, T> core::fmt::Debug for NullableBuilder<P, T>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P, T> defmt::Format for NullableBuilder<P, T>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}", self.parent)
    }
}

impl<P, T> TLVBuilderParent for NullableBuilder<P, T>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P, T> TLVBuilder<P> for NullableBuilder<P, T>
where
    P: TLVBuilderParent,
    T: TLVBuilder<P>,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Ok(Self::new(parent, tag))
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}

/// A builder for an optional TLV type.
pub struct OptionalBuilder<P, T> {
    parent: P,
    tag: TLVTag,
    _t: PhantomData<fn() -> T>,
}

impl<P, T> OptionalBuilder<P, T>
where
    P: TLVBuilderParent,
    T: TLVBuilder<P>,
{
    /// Create a new optional TLV builder for the given parent and tag.
    pub fn new(parent: P, tag: &TLVTag) -> Self {
        Self {
            parent,
            tag: tag.clone(),
            _t: PhantomData,
        }
    }

    /// Skip writing the TLV type and return the parent.
    pub fn none(self) -> P {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::optional -> none +", self);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::optional -> none +", self);

        self.parent
    }

    /// Create and return the builder for the non-optional value.
    pub fn some(self) -> Result<T, Error> {
        #[cfg(feature = "defmt")]
        defmt::debug!("{:?}::optional -> (some) +", self);
        #[cfg(feature = "log")]
        ::log::debug!("{:?}::optional -> (some) +", self);

        T::new(self.parent, &self.tag)
    }

    /// If `condition` is `true`, call the closure with the non-optional builder.
    /// If `condition` is `false`, return the parent.
    pub fn with_some_if<F>(self, condition: bool, f: F) -> Result<P, Error>
    where
        F: FnOnce(T) -> Result<P, Error>,
    {
        if condition {
            f(self.some()?)
        } else {
            Ok(self.none())
        }
    }

    /// If the input is `Some`, call the closure with the non-optional builder and the input.
    /// If the input is `None`, return the parent.
    pub fn with_some<I, F>(self, input: Option<I>, f: F) -> Result<P, Error>
    where
        F: FnOnce(&I, T) -> Result<P, Error>,
    {
        if let Some(input) = input.as_ref() {
            f(input, self.some()?)
        } else {
            Ok(self.none())
        }
    }
}

impl<P, T> core::fmt::Debug for OptionalBuilder<P, T>
where
    P: core::fmt::Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{:?}", self.parent)
    }
}

#[cfg(feature = "defmt")]
impl<P, T> defmt::Format for OptionalBuilder<P, T>
where
    P: defmt::Format,
{
    fn format(&self, f: defmt::Formatter<'_>) {
        defmt::write!(f, "{:?}", self.parent)
    }
}

impl<P, T> TLVBuilderParent for OptionalBuilder<P, T>
where
    P: TLVBuilderParent,
{
    type Write = P::Write;

    fn writer(&mut self) -> &mut Self::Write {
        self.parent.writer()
    }
}

impl<P, T> TLVBuilder<P> for OptionalBuilder<P, T>
where
    P: TLVBuilderParent,
    T: TLVBuilder<P>,
{
    fn new(parent: P, tag: &TLVTag) -> Result<Self, Error> {
        Ok(Self::new(parent, tag))
    }

    fn unchecked_into_parent(self) -> P {
        self.parent
    }
}