Document Dice better, CHANGES too.

CHANGES.txt

@@ -5,14 +5,17 @@ Dependencies:
  - squidlib-extra: libGDX 1.10.0
 Changes:
  - BREAKING: AbstractRNG's code that generated longs in a bounded range had some issues, and so did RNG. Both have been fixed, which may change bounded long generation (which tends to be rare).
+ - SEED BREAKING (unless you use an archive): Thesaurus can now generate vegetable, nut, shrub, and flower names, not just fruit.
+ - SEED BREAKING: The Ridged subclasses of Noise now default to rotating octaves after the first, which helps avoid artifacts with several types of noise.
+ - Continuing the above, FastNoise allows rotating later octaves with its "fractalSpiral" setting; it defaults to false (unchanged from earlier versions).
  - OpenSimplex2's "S" (smooth) and "F" (fast) versions have been added to SquidLib, though they have to "fake seeds" by sampling different coordinates for different seeds.
- - SEED BREAKING (unless you use an archive): Thesaurus can now generate vegetable names, and not just fruit.
  - Thesaurus also has a ZOMBIE mode, for the enlightened few of the walking dead that can murmur out partial sentences.
  - StringKit.appendJoined() methods simultaneously join items from an array or Collection and append them to a StringBuilder.
  - Some changes to SquidMouse, mostly for readability.
  - Speedup for NumberTools.atan2(), plus an implementation for atan() to round out the trigonometric functions.
  - Inconsolata LGC now has an MSDF version in the assets.
  - Lots of improvements and small visual changes to existing fonts (mostly "stretchable" distance field fonts).
+ - New features in Dice: you can store the data needed to describe a rule for rolling dice, to avoid parsing again.
 
 3.0.3
 Dependencies:

squidlib-util/src/main/java/squidpony/squidmath/Dice.java

@@ -427,7 +427,28 @@ else if("!".equals(mode))
         return prev;
     }
 
-    public IntVLA parseRollRuleInto(IntVLA into, String rollCode){
+    /**
+     * Parses the given dice roll notation in {@code rollCode} and returns the data needed to perform that roll, as an
+     * IntVLA called a roll rule here. You can roll such a roll rule with {@link #runRollRule(IntVLA)}, any number of
+     * times, and get different results on different rolls even with the same rule. This saves time spent and garbage
+     * produced parsing the roll code for each roll with {@link #roll(String)}.
+     * @param rollCode a String or other CharSequence holding dice roll notation, like "3d8+5" (see {@link #roll(String)})
+     * @return {@code into}, after the roll rule has been appended
+     */
+    public IntVLA parseRollRule(CharSequence rollCode) {
+        return parseRollRuleInto(new IntVLA(), rollCode);
+    }
+    /**
+     * Parses the given dice roll notation in {@code rollCode} and puts out the data needed to perform that roll into
+     * {@code into}, where {@code into} is usually an empty IntVLA, and is called a roll rule here. You can roll such a
+     * roll rule with {@link #runRollRule(IntVLA)}, any number of times, and get different results on different rolls
+     * even with the same rule. This saves time spent and garbage produced parsing the roll code for each roll with
+     * {@link #roll(String)}.
+     * @param into a usually-empty IntVLA that will have a roll rule appended to its contents
+     * @param rollCode a String or other CharSequence holding dice roll notation, like "3d8+5" (see {@link #roll(String)})
+     * @return {@code into}, after the roll rule has been appended
+     */
+    public IntVLA parseRollRuleInto(IntVLA into, CharSequence rollCode){
         mat2.setTarget(rollCode);
         int op = mat2.pattern().groupId("op");
         int sn = mat2.pattern().groupId("sn");
@@ -470,6 +491,13 @@ public IntVLA parseRollRuleInto(IntVLA into, String rollCode){
         return into;
     }
 
+    /**
+     * Attempts to run the given roll rule stored in the given IntVLA, returning the result as if rolling the dice as it
+     * describes. You can use {@link #parseRollRule(CharSequence)} or {@link #parseRollRuleInto(IntVLA, CharSequence)}
+     * to get such a roll rule.
+     * @param rollRule an IntVLA as returned by {@link #parseRollRule(CharSequence)} or {@link #parseRollRuleInto(IntVLA, CharSequence)}
+     * @return the result of one roll of the given rule
+     */
     public int runRollRule(IntVLA rollRule) {
         if(rollRule == null || rollRule.isEmpty()) return 0;
         int currentResult, previousTotal = 0;

squidlib/src/test/java/squidpony/gdx/tests/issues/Issue6519.java

@@ -15,8 +15,8 @@
 
 public class Issue6519 extends ApplicationAdapter {
     public static class GraphicalTerm {
-        private static final FileHandle GNUnicode = Gdx.files.classpath("7-12-serif.fnt");
-        private static final FileHandle GNUnicode_images = Gdx.files.classpath("7-12-serif.png");
+        private static final FileHandle serif = Gdx.files.classpath("7-12-serif.fnt");
+        private static final FileHandle serifImage = Gdx.files.classpath("7-12-serif.png");
         static BitmapFont font;
         public final int Height, Width;
         public final int Top;
@@ -77,7 +77,7 @@ public boolean SetChar(int x, int y, char c) {
         }
 
         public void Create() {
-            font = new BitmapFont(GNUnicode, GNUnicode_images, false);
+            font = new BitmapFont(serif, serifImage, false);
             font.setUseIntegerPositions(false);
             setAllFixedWidth(font);
         }