Interface JoinConfiguration

public sealed interface JoinConfiguration
A configuration for how a series of components can be joined.

A join configuration consists of the following parts:

  • a prefix (optional)

    a component to be prepended to the resulting component

  • a separator (optional)

    a component to be placed between each component

  • a last separator (optional)

    a component to be placed between the last two components

  • a suffix (optional)

    a component to be appended to the resulting component

  • a convertor (required, defaults to ComponentLike.asComponent())

    a function to change each ComponentLike that is being joined into a Component

  • a predicate (required, defaults to true)

    a predicate that specifies if a given component should be included in the join process

  • a root style (required, defaults to Style.empty())

    the style of the parent component that contains the joined components.

Note that the last separator only acts as an override for the normal separator. This means that if you do not specify a last separator, the normal separator will be placed between the last two components. To omit the final separator, but still include normal separators, use Component.empty() as the last separator.

If specified, the join method can use a different last separator in the case where the amount of components being joined together is more than two. This can be used to insert a serial (or Oxford) comma if needed.

Null elements are not allowed in the input of the join methods or as output from the convertor. If you would like to exclude elements from being joined, use the predicate.

Since:
4.9.0
See Also:

  • Method Details

    • builder

      static JoinConfiguration.Builder builder()
      Creates a new builder.
      Returns:
      a new builder
      Since:
      4.9.0

    • noSeparators

      static JoinConfiguration noSeparators()
      Gets a join configuration with no separators, prefix or suffix.
      Returns:
      the join configuration
      Since:
      4.9.0

    • newlines

      static JoinConfiguration newlines()
      Provides a join configuration with no prefix or suffix that simply joins the components together using the Component.newline() component.

      A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating the following output: 'hello\nthere'.

      Returns:
      the join configuration
      Since:
      4.10.0

    • spaces

      static JoinConfiguration spaces()
      Provides a join configuration with no prefix or suffix that simply joins the components together using the Component.space() component.

      A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating the following output: 'hello there'.

      Returns:
      the join configuration
      Since:
      4.15.0

    • commas

      static JoinConfiguration commas(boolean spaces)
      Provides a join configuration with no prefix or suffix that simply joins the components together using a single comma, matching a CSV like layout.

      A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating either the output 'hello,there' or 'hello, there' depending on whether the passed boolean flag was false or true respectively.

      Parameters:
      spaces - a plain boolean flag indicating whether the returned comma-based join configuration should append a single space after each comma or not
      Returns:
      the join configuration
      Since:
      4.10.0

    • arrayLike

      static JoinConfiguration arrayLike()
      Provides a join configuration that joins components together in the same manner Arrays.toString(Object[]) stringifies an array. Specifically, the join configuration prefixes and suffixes the components with an open or closed square bracket respectively. Components themselves are joined together using a comma and a space.

      A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating the following output: '[hello, there]'.

      Returns:
      the join configuration
      Since:
      4.10.0

    • separator

      static JoinConfiguration separator(@Nullable ComponentLike separator)
      Creates a join configuration with a separator and no prefix or suffix.
      Parameters:
      separator - the separator
      Returns:
      the join configuration
      Since:
      4.9.0

    • separators

      static JoinConfiguration separators(@Nullable ComponentLike separator, @Nullable ComponentLike lastSeparator)
      Creates a join configuration with a separator and last separator but no prefix or suffix.
      Parameters:
      separator - the separator
      lastSeparator - the last separator
      Returns:
      the join configuration
      Since:
      4.9.0

    • prefix

      @Nullable Component prefix()
      Gets the prefix of this join configuration.
      Returns:
      the prefix
      Since:
      4.9.0

    • suffix

      @Nullable Component suffix()
      Gets the suffix of this join configuration.
      Returns:
      the suffix
      Since:
      4.9.0

    • separator

      @Nullable Component separator()
      Gets the separator of this join configuration.
      Returns:
      the separator
      Since:
      4.9.0

    • lastSeparator

      @Nullable Component lastSeparator()
      Gets the last separator of this join configuration.
      Returns:
      the last separator
      Since:
      4.9.0

    • lastSeparatorIfSerial

      @Nullable Component lastSeparatorIfSerial()
      Gets the last separator that will be used instead of the normal last separator in the case where there are more than two components being joined. This can be used to mimic a serial (or Oxford) comma.
      Returns:
      the separator
      Since:
      4.9.0

    • convertor

      Function<ComponentLike, Component> convertor()
      Gets the convertor of this join configuration.

      This is used to change the components that are going to be joined. It does not touch the prefix, suffix or any of the separators.

      Returns:
      the operator
      Since:
      4.9.0

    • predicate

      Predicate<ComponentLike> predicate()
      Gets the predicate of this join configuration.

      This is used to determine if a component is to be included in the join process. It does not touch the prefix, suffix or any of the separators.

      Returns:
      the predicate
      Since:
      4.9.0

    • parentStyle

      Style parentStyle()
      Gets the style of the parent component that contains the joined components.
      Returns:
      the style
      Since:
      4.11.0