DefaultTruncateBuiltinAlgorithm (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.core, class: DefaultTruncateBuiltinAlgorithm

Package freemarker.core

# Class DefaultTruncateBuiltinAlgorithm

java.lang.Object
freemarker.core.TruncateBuiltinAlgorithm
freemarker.core.DefaultTruncateBuiltinAlgorithm

public class DefaultTruncateBuiltinAlgorithm extends TruncateBuiltinAlgorithm
The default `TruncateBuiltinAlgorithm` implementation; see `Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)`. To know the properties of this `TruncateBuiltinAlgorithm` implementation, see the constructor. You can find more explanation and examples in the documentation of the `truncate` built-in in the FreeMarker Manual.

Since:
  2.3.29

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static DefaultTruncateBuiltinAlgorithm`
  `ASCII_INSTANCE`
  Instance that uses `"[...]"` as the `defaultTerminator` constructor argument, and thus is safe to use for all output charsets.
  `static double`
  `DEFAULT_WORD_BOUNDARY_MIN_LENGTH`
  The value used in the constructor of `ASCII_INSTANCE` and `UNICODE_INSTANCE` as the `wordBoundaryMinLength` argument.
  `static String`
  `STANDARD_ASCII_TERMINATOR`
  Used by `ASCII_INSTANCE` as the terminator.
  `static TemplateHTMLOutputModel`
  `STANDARD_M_TERMINATOR`
  Used by `ASCII_INSTANCE` and `UNICODE_INSTANCE` as the markup terminator; HTML `<span class='truncateTerminator'>[&#8230;]</span>`, where `&#8230;` is the ellipsis (…) character.
  `static String`
  `STANDARD_UNICODE_TERMINATOR`
  Used by `UNICODE_INSTANCE` as the terminator.
  `static DefaultTruncateBuiltinAlgorithm`
  `UNICODE_INSTANCE`
  Instance that uses `"[…]"` as the `defaultTerminator` constructor argument, which contains ellipsis character (`"…"`, U+2026), and thus only works with UTF-8, and the cp125x charsets (like cp1250), and with some other rarely used ones.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, boolean addSpaceAtWordBoundary)`
  Creates an instance with string (plain text) terminator.
  `DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, TemplateMarkupOutputModel<?> defaultMTerminator, boolean addSpaceAtWordBoundary)`
  Creates an instance with a string (plain text) terminator and a markup terminator.
  `DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, Integer defaultTerminatorLength, Boolean defaultTerminatorRemovesDots, TemplateMarkupOutputModel<?> defaultMTerminator, Integer defaultMTerminatorLength, Boolean defaultMTerminatorRemovesDots, boolean addSpaceAtWordBoundary, Double wordBoundaryMinLength)`
  Creates an instance with markup terminator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `getAddSpaceAtWordBoundary()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `TemplateMarkupOutputModel<?>`
  `getDefaultMTerminator()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `Integer`
  `getDefaultMTerminatorLength()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `boolean`
  `getDefaultMTerminatorRemovesDots()`
  `String`
  `getDefaultTerminator()`
  `int`
  `getDefaultTerminatorLength()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `boolean`
  `getDefaultTerminatorRemovesDots()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `protected int`
  `getMTerminatorLength​(TemplateMarkupOutputModel<?> mTerminator)`
  Returns the (estimated) length of the argument terminator.
  `protected boolean`
  `getMTerminatorRemovesDots​(TemplateMarkupOutputModel terminator)`
  Same as `getTerminatorRemovesDots(String)`, but invoked for a markup terminator.
  `protected boolean`
  `getTerminatorRemovesDots​(String terminator)`
  Tells if the dots touched by the terminator text should be removed.
  `double`
  `getWordBoundaryMinLength()`
  See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.
  `TemplateScalarModel`
  `truncate​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate(...)` in templates.
  `TemplateScalarModel`
  `truncateC​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_c_m(...)` in templates.
  `TemplateModel`
  `truncateCM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_c_m(...)` in templates.
  `TemplateModel`
  `truncateM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_m(...)` in templates.
  `TemplateScalarModel`
  `truncateW​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_w(...)` in templates.
  `TemplateModel`
  `truncateWM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_w_m(...)` in templates.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### STANDARD_ASCII_TERMINATOR

    public static final String STANDARD_ASCII_TERMINATOR
    Used by `ASCII_INSTANCE` as the terminator.
    See Also:
      Constant Field Values

  - ### STANDARD_UNICODE_TERMINATOR

    public static final String STANDARD_UNICODE_TERMINATOR
    Used by `UNICODE_INSTANCE` as the terminator.
    See Also:
      Constant Field Values

  - ### STANDARD_M_TERMINATOR

    public static final TemplateHTMLOutputModel STANDARD_M_TERMINATOR
    Used by `ASCII_INSTANCE` and `UNICODE_INSTANCE` as the markup terminator; HTML `<span class='truncateTerminator'>[&#8230;]</span>`, where `&#8230;` is the ellipsis (…) character. Note that while the ellipsis character is not in US-ASCII, this still works safely regardless of output charset, as `&#8230;` itself only contains US-ASCII characters.

  - ### DEFAULT_WORD_BOUNDARY_MIN_LENGTH

    public static final double DEFAULT_WORD_BOUNDARY_MIN_LENGTH
    The value used in the constructor of `ASCII_INSTANCE` and `UNICODE_INSTANCE` as the `wordBoundaryMinLength` argument.
    See Also:
      Constant Field Values

  - ### ASCII_INSTANCE

    public static final DefaultTruncateBuiltinAlgorithm ASCII_INSTANCE
    Instance that uses `"[...]"` as the `defaultTerminator` constructor argument, and thus is safe to use for all output charsets. Because of that, this is the default of `Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)`. The `defaultMTerminator` (markup terminator) is `STANDARD_M_TERMINATOR`, and the `wordBoundaryMinLength` is `DEFAULT_WORD_BOUNDARY_MIN_LENGTH`, and `addSpaceAtWordBoundary` is `true`.

  - ### UNICODE_INSTANCE

    public static final DefaultTruncateBuiltinAlgorithm UNICODE_INSTANCE
    Instance that uses `"[…]"` as the `defaultTerminator` constructor argument, which contains ellipsis character (`"…"`, U+2026), and thus only works with UTF-8, and the cp125x charsets (like cp1250), and with some other rarely used ones. It does not work (becomes to a question mark) with ISO-8859-x charsets (like ISO-8859-1), which are probably the most often used charsets after UTF-8.

    The `defaultMTerminator` (markup terminator) is `STANDARD_M_TERMINATOR`, and the `wordBoundaryMinLength` is `DEFAULT_WORD_BOUNDARY_MIN_LENGTH`, and `addSpaceAtWordBoundary` is `true`.

- ## Constructor Details

  - ### DefaultTruncateBuiltinAlgorithm

    public DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, TemplateMarkupOutputModel<?> defaultMTerminator, boolean addSpaceAtWordBoundary)
    Creates an instance with a string (plain text) terminator and a markup terminator. See parameters in `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)`; the missing parameters will be `null`.

  - ### DefaultTruncateBuiltinAlgorithm

    public DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, boolean addSpaceAtWordBoundary)
    Creates an instance with string (plain text) terminator. See parameters in `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)`; the missing parameters will be `null`.

  - ### DefaultTruncateBuiltinAlgorithm

    public DefaultTruncateBuiltinAlgorithm​(String defaultTerminator, Integer defaultTerminatorLength, Boolean defaultTerminatorRemovesDots, TemplateMarkupOutputModel<?> defaultMTerminator, Integer defaultMTerminatorLength, Boolean defaultMTerminatorRemovesDots, boolean addSpaceAtWordBoundary, Double wordBoundaryMinLength)
    Creates an instance with markup terminator.
    Parameters:
      `defaultTerminator` - The terminator to use if the invocation (like `s?truncate(20)`) doesn't specify it. The terminator is the text appended after a truncated string, to indicate that it was truncated. Typically, it's `"[...]"` or `"..."`, or the same with UNICODE ellipsis character.
      `defaultTerminatorLength` - The assumed length of `defaultTerminator`, or `null` if the assumed length is simply `defaultTerminator.length()`.
      `defaultTerminatorRemovesDots` - Whether dots and ellipsis characters that the `defaultTerminator` touches should be removed. If `null`, this will be auto-detected based on if `defaultTerminator` starts with dot or ellipsis. The goal is to avoid outcomes where we have more dots next to each other than there are in the terminator.
      `defaultMTerminator` - Similar to `defaultTerminator`, but is markup instead of plain text. This can be `null`, in which case `defaultTerminator` will be used even if `?truncate_m` or similar built-in is called.
      `defaultMTerminatorLength` - The assumed length of the terminator, or `null` if the assumed length will be `getMTerminatorLength(TemplateMarkupOutputModel)`. Note that if you have HTML tags, or entity references in the `defaultMTerminator`, then the visual length differs from the string length, and `getMTerminatorLength(TemplateMarkupOutputModel)` accounts for these complications to an extent, but it for example it won't know what CSS does, or if the nested content of some HTML elements are not displayed.
      `defaultMTerminatorRemovesDots` - Similar to `defaultTerminatorRemovesDots`, but for `defaultMTerminator`. If `null`, and `defaultMTerminator` is HTML/XML/XHTML, then it will be examined of the first character of the terminator that's outside a HTML/XML tag or comment is dot or ellipsis (after resolving numerical character references). For other kind of markup it defaults to `true`, to be on the safe side.
      `addSpaceAtWordBoundary` - , Whether to add a space before the terminator if the truncation happens directly after the end of a word. For example, when "too long sentence" is truncated, it will be a like "too long [...]" instead of "too long[...]". When the truncation happens inside a word, this has no effect, i.e., it will be always like "too long se[...]" (no space before the terminator). Note that only whitespace is considered to be a word separator, not punctuation, so if this is `true`, you get results like "Some sentence. [...]".
      `wordBoundaryMinLength` - Used when `truncate(java.lang.String, int, freemarker.template.TemplateScalarModel, java.lang.Integer, freemarker.core.Environment)` or `truncateM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)` has to decide between word boundary truncation, and character boundary truncation; it's the minimum length, given as proportion of `maxLength`, that word boundary truncation has to produce. If the resulting length is less, we do character boundary truncation instead. For example, if `maxLength` is 30, and this parameter is 0.85, then: 30 * 0.85 = 25.5, rounded up that's 26, so the resulting length must be at least 26. The result of character boundary truncation will always be accepted, even if it's still too short. If this parameter is `null`, then `DEFAULT_WORD_BOUNDARY_MIN_LENGTH` will be used. If this parameter is 0, then truncation always happens at word boundary. If this parameter is 1.0, then truncation doesn't prefer word boundaries over other places.

- ## Method Details

  - ### truncate

    public TemplateScalarModel truncate​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate(...)` in templates. Similar to `TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)`, but only allows an FTL string as terminator, and thence the return value is always an FTL string as well (not `TemplateMarkupOutputModel`).
    Specified by:
      `truncate` in class `TruncateBuiltinAlgorithm`
    Throws:
      `TemplateException`

  - ### truncateW

    public TemplateScalarModel truncateW​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate_w(...)` in templates. Same as `TruncateBuiltinAlgorithm.truncateWM(String, int, TemplateModel, Integer, Environment)`, but only allows an FTL string as terminator, and thence the return value is always an FTL string as well (not `TemplateMarkupOutputModel`).
    Specified by:
      `truncateW` in class `TruncateBuiltinAlgorithm`
    Throws:
      `TemplateException`

  - ### truncateC

    public TemplateScalarModel truncateC​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate_c_m(...)` in templates. Same as `TruncateBuiltinAlgorithm.truncateCM(String, int, TemplateModel, Integer, Environment)`, but only allows an FTL string as terminator, and thence the return value is always an FTL string as well (not markup).
    Specified by:
      `truncateC` in class `TruncateBuiltinAlgorithm`
    Throws:
      `TemplateException`

  - ### truncateM

    public TemplateModel truncateM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate_m(...)` in templates. This method decides automatically if it will truncate at word boundary (see `TruncateBuiltinAlgorithm.truncateWM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)`) or at character boundary (see `TruncateBuiltinAlgorithm.truncateCM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)`). While it depends on the implementation, the idea is that it should truncate at word boundary, unless that gives a too short string, in which case it falls back to truncation at character duration.

    The terminator and the return value can be `TemplateMarkupOutputModel` (FTL markup output type), not just `String` (FTL string type), hence the "m" in the name.

    Specified by:
      `truncateM` in class `TruncateBuiltinAlgorithm`
    Parameters:
      `s` - The input string whose length need to be limited. The caller (the FreeMarker core normally) is expected to guarantee that this won't be `null`.
      `maxLength` - The maximum length of the returned string, although the algorithm need not guarantee this strictly. For example, if this is less than the length of the `terminator` string, then most algorithms should still return the `terminator` string. Or, some sophisticated algorithm may counts in letters differently depending on their visual width. The goal is usually to prevent unusually long string values to ruin visual layout, while showing clearly to the user that the end of the string was cut off. If the input string is not longer than the maximum length, then it should be returned as is. The caller (the FreeMarker core normally) is expected to guarantee that this will be at least 0.
      `terminator` - The string or markup to show at the end of the returned string if the string was actually truncated. This can be `null`, in which case the default terminator of the algorithm will be used. It can be an FTL string (a `TemplateScalarModel`) of any length (including 0), or a `TemplateMarkupOutputModel` (typically HTML markup). If it's `TemplateMarkupOutputModel`, then the result is `TemplateMarkupOutputModel` of the same output format as well, otherwise it can remain `TemplateScalarModel`. Note that the length of the terminator counts into the result length that shouldn't be exceed (`maxLength`) (or at least the algorithm should make an effort to avoid that).
      `terminatorLength` - The assumed length of the terminator. If this is `null` (and typically it is), then the method decides the length of the terminator. If this is not `null`, then the method must pretend that the terminator length is this. This can be used to specify the visual length of a terminator explicitly, which can't always be decided well programmatically.
      `env` - The runtime environment from which this algorithm was called. The caller (the FreeMarker core normally) is expected to guarantee that this won't be `null`.
    Returns:
      The truncated text, which is either a `TemplateScalarModel` (FTL string), or a `TemplateMarkupOutputModel`.
    Throws:
      `TemplateException` - If anything goes wrong during truncating. It's unlikely that an implementation will need this though.

  - ### truncateWM

    public TemplateModel truncateWM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate_w_m(...)` in templates. Similar to `TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)`, but the truncation should happen at word boundary (hence the "w"). That is, the truncation isn't allowed to truncate a word. What counts as a word, is up to the implementation, but at least in `DefaultTruncateBuiltinAlgorithm` words are the sections that are separated by whitespace (so punctuation doesn't separate words).
    Specified by:
      `truncateWM` in class `TruncateBuiltinAlgorithm`
    Throws:
      `TemplateException`

  - ### truncateCM

    public TemplateModel truncateCM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Description copied from class: `TruncateBuiltinAlgorithm`
    Corresponds to `?truncate_c_m(...)` in templates. Similar to `TruncateBuiltinAlgorithm.truncateM(String, int, TemplateModel, Integer, Environment)`, but the truncation should not prefer truncating at word boundaries over the closer approximation of the desired `maxLength`. Hence, we say that it truncates at character boundary (hence the "c").
    Specified by:
      `truncateCM` in class `TruncateBuiltinAlgorithm`
    Throws:
      `TemplateException`

  - ### getDefaultTerminator

    public String getDefaultTerminator()

  - ### getDefaultTerminatorLength

    public int getDefaultTerminatorLength()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getDefaultTerminatorRemovesDots

    public boolean getDefaultTerminatorRemovesDots()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getDefaultMTerminator

    public TemplateMarkupOutputModel<?> getDefaultMTerminator()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getDefaultMTerminatorLength

    public Integer getDefaultMTerminatorLength()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getDefaultMTerminatorRemovesDots

    public boolean getDefaultMTerminatorRemovesDots()

  - ### getWordBoundaryMinLength

    public double getWordBoundaryMinLength()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getAddSpaceAtWordBoundary

    public boolean getAddSpaceAtWordBoundary()
    See similarly named parameter of `DefaultTruncateBuiltinAlgorithm(String, Integer, Boolean, TemplateMarkupOutputModel, Integer, Boolean, boolean, Double)` the construction}.

  - ### getMTerminatorLength

    protected int getMTerminatorLength​(TemplateMarkupOutputModel<?> mTerminator) throws TemplateModelException
    Returns the (estimated) length of the argument terminator. It should only count characters that are visible for the user (like in the web browser).

    In the implementation in `DefaultTruncateBuiltinAlgorithm`, if the markup is HTML/XML/XHTML, then this counts the characters outside tags and comments, and inside CDATA sections (ignoring the CDATA section delimiters). Furthermore, then it counts character and entity references as having length of 1. If the markup is not HTML/XML/XHTML (or subclasses of those `MarkupOutputFormat`-s) then it doesn't know how to measure it, and simply returns 3.

    Throws:
      `TemplateModelException`

  - ### getTerminatorRemovesDots

    protected boolean getTerminatorRemovesDots​(String terminator) throws TemplateModelException
    Tells if the dots touched by the terminator text should be removed.

    The implementation in `DefaultTruncateBuiltinAlgorithm` return `true` if the terminator starts with dot (or ellipsis).

    Parameters:
      `terminator` - A `TemplateScalarModel` or `TemplateMarkupOutputModel`. Not `null`.
    Throws:
      `TemplateModelException`

  - ### getMTerminatorRemovesDots

    protected boolean getMTerminatorRemovesDots​(TemplateMarkupOutputModel terminator) throws TemplateModelException
    Same as `getTerminatorRemovesDots(String)`, but invoked for a markup terminator.

    The implementation in `DefaultTruncateBuiltinAlgorithm` will skip HTML/XML tags and comments, and resolves relevant character references to find out if the first character is dot or ellipsis. But it only does this for HTML/XMl/XHTML (or subclasses of those `MarkupOutputFormat`-s), otherwise it always returns `true` to be on the safe side.

    Throws:
      `TemplateModelException`