Package eu.bandm.tools.util.java

Interface Strings.TextFlow

All Superinterfaces:
BiFunction<Strings.TextConsumer,Strings.TextConsumer,Strings.TextConsumer>, BinaryOperator<Strings.TextConsumer>
Enclosing class:
Strings
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public static interface Strings.TextFlow extends BinaryOperator<Strings.TextConsumer>
Functional interface for composable partial transformations of text.

Two text consumers are passed as arguments to the apply(eu.bandm.tools.util.java.Strings.TextConsumer, eu.bandm.tools.util.java.Strings.TextConsumer) method. The result should be a text consumer that forwards transformed/untransformed text to the first/second one, respectively.

  • Field Details

    • JAVA_STRING

      static final Strings.TextFlow JAVA_STRING
      A text flow that encodes text according to the rules of Java string literals.

    • XML

      static final Strings.TextFlow XML
      A text flow that encodes text according to the rules of XML text.

    • PASCAL_STRING

      static final Strings.TextFlow PASCAL_STRING
      A text flow that encodes text according to the rules of Pascal string literals.

  • Method Details

    • apply

      Strings.TextConsumer apply(Strings.TextConsumer downstream, Strings.TextConsumer alternative)
      Specified by:
      apply in interface BiFunction<Strings.TextConsumer,Strings.TextConsumer,Strings.TextConsumer>

    • applyAlways

      default Strings.TextConsumer applyAlways(Strings.TextConsumer downstream)
      Passes the same downstream consumer for transformed and untransformed text.

      This method is a convenient shorthand for apply(downstream, downstream).

      Parameters:
      downstream - the textconsumer to forward both transformed and untransformed text to
      Returns:
      a text consumer that forwards both transformed and untransformed text to downstream
      Throws:
      NullPointerException - if downstream is null

    • identity

      static Strings.TextFlow identity()
      Returns a text flow that forwards all text as if transformed.
      Returns:
      a text flow that forwards all text to downstream, without any transformation

    • empty

      static Strings.TextFlow empty()
      Returns a text flow that forwards all text untransformed.
      Returns:
      a text flow that forwards all text to alternative

    • map

      static Strings.TextFlow map(IntUnaryOperator op)
      Returns a text flow that transforms each code point according to a given function.
      Parameters:
      op - the function to transform code points with
      Returns:
      a text flow that transforms each code point by applying op
      Throws:
      NullPointerException - if op is null

    • select

      static Strings.TextFlow select(IntPredicate which)
      Returns a text flow that transforms selected code points to themselves.

      This flow does not perform any actual transformation, but demultiplexes code points to the transformed/untransformed channel, according to a given predicate. Thus is useful when followed by andThen to restrict a downstream flow to the selected code points, or followed by orElse to restrict an alternative flow to the unselected code points, respectively.

      Parameters:
      which - a predicate that selects code points
      Returns:
      a text flow that forwards each code point as transformed if which returns true, and as untransformed otherwise
      Throws:
      NullPointerException - if which is null

    • andAlways

      default Strings.TextFlow andAlways(Strings.TextFlow other)
      Returns a variant of this text flow that forwards both transformed and untransformed text to the given text flow.
      Parameters:
      other - the text flow to forward to
      Returns:
      a variant of this text flow that forwards both transformed and untransformed text to other
      Throws:
      NullPointerException - if other is null

    • andThen

      default Strings.TextFlow andThen(Strings.TextFlow other)
      Returns a text flow that forwards transformed text to the given text flow. Untransformed text bypasses the given text flow.
      Parameters:
      other - the text flow to forward transformed text to
      Returns:
      a variant of this text flow that forwards transformed text to other
      Throws:
      NullPointerException - if other is null

    • orElse

      default Strings.TextFlow orElse(Strings.TextFlow other)
      Returns a text flow that forwards untransformed text to the given text flow. Transformed text bypasses the given text flow.
      Parameters:
      other - the text flow to forward untransformed text to
      Returns:
      a variant of this text flow that forwards untransformed text to other
      Throws:
      NullPointerException - if other is null

    • drop

      static Strings.TextFlow drop()
      Returns a text flow that drops all text.

      This is useful in conjunction with andThen(eu.bandm.tools.util.java.Strings.TextFlow) and orElse. For example, a positive filter operation can be expressed as select(p).orElse(drop()), and a negative filter operation can be expressed as select(p).andThen(drop()).

      Returns:
      a text flow that drops all text

    • escapeNumeric

      static Strings.TextFlow escapeNumeric(String prefix, String suffix, int radix, int minWidth, int maxWidth)
      Returns a text flow that encodes code points numerically.

      The resulting consumer will throw IllegalArgumentException later, if a code point is encountered whose numerical escape sequence has more digits than specified by maxWidth. By contrast, if the sequence has fewer digits than specified by minWidth, leading zeroes are silently added.

      This transformation applies to all code points. Use select(java.util.function.IntPredicate) and andThen(eu.bandm.tools.util.java.Strings.TextFlow) or orElse(eu.bandm.tools.util.java.Strings.TextFlow) to restrict the transformation to a subset.

      Parameters:
      prefix - the common prefix of numerical escape sequences
      suffix - the common suffix of numerical escape sequences
      radix - the radix to use in numerical escape sequences
      minWidth - the minimum number of digits in numerical escape sequences
      maxWidth - the maximum number of digits in numerical escape sequences
      Returns:
      a text flow that encodes code points by a number in the format specified by radix, minWidth and maxWidth, enclosed in prefix and suffix
      Throws:
      NullPointerException - if any of prefix, suffix is null
      IllegalArgumentException - if radix is out of the meaningful bounds, or if minWidth is less than one or greater than maxWidth
      See Also:

    • geminate

      static Strings.TextFlow geminate()
      Returns a text flow that encodes code points by doubling.

      This transformation applies to all code points. Use select(java.util.function.IntPredicate) and andThen(eu.bandm.tools.util.java.Strings.TextFlow) or orElse(eu.bandm.tools.util.java.Strings.TextFlow) to restrict the transformation to a subset.

      Returns:
      a test flow that encodes each code point by forwarding it twice

    • escapeSymbolic

      static Strings.TextFlow escapeSymbolic(String prefix, String suffix, Map<Integer,String> which)
      Returns a text flow that encodes code points symbolically.

      This transformation applies to the code points specified by the given map. All others are forwarded untransformed.

      Parameters:
      prefix - the common prefix of symbolic escape sequences
      suffix - the common suffix of symbolic escape sequences
      which - a map of code points to their symbolic names
      Returns:
      a text flow that encodes code points in the key set of map as the associated value, enclosed in prefix and suffix; all other code points are forwarded untransformed.
      Throws:
      NullPointerException - if prefix, suffix or which is null

    • utf16

      static Strings.TextFlow utf16()
      Returns a text flow that encodes code points in UTF-16.

      Code points in the basic multilingual plane (BMP) are forwarded untransformed; all others are encoded as a surrogate pair.

      Returns:
      a text flow that encodes code points in UTF-16