feat: add Category::to_full_name() to easily generate full names from short ones.

Author: Byron

gix-ref/src/fullname.rs

@@ -156,6 +156,35 @@ impl FullNameRef {
     }
 }
 
+/// Conversion
+impl Category<'_> {
+    /// As the inverse of [`FullNameRef::category_and_short_name()`], use the prefix of this category alongside
+    /// the `short_name` to create a valid fully qualified [reference name](FullName).
+    pub fn to_full_name<'a>(&self, short_name: impl Into<&'a BStr>) -> Result<FullName, crate::name::Error> {
+        let mut out: BString = self.prefix().into();
+        let short_name = short_name.into();
+        let partial_name = match self {
+            Category::Note => short_name.strip_prefix("notes/".as_bytes()).unwrap_or(short_name),
+            Category::MainRef => short_name.strip_prefix("refs/".as_bytes()).unwrap_or(short_name),
+            Category::LinkedPseudoRef { name } | Category::LinkedRef { name } => {
+                out.extend_from_slice(name);
+                out.push(b'/');
+                short_name
+            }
+            Category::Bisect => short_name.strip_prefix("bisect/".as_bytes()).unwrap_or(short_name),
+            Category::Rewritten => short_name.strip_prefix("rewritten/".as_bytes()).unwrap_or(short_name),
+            Category::WorktreePrivate => short_name.strip_prefix("worktree/".as_bytes()).unwrap_or(short_name),
+            Category::Tag
+            | Category::LocalBranch
+            | Category::RemoteBranch
+            | Category::PseudoRef
+            | Category::MainPseudoRef => short_name,
+        };
+        out.extend_from_slice(partial_name);
+        FullName::try_from(out)
+    }
+}
+
 impl FullName {
     /// Convert this name into the relative path, lossily, identifying the reference location relative to a repository
     pub fn to_path(&self) -> &Path {

gix-ref/tests/refs/fullname.rs

@@ -81,10 +81,23 @@ fn shorten_and_category() {
         assert_eq!(name.as_ref().shorten(), expected);
         assert_eq!(name.shorten(), expected);
         assert_eq!(name.category(), category);
-        assert_eq!(
-            name.category_and_short_name(),
-            category.map(|cat| (cat, expected.into()))
-        );
+
+        let cat_and_short_name = name.category_and_short_name();
+        match category {
+            None => {
+                assert_eq!(cat_and_short_name, None);
+            }
+            Some(expected_category) => {
+                assert_eq!(cat_and_short_name, Some((expected_category, expected.into())));
+                let (cat, short_name) = cat_and_short_name.expect("we know it's set");
+                let actual = cat.to_full_name(short_name).expect("valid input = valid output");
+                assert_eq!(
+                    actual.as_ref().as_bstr(),
+                    input,
+                    "{input}: {cat:?}:{short_name}: categories and short-names can round-trip"
+                );
+            }
+        }
         assert_eq!(name.as_ref().category(), category);
     }
 
@@ -97,6 +110,11 @@ fn shorten_and_category() {
         );
         assert_eq!(name.category(), None);
     }
+
+    assert!(
+        Category::LocalBranch.to_full_name("invalid/").is_err(),
+        "validation is performed as one would expect"
+    );
 }
 
 #[test]

gix-ref/tests/refs/main.rs

@@ -8,6 +8,35 @@ pub use gix_testtools::Result;
 
 mod file;
 mod fullname;
+mod partialname {
+    use gix_ref::PartialName;
+
+    #[test]
+    fn join() -> crate::Result {
+        let pn = PartialName::try_from("no-trailing-slash")?;
+        assert_eq!(pn.join("name".into())?.as_ref().as_bstr(), "no-trailing-slash/name");
+
+        let err = PartialName::try_from("trailing-slash/").unwrap_err();
+        assert!(
+            matches!(
+                err,
+                gix_validate::reference::name::Error::Tag(gix_validate::tag::name::Error::EndsWithSlash)
+            ),
+            "thanks to this there is no worry about dealing with this case"
+        );
+
+        let pn = PartialName::try_from("prefix")?;
+        let err = pn.join("/slash-in-name".into()).unwrap_err();
+        assert!(
+            matches!(
+                err,
+                gix_validate::reference::name::Error::Tag(gix_validate::tag::name::Error::RepeatedSlash)
+            ),
+            "validation post-join assures the returned type is valid"
+        );
+        Ok(())
+    }
+}
 mod namespace;
 mod packed;
 mod reference;