Additional documentation, and test for: PR #87 - Fix string comparison to avoid using the collator
diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java
index 82b89d3..2558bfb 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -24,6 +24,7 @@
import java.io.Writer;
import java.lang.reflect.InvocationTargetException;
import java.net.URLConnection;
+import java.text.Collator;
import java.text.DecimalFormat;
import java.text.SimpleDateFormat;
import java.util.Collection;
@@ -976,6 +977,21 @@
* </li>
* </ul>
* </li>
+ * <li>
+ * <p>
+ * 2.3.33 (or higher):
+ * <ul>
+ * <li><p>Comparing string is now way faster. If your template does lot of string comparisons, this can
+ * mean very significant speedup. We now use a simpler way of comparing strings, and because templates
+ * were only ever allowed equality comparisons between strings (not less-than, or greater-than), it's very
+ * unlikely to change the behavior of your templates. (Technically, what changes is that instead of using
+ * Java's localized {@link Collator}-s, we switch to a simple binary comparison after UNICODE NFKC
+ * normalization. So, in theory it's possible that for some locales two different but similarly looking
+ * characters were treated as equal by the collator, but will count as different now. But it's very
+ * unlikely that anyone wanted to depend on such fragile logic anyway. Note again that we still do UNICODE
+ * normalization, so combining characters won't break your comparison.)</p></li>
+ * </ul>
+ * </li>
* </ul>
*
* @throws IllegalArgumentException
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index ab7368c..c1bf77c 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -30070,7 +30070,25 @@
<itemizedlist>
<listitem>
- <para>[TODO]</para>
+ <para><link
+ xlink:href="https://github.com/apache/freemarker/pull/87">GitHub
+ PR 87</link> Comparing string is now way faster, if the <link
+ linkend="pgui_config_incompatible_improvements_how_to_set"><literal>incompatible_improvements</literal>
+ setting</link> is at least 2.3.33. If your template does lot of
+ string comparisons, this can mean very significant speedup. With
+ this enabled, we use a simpler way of comparing strings, and
+ because templates were only ever allowed equality comparisons
+ between strings (not less-than, or greater-than), it's very
+ unlikely to change the behavior of your templates. (Technically,
+ what changes is that instead of using Java's localized
+ <literal>Collator</literal>-s, we switch to a simple binary
+ comparison after UNICODE NFKC normalization. So, in theory it's
+ possible that for some locales two different but similarly
+ looking characters were treated as equal by the collator, but
+ will count as different now. But it's very unlikely that anyone
+ wanted to depend on such fragile logic anyway. Note again that
+ we still do UNICODE normalization, so combining characters won't
+ break your comparison.)</para>
</listitem>
</itemizedlist>
</section>
diff --git a/src/test/resources/freemarker/test/templatesuite/expected/comparisons.txt b/src/test/resources/freemarker/test/templatesuite/expected/comparisons.txt
index 8d9d372..149fc95 100644
--- a/src/test/resources/freemarker/test/templatesuite/expected/comparisons.txt
+++ b/src/test/resources/freemarker/test/templatesuite/expected/comparisons.txt
@@ -88,6 +88,5 @@
<p>Item is: 12</p>
<p>Item is greater than two.</p>
<p>Item is greater than or equal to ten.</p>
-
</body>
</html>
diff --git a/src/test/resources/freemarker/test/templatesuite/templates/comparisons.ftl b/src/test/resources/freemarker/test/templatesuite/templates/comparisons.ftl
index 3889765..da9d45e 100644
--- a/src/test/resources/freemarker/test/templatesuite/templates/comparisons.ftl
+++ b/src/test/resources/freemarker/test/templatesuite/templates/comparisons.ftl
@@ -82,6 +82,7 @@
<p>Item is greater than or equal to ten.</p>
</#if>
</#foreach>
+<@noOutput>
<#-- Signum-based optimization test, all 9 permutations: -->
<#-- 1 -->
@@ -214,5 +215,26 @@
<@assert test= (p3 >= m3) />
<@assert test= !(p3 < m3) />
<@assert test= !(p3 <= m3) />
+
+<#-- String comparison: -->
+<#assign s = 'a'>
+<@assert test= '' == '' />
+<@assert test= 'a' == 'a' />
+<@assert test= s == 'a' />
+<@assert test= s + 'b' == 'ab' />
+<@assert test= 'á' == 'a\x0301' />
+<@assert test= 'a\x0301' == 'á'/>
+<@assert test= 'a' != 'A' />
+<@assert test= s != 'A' />
+<@assert test= 'A' != 'a' />
+<@assert test= '' != 'a' />
+<@assert test= 'a' != '' />
+<@assert test= 'ab' != 'ac' />
+<@assertFails message="Can't use operator \"<\" on string values.">${s < s}</@>
+<@assertFails message="Can't use operator \">\" on string values.">${s > s}</@>
+<@assertFails message="Can't use operator \"<=\" on string values.">${s <= s}</@>
+<@assertFails message="Can't use operator \">=\" on string values.">${(s >= s)}</@>
+
+</@noOutput>
</body>
</html>
