From 7074dd86b98ebf10c157c19262cf80fc46e78f0c Mon Sep 17 00:00:00 2001
From: "Steven R. Loomis" <srl295@gmail.com>
Date: Wed, 24 Jan 2024 14:34:18 -0600
Subject: [PATCH] CLDR-17327 speedup VoteResolver's transcript

- add and correct some comments
---
 .../unicode/cldr/util/DeferredTranscript.java | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/tools/cldr-code/src/main/java/org/unicode/cldr/util/DeferredTranscript.java b/tools/cldr-code/src/main/java/org/unicode/cldr/util/DeferredTranscript.java
index 48a6fa9201f..9d56cdf9d5c 100644
--- a/tools/cldr-code/src/main/java/org/unicode/cldr/util/DeferredTranscript.java
+++ b/tools/cldr-code/src/main/java/org/unicode/cldr/util/DeferredTranscript.java
@@ -7,8 +7,15 @@
 import java.util.stream.Collectors;
 
 /**
- * lazily-calculates the transcript. Thread safe to call get() multiple times once commit() is
- * called and before clear() is called.
+ * A deferred list of formatted strings, one per line. The formatting is deferred until when (and
+ * if) get() is called. It's thread safe to call get() multiple times, but add() should be called
+ * from a single thread.
+ *
+ * <p>Once get() is called, the contents are 'resolved' into a string, and subsequent get() calls
+ * will return the same string (even if add() was called). To re-use the object, call clear() and
+ * then new content can be added with add().
+ *
+ * <p>In testing, there was a significant speed-up for the use case where get() might not be called.
  */
 public class DeferredTranscript implements Supplier<String> {
 
@@ -16,11 +23,13 @@ private final class FormatEntry {
         public final CharSequence fmt;
         public final Object[] args;
 
+        /** Add a new FormatEntry as a deferred format */
         public FormatEntry(String fmt, Object[] args) {
             this.fmt = fmt;
             this.args = args;
         }
 
+        /** Output this entry as a CharSequence, performing any formatting needed. */
         public final CharSequence format() {
             if (args == null || args.length == 0) {
                 return fmt;
@@ -30,14 +39,18 @@ public final CharSequence format() {
         }
     }
 
+    /** clear the DeferredTranscript on startup */
     public DeferredTranscript() {
         clear();
     }
 
+    /** The first time this is read, it will calculate the entire string. */
     private Supplier<String> delegate = null;
+
+    /** cached formats */
     private List<FormatEntry> formats;
 
-    /** reset this transcript so it can be used again. */
+    /** reset this transcript so it can be added to again. */
     public void clear() {
         // the delegate only calculates the value once, the first time it is accessed.
         delegate =
@@ -60,7 +73,8 @@ public final String get() {
     }
 
     /**
-     * Add a formatted entry. Will be ignored if get() has been called since clear()
+     * Add a formatted entry. Will have no effect if get() has been called since clear() or object
+     * construction.
      *
      * @param fmt the string or pattern string
      * @param args if non-null, arguments to String.format()