javadoc changes

Author: fluentfuture

mug-guava/src/main/java/com/google/mu/safesql/SafeSql.java

@@ -265,6 +265,23 @@
  *   List<Long> ids = sql.query(connection, row -> row.getLong("id"));
  * }</pre>
  *
+ * <p><strong>Automatic Escaping: No Need for ESCAPE Clause</strong></p>
+ *
+ * <p>This means you <em>do not</em> need to (and in fact, must not) write SQL
+ * using {@code ESCAPE} clauses. Any such attempt, like:
+ *
+ * <pre>{@code
+ *   SELECT name FROM Users WHERE name LIKE '%{term}%' ESCAPE '\'
+ * }</pre>
+ *
+ * <p>...will be rejected, because SafeSql already performs all necessary escaping internally.
+ * This eliminates the need for developers to deal with brittle double-escaping
+ * (like {@code '\\'}), improves readability, and avoids cross-database compatibility issues.
+ *
+ * <p>If you find yourself wanting to use {@code ESCAPE}, consider whether you are
+ * manually escaping strings that could instead be safely passed as-is to SafeSql's
+ * template system.
+ *
  * <dl><dt><STRONG>Quote String Placeholders</STRONG></dt></dl>
  *
  * Even when you don't use the {@code LIKE} operator or the percent sign (%), it may still be
@@ -924,7 +941,8 @@ public static <T> Template<List<T>> prepareToQuery(
    * <p>The template arguments follow the same rules as discussed in {@link #of(String, Object...)}
    * and receives the same compile-time protection against mismatch or out-of-order human mistakes.
    *
-   * <p>The returned Template is <em>not</em> thread safe.
+   * <p>The returned Template is <em>not</em> thread safe because the cached {@link
+   * PreparedStatement} objects aren't.
    *
    * <p>The caller is expected to close the {@code connection} after done, which will close the
    * cached PreparedStatement.

mug/src/main/java/com/google/mu/util/Substring.java

@@ -115,6 +115,256 @@
  * assertThat(rendered).isEqualTo("Arya Stark went to Braavos.");
  * }</pre>
  *
+ * <h2>From Apache StringUtils to Substring</h2>
+ * <table border="1" cellpadding="6" cellspacing="0">
+ * <thead><tr><th>StringUtils Style</th><th>Substring Style</th></tr></thead>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Success
+ * String username = substringBefore("user@gmail.com", "@");
+ *     // => "user"
+ *
+ * // '.' not found in "readme", returns empty
+ * String filename = substringBefore("readme", ".");
+ *     // => ""
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Success
+ * String username = before(first("@"))
+ *     .from("user@gmail.com");
+ *     // => "user"
+ *
+ * // explicitly specify "readme" as fallback
+ * String filename = before(first("."))
+ *     .from("readme")
+ *     .orElse("readme");
+ *     // => "readme"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Success
+ * String emailDomain = substringAfter("user@gmail.com", "@");
+ *     // => "gmail.com"
+ *
+ * // '.' not found in "myfile": full name is assumed to be extension
+ * String extension = substringAfter("myfile", ".");
+ *     // => "myfile"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Success
+ * String emailDomain = after(first("@"))
+ *     .from("user@gmail.com");
+ *     // => "gmail.com"
+ *
+ * // explicitly specify "n/a" as fallback
+ * String extension = after(first("."))
+ *     .from("myfile")
+ *     .orElse("n/a");
+ *     // => "n/a"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Success
+ * String extension = substringAfterLast("myfile.txt", ".");
+ *     // => "txt"
+ *
+ * // '.' not found in "myfile": full name is assumed to be extension
+ * String extension = substringAfterLast("myfile", ".");
+ *     // => "myfile"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Success
+ * String extension = after(last("."))
+ *     .from("myfile.txt");
+ *     // => "txt"
+ *
+ * // explicitly specify "n/a" as fallback
+ * String extension = after(last("."))
+ *     .from("myfile")
+ *     .orElse("n/a");
+ *     // => "n/a"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Success
+ * String value = substringBetween("<a>hello</a>", "<a>", "</a>");
+ *     // => "hello"
+ *
+ * // Tags not matched in "value": returns null
+ * String fallback = substringBetween("value", "<a>", "</a>");
+ *     // => null
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Success
+ * String value = between("<a>", "</a>")
+ *     .from("<a>hello</a>");
+ *     // => "hello"
+ *
+ * // explicitly specify "n/a" as fallback
+ * String fallback = between("<a>", "</a>")
+ *     .from("value")
+ *     .orElse("n/a");
+ *     // => "n/a"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Success
+ * String[] values = substringsBetween("<a>1</a><a>2</a>", "<a>", "</a>");
+ *     // => ["1", "2"]
+ *
+ * // Tag mismatch: returns null
+ * String[] values = substringsBetween("value", "<a>", "</a>");
+ *     // => null
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Returns [] if not found
+ * List<String> values = between("<a>", "</a>")
+ *     .repeatedly()
+ *     .from("<a>1</a><a>2</a>")
+ *     .toList();
+ *     // => ["1", "2"]
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * String result = replacePattern("v1.2.3", "\\d+", "x");
+ *     // => "vx.x.x"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Always use repeatedly() to apply to all occurrences
+ * String result = first(Pattern.compile("\\d+"))
+ *     .repeatedly()
+ *     .replaceAllFrom("v1.2.3", m -> "x");
+ *     // => "vx.x.x"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * String result = replaceEachRepeatedly("a-b-a", new String[]{"a", "b"}, new String[]{"x", "y"});
+ *     // => "x-y-x"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Always use repeatedly() to apply to all occurrences
+ * Map<String, String> replacements = Map.of("a", "x", "b", "y");
+ * String result = replacements.keySet().stream()
+ *     .map(Substring::first)
+ *     .collect(firstOccurrence())
+ *     .replaceAllFrom("a-b-a", m -> replacements.get(m.toString()));
+ *     // => "x-y-x"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * String name = removeStart("Mr.Bond", "Mr.");
+ *     // => "Bond"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * String name = prefix("Mr.").removeFrom("Mr.Bond");
+ *     // => "Bond"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * String name = removeEnd("file.txt", ".txt");
+ *     // => "file"
+ * }</pre></td>
+ *   <td><pre>{@code
+ * String name = suffix(".txt").removeFrom("file.txt");
+ *     // => "file"
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Filters out empty
+ * String[] parts = split("a,b,c,", ",");
+ *     // => ["a", "b", "c"]
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Explicitly filter out empty matches
+ * List<String> parts = all(",")
+ *     .split("a,b,c,")
+ *     .filter(Match::isNotEmpty)
+ *     .map(Match::toString)
+ *     .toList();
+ *     // => ["a", "b", "c"]
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // Retains empty
+ * String[] parts = splitPreserveAllTokens("a,,b", ",");
+ *     // => ["a", "", "b"]
+ * }</pre></td>
+ *   <td><pre>{@code
+ * List<String> parts = all(",")
+ *     .split("a,,b")
+ *     .map(Match::toString)
+ *     .toList();
+ *     // => ["a", "", "b"]
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // By -, --, --- etc. Ignores empty.
+ * String[] parts = splitByWholeSeparator("a--b-c-", "-");
+ *     // => ["a", "b", "c"]
+ * }</pre></td>
+ *   <td><pre>{@code
+ * // Explicitly filter out empty matches
+ * List<String> parts = consecutive(is('-'))
+ *     .repeatedly()
+ *     .split("a--b-c-")
+ *     .filter(Match::isNotEmpty)
+ *     .map(Match::toString)
+ *     .toList();
+ *     // => ["a", "b", "c"]
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * // By -, --, --- etc. Retains empty.
+ * String[] parts = splitByWholeSeparatorPreserveAllTokens("a--", "-");
+ *     // => ["a", ""]
+ * }</pre></td>
+ *   <td><pre>{@code
+ * List<String> parts = consecutive(is('-'))
+ *     .repeatedly()
+ *     .split("a--")
+ *     .map(Match::toString)
+ *     .toList();
+ *     // => ["a", ""]
+ * }</pre></td>
+ * </tr>
+ *
+ * <tr>
+ *   <td><pre>{@code
+ * int count = countMatches("a,b,c", ",");
+ *     // => 2
+ * }</pre></td>
+ *   <td><pre>{@code
+ * long count = all(",").match("a,b,c").count();
+ *     // => 2
+ * }</pre></td>
+ * </tr>
+ * </table>
+ *
  * @since 2.0
  */
 public final class Substring {