Merge pull request 'Add conversion traits to Builder' (#12) from alch_emii/maj-prs:to-string into main

Reviewed-on: cadey/maj#12

gemtext/src/lib.rs

@@ -54,11 +54,53 @@ impl Builder {
     }
 }
 
+impl ToString for Builder {
+    /// Render a document to a string
+    ///
+    /// This produces a text/gemini compliant text document, represented as a string
+    fn to_string(&self) -> String {
+        let len: usize = self.nodes.iter().map(Node::estimate_len).sum(); // sum up node lengths
+        let mut bytes = Vec::with_capacity(len + self.nodes.len()); // add in inter-node newlines
+        render(self, &mut bytes).unwrap(); // Writing to a string shouldn't produce errors
+
+        unsafe {
+            // This is safe because bytes is composed of Strings.  We could have this as
+            // pure safe code by replicating the `render()` method and switching it to use
+            // a fmt::Write (or even `String::push()`)instead of a io::Write, but this has
+            // the same effect, with much DRYer code.
+            String::from_utf8_unchecked(bytes)
+        }
+    }
+}
+
+impl AsRef<[Node]> for Builder {
+    /// Get a reference to the internal node list of this builder
+    fn as_ref(&self) -> &[Node] {
+        self.nodes.as_ref()
+    }
+}
+
+impl AsMut<[Node]> for Builder {
+    /// Get a mutable reference to the internal node list of this builder
+    fn as_mut(&mut self) -> &mut [Node] {
+        self.nodes.as_mut()
+    }
+}
+
+impl From<Builder> for Vec<Node> {
+    /// Convert into a collection of [`Node`]s.
+    ///
+    /// Equivilent to calling [`Builder::build()`]
+    fn from(builder: Builder) -> Self {
+        builder.build()
+    }
+}
+
 /// Render a set of nodes as a document to a writer.
-pub fn render(nodes: Vec<Node>, out: &mut impl Write) -> io::Result<()> {
+pub fn render(nodes: impl AsRef<[Node]>, out: &mut impl Write) -> io::Result<()> {
     use Node::*;
 
-    for node in nodes {
+    for node in nodes.as_ref() {
         match node {
             Text(body) => {
                 let special_prefixes = ["=>", "```", "#", "*", ">"];
@@ -72,7 +114,7 @@ pub fn render(nodes: Vec<Node>, out: &mut impl Write) -> io::Result<()> {
                 None => write!(out, "=> {}\n", to)?,
             },
             Preformatted(body) => write!(out, "```\n{}\n```\n", body)?,
-            Heading { level, body } => write!(out, "{} {}\n", "#".repeat(level as usize), body)?,
+            Heading { level, body } => write!(out, "{} {}\n", "#".repeat(*level as usize), body)?,
             ListItem(body) => write!(out, "* {}\n", body)?,
             Quote(body) => write!(out, "> {}\n", body)?,
         };
@@ -166,6 +208,47 @@ impl Node {
     pub fn blank() -> Node {
         Node::Text("".to_string())
     }
+
+    /// Cheaply estimate the length of this node
+    ///
+    /// This measures length in bytes, *not characters*.  So if the user includes
+    /// non-ascii characters, a single one of these characters may add several bytes to
+    /// the length, despite only displaying as one character.
+    ///
+    /// This does include any newlines, but not any trailing newlines.  For example, a
+    /// preformatted text block containing a single line reading "trans rights! 🏳️‍⚧️"
+    /// would have a length of 30:  3 backticks, a newline, the text (including 16 bytes
+    /// for the trans flag), another newline, and another 3 backticks.
+    ///
+    /// ```
+    /// # use gemtext::Node;
+    /// let simple_text = Node::Text(String::from("Henlo worl"));
+    /// let linky_link = Node::Link { to: "gemini://cetacean.club/maj/".to_string(), name: Some("Maj".to_string()) };
+    /// let human_rights = Node::Preformatted("trans rights! 🏳️‍⚧️".to_string());;
+    ///
+    /// assert_eq!(
+    ///     simple_text.estimate_len(),
+    ///     "Henlo worl".as_bytes().len()
+    /// );
+    /// assert_eq!(
+    ///     linky_link.estimate_len(),
+    ///     "=> gemini://cetacean.club/maj/ Maj".as_bytes().len()
+    /// );
+    /// assert_eq!(
+    ///     human_rights.estimate_len(),
+    ///     "```\ntrans rights! 🏳️‍⚧️\n```".as_bytes().len()
+    /// );
+    /// ```
+    pub fn estimate_len(&self) -> usize {
+        match self {
+            Self::Text(text) => text.len(),
+            Self::Link { to, name } => 3 + to.as_bytes().len() +
+                name.as_ref().map(|n| n.as_bytes().len() + 1).unwrap_or(0),
+            Self::Preformatted(text) => text.as_bytes().len() + 8,
+            Self::Heading { level, body } => *level as usize + 1 + body.as_bytes().len(),
+            Self::ListItem(item) | Self::Quote(item)=> 2 + item.as_bytes().len(),
+        }
+    }
 }
 
 pub fn parse(doc: &str) -> Vec<Node> {