PersonIdent: Document that name and email aren't trimmed

This might be somewhat surprising behavior to users who might
naturally assume the following invariant:
  ident.equals(parseIdent(ident.toExternalString()))

This invariant does not hold since whitespace is only trimmed during
serialization. We don't want to mess with the strings during
initialization, as this is called during the highly-optimized commit
parsing codepath.

Change-Id: I081a603f0ac0e33167462244779b0ff3ad51e80c

diff --git a/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/T0001_PersonIdentTest.java b/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/T0001_PersonIdentTest.java
index 1515a07ac49101f43d5f5b8d0537896e77596233..48d2c480a949708a8dbe622e0b85476365f2fb30 100644 (file)
--- a/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/T0001_PersonIdentTest.java
+++ b/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/T0001_PersonIdentTest.java
@@ -92,8 +92,10 @@ public class T0001_PersonIdentTest {
                PersonIdent personIdent = new PersonIdent("  A U Thor  ",
                                "  author@example.com  ");
 
-               String externalString = personIdent.toExternalString();
+               assertEquals("  A U Thor  ", personIdent.getName());
+               assertEquals("  author@example.com  ", personIdent.getEmailAddress());
 
+               String externalString = personIdent.toExternalString();
                assertTrue(externalString.startsWith("A U Thor <author@example.com>"));
        }
 

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java
index 2ecc60c3b62b8f3ac98cd7cd7a0d978fd3d27617..aa304634baed60d0614dd6e6d904ffcf554c9ffe 100644 (file)
--- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java
@@ -217,7 +217,12 @@ public class PersonIdent implements Serializable {
        }
 
        /**
-        * Construct a {@link PersonIdent}
+        * Construct a {@link PersonIdent}.
+        * <p>
+        * Whitespace in the name and email is preserved for the lifetime of this
+        * object, but are trimmed by {@link #toExternalString()}. This means that
+        * parsing the result of {@link #toExternalString()} may not return an
+        * equivalent instance.
         *
         * @param aName
         * @param aEmailAddress