Class Converters

java.lang.Object
io.bytestreams.codec.core.util.Converters
public final class Converters extends Object
Factory methods for creating Converter instances.

  • Method Details

    • of

      public static <V,U> Converter<V,U> of(Function<V,U> to, Function<U,V> from)
      Creates a converter from two functions.
      Type Parameters:
      V - the source type
      U - the target type
      Parameters:
      to - the forward conversion function
      from - the reverse conversion function
      Returns:
      a new converter

    • rightPad

      public static Converter<String,String> rightPad(char padChar, int length)
      Returns a converter that right-pads strings to a fixed length on from and strips trailing pad characters on to.
      Parameters:
      padChar - the character to pad with
      length - the target length
      Returns:
      a right-padding converter
      Throws:
      IllegalArgumentException - if length is not positive

    • leftPad

      public static Converter<String,String> leftPad(char padChar, int length)
      Returns a converter that left-pads strings to a fixed length on from and strips leading pad characters on to.
      Parameters:
      padChar - the character to pad with
      length - the target length
      Returns:
      a left-padding converter
      Throws:
      IllegalArgumentException - if length is not positive

    • rightFitPad

      public static Converter<String,String> rightFitPad(char padChar, int length)
      Returns a converter that right-pads or right-truncates strings to a fixed length on from and strips trailing pad characters on to.
      Parameters:
      padChar - the character to pad with
      length - the target length
      Returns:
      a right-fit-padding converter
      Throws:
      IllegalArgumentException - if length is not positive

    • leftFitPad

      public static Converter<String,String> leftFitPad(char padChar, int length)
      Returns a converter that left-pads or left-truncates strings to a fixed length on from and strips leading pad characters on to.
      Parameters:
      padChar - the character to pad with
      length - the target length
      Returns:
      a left-fit-padding converter
      Throws:
      IllegalArgumentException - if length is not positive

    • leftEvenPad

      public static Converter<String,String> leftEvenPad(char padChar)
      Returns a converter that left-pads strings to an even length on from and strips leading pad characters on to.
      Parameters:
      padChar - the character to pad with
      Returns:
      a left-even-padding converter

    • rightEvenPad

      public static Converter<String,String> rightEvenPad(char padChar)
      Returns a converter that right-pads strings to an even length on from and strips trailing pad characters on to.
      Parameters:
      padChar - the character to pad with
      Returns:
      a right-even-padding converter

    • toBigInt

      public static Converter<String, BigInteger> toBigInt(int digits)
      Returns a converter that parses strings to BigIntegers on to and formats them to zero-padded strings on from.

      For numeric fields wider than a long holds. COBOL allows PIC 9(31), and toLong(int) stops at eighteen digits. 

      Codec<BigInteger> reference = Codecs.ascii(25).xmap(Converters.toBigInt(25));

      Zero-padded numerics are unsigned. A negative value is rejected on from, since padding it would put the minus sign inside the zeros. Use a zoned or packed decimal codec for a field that carries a sign.

      Decoding is more permissive and accepts a leading sign, so a non-conforming field can be read but not written back unchanged.

      Parameters:
      digits - the number of digits for zero-padded formatting
      Returns:
      a string-to-BigInteger converter
      Throws:
      IllegalArgumentException - if digits is not positive

    • scaled

      public static Converter<Long, BigDecimal> scaled(int scale)
      Returns a converter between an integer of minor units and a BigDecimal with an implied decimal point.

      Many formats store a number as an integer whose decimal point position comes from the specification rather than the data: ISO 8583 field 4 is twelve digits of minor units, and COBOL writes PIC S9(7)V99 with the V marking a point that occupies no storage. 

      Codec<BigDecimal> amount = Codecs.packedLong(9).xmap(Converters.scaled(2));
Codec<BigDecimal> field4 = Codecs.asciiLong(12).xmap(Converters.scaled(2));

      Conversion is exact in both directions and never goes through double, which cannot represent most decimal fractions.

      from rejects a value carrying more precision than the scale allows rather than discarding it: 123.456 at scale 2 is an error, not 123.45. Round explicitly beforehand if that is what you want.

      Parameters:
      scale - the number of implied decimal places
      Returns:
      a converter between minor units and a decimal amount
      Throws:
      IllegalArgumentException - if scale is negative

    • toInt

      public static Converter<String,Integer> toInt(int digits)
      Returns a converter that parses strings to integers on to and formats integers to zero-padded strings on from.

      Zero-padded numerics are unsigned. A negative value is rejected on from, since padding it would put the minus sign inside the zeros. Use a zoned or packed decimal codec for a field that carries a sign.

      Decoding is more permissive and accepts a leading sign, so a non-conforming field can be read but not written back unchanged.

      Parameters:
      digits - the number of digits for zero-padded formatting
      Returns:
      a string-to-integer converter
      Throws:
      IllegalArgumentException - if digits is not positive

    • toLong

      public static Converter<String,Long> toLong(int digits)
      Returns a converter that parses strings to longs on to and formats longs to zero-padded strings on from.

      Zero-padded numerics are unsigned. A negative value is rejected on from, since padding it would put the minus sign inside the zeros. Use a zoned or packed decimal codec for a field that carries a sign.

      Decoding is more permissive and accepts a leading sign, so a non-conforming field can be read but not written back unchanged.

      Parameters:
      digits - the number of digits for zero-padded formatting
      Returns:
      a string-to-long converter
      Throws:
      IllegalArgumentException - if digits is not positive

    • temporal

      public static <T extends TemporalAccessor> Converter<String,T> temporal(String format, TemporalQuery<T> query)
      Returns a converter that parses strings to temporal values on to and formats temporal values to strings on from.

      The pattern is compiled with DateTimeFormatter.ofPattern(String), which uses the SMART resolver style. Under SMART resolution an out-of-range date such as 02/31 is adjusted to the last valid day of the month rather than rejected. Use temporal(DateTimeFormatter, TemporalQuery) to supply a formatter with different behaviour, such as STRICT resolution or a specific locale.

      Type Parameters:
      T - the temporal type
      Parameters:
      format - the date-time format pattern (see DateTimeFormatter)
      query - the temporal query for parsing (e.g. LocalDate::from)
      Returns:
      a string-to-temporal converter
      Throws:
      ConverterException - if the string cannot be parsed

    • temporal

      public static <T extends TemporalAccessor> Converter<String,T> temporal(DateTimeFormatter formatter, TemporalQuery<T> query)
      Returns a converter that parses strings to temporal values on to and formats temporal values to strings on from using the given formatter.

      Supplying a pre-built formatter gives full control over parsing behaviour, including resolver style and locale. For example, a formatter with STRICT resolution rejects an invalid date such as 02/31 instead of adjusting it.

      Type Parameters:
      T - the temporal type
      Parameters:
      formatter - the date-time formatter
      query - the temporal query for parsing (e.g. LocalDate::from)
      Returns:
      a string-to-temporal converter
      Throws:
      ConverterException - if the string cannot be parsed