Struct DebugMap 

pub struct DebugMap<'a, 'b: 'a> { /* private fields */ }

A struct to help with fmt::Debug implementations.

This is useful when you wish to output a formatted map as a part of your Debug::fmt implementation.

This can be constructed by the Formatter::debug_map method.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"A": 10, "B": 11}"#,
);

Implementations

impl<'a, 'b: 'a> DebugMap<'a, 'b>

pub fn entry(&mut self, key: &dyn Debug, value: &dyn Debug) -> &mut Self

Adds a new entry to the map output.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map()
           .entry(&"whole", &self.0) // We add the "whole" entry.
           .finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"whole": [("A", 10), ("B", 11)]}"#,
);

pub fn key(&mut self, key: &dyn Debug) -> &mut Self

Adds the key part of a new entry to the map output.

This method, together with value, is an alternative to entry that can be used when the complete entry isn’t known upfront. Prefer the entry method when it’s possible to use.

Panics

key or key_with must be called before value or value_with, and each key call must be followed by a corresponding value call. Otherwise this method will panic.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map()
           .key(&"whole").value(&self.0) // We add the "whole" entry.
           .finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"whole": [("A", 10), ("B", 11)]}"#,
);

pub fn key_with( &mut self, key_fmt: impl FnOnce(&mut Formatter<'_>) -> Result, ) -> &mut Self

Adds the key part of a new entry to the map output.

This method is equivalent to DebugMap::key, but formats the key using a provided closure rather than by calling Debug::fmt.

Panics

key or key_with must be called before value or value_with, and each key call must be followed by a corresponding value call. Otherwise this method will panic.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut map = fmt.debug_map();
        for (k, v) in &self.0 {
            // Append "entry" to each key
            map.key_with(|fmt| write!(fmt, "entry {k}"));
            // Write values as hex
            map.value_with(|fmt| write!(fmt, "{v:#010x}"));
        }
        map.finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{entry A: 0x0000000a, entry B: 0x0000000b}"#,
);

pub fn value(&mut self, value: &dyn Debug) -> &mut Self

Adds the value part of a new entry to the map output.

This method, together with key, is an alternative to entry that can be used when the complete entry isn’t known upfront. Prefer the entry method when it’s possible to use.

Panics

key or key_with must be called before value or value_with, and each key call must be followed by a corresponding value call. Otherwise this method will panic.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map()
           .key(&"whole").value(&self.0) // We add the "whole" entry.
           .finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"whole": [("A", 10), ("B", 11)]}"#,
);

pub fn value_with( &mut self, value_fmt: impl FnOnce(&mut Formatter<'_>) -> Result, ) -> &mut Self

Adds the value part of a new entry to the map output.

This method is equivalent to DebugMap::value, but formats the value using a provided closure rather than by calling Debug::fmt.

Panics

key or key_with must be called before value or value_with, and each key call must be followed by a corresponding value call. Otherwise this method will panic.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut map = fmt.debug_map();
        for (k, v) in &self.0 {
            // Append "entry" to each key
            map.key_with(|fmt| write!(fmt, "entry {k}"));
            // Write values as hex
            map.value_with(|fmt| write!(fmt, "{v:#010x}"));
        }
        map.finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{entry A: 0x0000000a, entry B: 0x0000000b}"#,
);

pub fn entries<K, V, I>(&mut self, entries: I) -> &mut Self

where K: Debug, V: Debug, I: IntoIterator<Item = (K, V)>,

Adds the contents of an iterator of entries to the map output.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map()
           // We map our vec so each entries' first field will become
           // the "key".
           .entries(self.0.iter().map(|&(ref k, ref v)| (k, v)))
           .finish()
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"A": 10, "B": 11}"#,
);

pub fn finish_non_exhaustive(&mut self) -> Result

Marks the map as non-exhaustive, indicating to the reader that there are some other entries that are not shown in the debug representation.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        // Print at most two elements, abbreviate the rest
        let mut f = fmt.debug_map();
        let mut f = f.entries(self.0.iter().take(2).map(|&(ref k, ref v)| (k, v)));
        if self.0.len() > 2 {
            f.finish_non_exhaustive()
        } else {
            f.finish()
        }
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![
        ("A".to_string(), 10),
        ("B".to_string(), 11),
        ("C".to_string(), 12),
    ])),
    r#"{"A": 10, "B": 11, ..}"#,
);

pub fn finish(&mut self) -> Result

Finishes output and returns any error encountered.

Panics

key or key_with must be called before value or value_with, and each key call must be followed by a corresponding value call. Otherwise this method will panic.

Examples

use std::fmt;

struct Foo(Vec<(String, i32)>);

impl fmt::Debug for Foo {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_map()
           .entries(self.0.iter().map(|&(ref k, ref v)| (k, v)))
           .finish() // Ends the map formatting.
    }
}

assert_eq!(
    format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])),
    r#"{"A": 10, "B": 11}"#,
);