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

Package freemarker.core

# Class TruncateBuiltinAlgorithm

java.lang.Object
freemarker.core.TruncateBuiltinAlgorithm

Direct Known Subclasses:
  `DefaultTruncateBuiltinAlgorithm`

public abstract class TruncateBuiltinAlgorithm extends Object
Used for implementing the "truncate" family of built-ins. There are several variations of the "truncate" built-ins, each has a corresponding method here. See `truncateM(String, int, TemplateModel, Integer, Environment)` as the starting point.

New methods may be added in later versions, whoever they won't be abstract for backward compatibility.

Since:
  2.3.29
See Also:
  `Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TruncateBuiltinAlgorithm()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract TemplateScalarModel`
  `truncate​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate(...)` in templates.
  `abstract TemplateScalarModel`
  `truncateC​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_c_m(...)` in templates.
  `abstract TemplateModel`
  `truncateCM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_c_m(...)` in templates.
  `abstract TemplateModel`
  `truncateM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_m(...)` in templates.
  `abstract TemplateScalarModel`
  `truncateW​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env)`
  Corresponds to `?truncate_w(...)` in templates.
  `abstract 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`

- ## Constructor Details

  - ### TruncateBuiltinAlgorithm

    public TruncateBuiltinAlgorithm()

- ## Method Details

  - ### truncateM

    public abstract TemplateModel truncateM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate_m(...)` in templates. This method decides automatically if it will truncate at word boundary (see `truncateWM(java.lang.String, int, freemarker.template.TemplateModel, java.lang.Integer, freemarker.core.Environment)`) or at character boundary (see `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.

    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.

  - ### truncate

    public abstract TemplateScalarModel truncate​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate(...)` in templates. Similar to `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`).
    Throws:
      `TemplateException`

  - ### truncateW

    public abstract TemplateScalarModel truncateW​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate_w(...)` in templates. Same as `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`).
    Throws:
      `TemplateException`

  - ### truncateWM

    public abstract TemplateModel truncateWM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate_w_m(...)` in templates. Similar to `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).
    Throws:
      `TemplateException`

  - ### truncateC

    public abstract TemplateScalarModel truncateC​(String s, int maxLength, TemplateScalarModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate_c_m(...)` in templates. Same as `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).
    Throws:
      `TemplateException`

  - ### truncateCM

    public abstract TemplateModel truncateCM​(String s, int maxLength, TemplateModel terminator, Integer terminatorLength, Environment env) throws TemplateException
    Corresponds to `?truncate_c_m(...)` in templates. Similar to `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").
    Throws:
      `TemplateException`