Bug: add_named_destination() maintains named destination list sort order (#1930)

To quote the "Table 36 – Entries in a name tree node dictionary" the part about the `Names` key:

> The keys shall be sorted in lexical order, as described below. [...]
>
> The Names entries in the leaf (or root) nodes shall contain the tree’s keys and their
associated values, arranged in key-value pairs and shall be sorted lexically in ascending order by key. Shorter
keys shall appear before longer ones beginning with the same byte sequence. Any encoding of the keys may
be used as long as it is self-consistent; keys shall be compared for equality on a simple byte-by-byte basis.

Fixes #1927

Author: robertkearns

pypdf/_writer.py

@@ -1997,10 +1997,10 @@ def add_named_destination(
         )
 
         dest_ref = self._add_object(dest)
-        nd = self.get_named_dest_root()
         if not isinstance(title, TextStringObject):
             title = TextStringObject(str(title))
-        nd.extend([title, dest_ref])
+
+        self.add_named_destination_array(title, dest_ref)
         return dest_ref
 
     def addNamedDestination(

tests/test_writer.py

@@ -607,6 +607,32 @@ def test_add_named_destination(pdf_file_path):
         writer.write(output_stream)
 
 
+def test_add_named_destination_sort_order(pdf_file_path):
+    """
+    Issue #1927 does not appear.
+
+    add_named_destination() maintains the named destination list sort order
+    """
+    writer = PdfWriter()
+
+    assert writer.get_named_dest_root() == []
+
+    writer.add_blank_page(200, 200)
+    writer.add_named_destination("b", 0)
+    # "a" should be moved before "b" on insert
+    writer.add_named_destination("a", 0)
+
+    root = writer.get_named_dest_root()
+
+    assert len(root) == 4
+    assert root[0] == "a", '"a" was not inserted before "b" in the named destination root'
+    assert root[2] == "b"
+
+    # write "output" to pypdf-output.pdf
+    with open(pdf_file_path, "wb") as output_stream:
+        writer.write(output_stream)
+
+
 def test_add_uri(pdf_file_path):
     reader = PdfReader(RESOURCE_ROOT / "pdflatex-outline.pdf")
     writer = PdfWriter()