More

Author: LaurenzV

src/object.rs

@@ -651,6 +651,14 @@ impl<'a> Obj<'a> {
     /// Write a primitive object.
     #[inline]
     pub fn primitive<T: Primitive>(self, value: T) {
+        // Normally, we need to separate different PDF objects by a whitespace. he key to the
+        // optimizations applied here are explained in 7.2.3 in the PDF reference:
+        // > The delimiter characters (, ), <, >, [, ], /, and % are special. They
+        // > delimit syntactic entities such as arrays, names, and comments. Any of these
+        // > delimiters terminates the entity preceding it and is not included in the entity.
+        // Therefore, if either the previous byte is a delimiter character or the current token
+        // starts with one, we don't need to add a whitespace for padding.
+
         let ends_with_delimiter =
             self.buf.last().copied().is_some_and(is_delimiter_character);
 
@@ -659,6 +667,7 @@ impl<'a> Obj<'a> {
         }
 
         value.write(self.buf);
+
         if self.indirect {
             self.buf.extend(b"\nendobj\n");
 
@@ -668,6 +677,9 @@ impl<'a> Obj<'a> {
         }
     }
 
+    // Note: Arrays and dictionaries always start with a delimiter, so we don't need to do any case
+    // distinction, unlike in `primitive`.
+
     /// Start writing an array.
     #[inline]
     pub fn array(self) -> Array<'a> {
@@ -763,7 +775,9 @@ impl<'a> Array<'a> {
         } else {
             false
         };
+
         self.len += 1;
+
         Obj::direct(self.buf, self.indent, self.settings, needs_padding)
     }
 
@@ -915,6 +929,8 @@ impl<'a> Dict<'a> {
     pub fn insert(&mut self, key: Name) -> Obj<'_> {
         self.len += 1;
 
+        // Keys always start with a delimiter since they are names, so we never need
+        // padding unless `pretty` is activated.
         if self.settings.pretty {
             self.buf.push(b'\n');
 
@@ -924,6 +940,7 @@ impl<'a> Dict<'a> {
         }
 
         self.buf.push_val(key);
+
         let needs_padding = if self.settings.pretty {
             self.buf.push(b' ');
             false