1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

//! A trait for all domain name types.

use std::borrow::Cow;
use super::super::{Composer, ComposeResult};
use super::{DNameSlice, NameLabels, NameLabelettes};


//------------ DName ---------------------------------------------------------

/// A trait implemented by all domain name types.
///
/// The purpose of the trait is to allow building composite types that are
/// generic over all possible variants of domain names. In particular,
/// `DName` is implemented for [`&DNameSlice`] for references to uncompressed
/// domain names, [`DNameBuf`] for owned uncompressed domain names, and
/// [`ParsedDName`] for domain names parsed from DNS messages.
///
/// If you don’t need to include [`ParsedDName`], you might want your type
/// to be generic over `AsRef<DNameSlice>` instead as this allows for the
/// full range of functionality provided by [`DNameSlice`].
///
/// [`&DNameSlice`]: struct.DNameSlice.html
/// [`DNameBuf`]: struct.DNameBuf.html
/// [`ParsedDName`]: struct.ParsedDName.html
pub trait DName: Sized {
    /// Converts the name into an uncompressed name.
    ///
    /// Since unpacking parsed domain names may need allocations to collect
    /// the labels, the return value is a cow. This cow will, however, be of
    /// the borrowed variant whenever possible.
    fn to_cow(&self) -> Cow<DNameSlice>;

    /// Returns an iterator over the labels of the domain name.
    fn labels(&self) -> NameLabels;

    /// Returns an iterator over the labelettes of the domain name.
    ///
    /// See [`Labelette`] for a discussion of what exactly labelettes are.
    ///
    /// [`Labelette`]: struct.Labelette.html
    fn labelettes(&self) -> NameLabelettes {
        NameLabelettes::new(self.labels())
    }

    /// Appends the name to the end of a composition.
    fn compose<C: AsMut<Composer>>(&self, mut composer: C)
                                   -> ComposeResult<()> {
        composer.as_mut().compose_dname(self)
    }

    /// Appends the name to the end of a composition using name compression.
    fn compose_compressed<C: AsMut<Composer>>(&self, mut composer: C)
                                              -> ComposeResult<()> {
        composer.as_mut().compose_dname_compressed(self)
    }
}