Package io.nayuki.qrcodegen

Class QrSegment

  • public final class QrSegment
extends java.lang.Object
    A segment of character/binary/control data in a QR Code symbol. Instances of this class are immutable.

    The mid-level way to create a segment is to take the payload data and call a static factory function such as makeNumeric(CharSequence). The low-level way to create a segment is to custom-make the bit buffer and call the constructor with appropriate values.

    This segment class imposes no length restrictions, but QR Codes have restrictions. Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. Any segment longer than this is meaningless for the purpose of generating QR Codes. This class can represent kanji mode segments, but provides no help in encoding them - see QrSegmentAdvanced for full kanji support.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  QrSegment.Mode
      Describes how a segment's data bits are interpreted.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      QrSegment.Mode mode
      The mode indicator of this segment.
      int numChars
      The length of this segment's unencoded data.

    • Constructor Summary

      Constructors 
      Constructor Description
      QrSegment​(QrSegment.Mode md, int numCh, BitBuffer data)
      Constructs a QR Code segment with the specified attributes and data.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      BitBuffer getData()
      Returns the data bits of this segment.
      static boolean isAlphanumeric​(java.lang.CharSequence text)
      Tests whether the specified string can be encoded as a segment in alphanumeric mode.
      static boolean isNumeric​(java.lang.CharSequence text)
      Tests whether the specified string can be encoded as a segment in numeric mode.
      static QrSegment makeAlphanumeric​(java.lang.CharSequence text)
      Returns a segment representing the specified text string encoded in alphanumeric mode.
      static QrSegment makeBytes​(byte[] data)
      Returns a segment representing the specified binary data encoded in byte mode.
      static QrSegment makeEci​(int assignVal)
      Returns a segment representing an Extended Channel Interpretation (ECI) designator with the specified assignment value.
      static QrSegment makeNumeric​(java.lang.CharSequence digits)
      Returns a segment representing the specified string of decimal digits encoded in numeric mode.
      static java.util.List<QrSegment> makeSegments​(java.lang.CharSequence text)
      Returns a list of zero or more segments to represent the specified Unicode text string.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • mode

        public final QrSegment.Mode mode
        The mode indicator of this segment. Not null.

      • numChars

        public final int numChars
        The length of this segment's unencoded data. Measured in characters for numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. Always zero or positive. Not the same as the data's bit length.

    • Constructor Detail

      • QrSegment

        public QrSegment​(QrSegment.Mode md,
                 int numCh,
                 BitBuffer data)
        Constructs a QR Code segment with the specified attributes and data. The character count (numCh) must agree with the mode and the bit buffer length, but the constraint isn't checked. The specified bit buffer is cloned and stored.
        Parameters:
        md - the mode (not null)
        numCh - the data length in characters or bytes, which is non-negative
        data - the data bits (not null)
        Throws:
        java.lang.NullPointerException - if the mode or data is null
        java.lang.IllegalArgumentException - if the character count is negative

    • Method Detail

      • makeBytes

        public static QrSegment makeBytes​(byte[] data)
        Returns a segment representing the specified binary data encoded in byte mode. All input byte arrays are acceptable.

        Any text string can be converted to UTF-8 bytes ( s.getBytes(StandardCharsets.UTF_8)) and encoded as a byte mode segment.

        Parameters:
        data - the binary data (not null)
        Returns:
        a segment (not null) containing the data
        Throws:
        java.lang.NullPointerException - if the array is null

      • makeNumeric

        public static QrSegment makeNumeric​(java.lang.CharSequence digits)
        Returns a segment representing the specified string of decimal digits encoded in numeric mode.
        Parameters:
        digits - the text (not null), with only digits from 0 to 9 allowed
        Returns:
        a segment (not null) containing the text
        Throws:
        java.lang.NullPointerException - if the string is null
        java.lang.IllegalArgumentException - if the string contains non-digit characters

      • makeAlphanumeric

        public static QrSegment makeAlphanumeric​(java.lang.CharSequence text)
        Returns a segment representing the specified text string encoded in alphanumeric mode. The characters allowed are: 0 to 9, A to Z (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
        Parameters:
        text - the text (not null), with only certain characters allowed
        Returns:
        a segment (not null) containing the text
        Throws:
        java.lang.NullPointerException - if the string is null
        java.lang.IllegalArgumentException - if the string contains non-encodable characters

      • makeSegments

        public static java.util.List<QrSegment> makeSegments​(java.lang.CharSequence text)
        Returns a list of zero or more segments to represent the specified Unicode text string. The result may use various segment modes and switch modes to optimize the length of the bit stream.
        Parameters:
        text - the text to be encoded, which can be any Unicode string
        Returns:
        a new mutable list (not null) of segments (not null) containing the text
        Throws:
        java.lang.NullPointerException - if the text is null

      • makeEci

        public static QrSegment makeEci​(int assignVal)
        Returns a segment representing an Extended Channel Interpretation (ECI) designator with the specified assignment value.
        Parameters:
        assignVal - the ECI assignment number (see the AIM ECI specification)
        Returns:
        a segment (not null) containing the data
        Throws:
        java.lang.IllegalArgumentException - if the value is outside the range [0, 106)

      • isNumeric

        public static boolean isNumeric​(java.lang.CharSequence text)
        Tests whether the specified string can be encoded as a segment in numeric mode. A string is encodable iff each character is in the range 0 to 9.
        Parameters:
        text - the string to test for encodability (not null)
        Returns:
        true iff each character is in the range 0 to 9.
        Throws:
        java.lang.NullPointerException - if the string is null
        See Also:
        makeNumeric(CharSequence)

      • isAlphanumeric

        public static boolean isAlphanumeric​(java.lang.CharSequence text)
        Tests whether the specified string can be encoded as a segment in alphanumeric mode. A string is encodable iff each character is in the following set: 0 to 9, A to Z (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
        Parameters:
        text - the string to test for encodability (not null)
        Returns:
        true iff each character is in the alphanumeric mode character set
        Throws:
        java.lang.NullPointerException - if the string is null
        See Also:
        makeAlphanumeric(CharSequence)

      • getData

        public BitBuffer getData()
        Returns the data bits of this segment.
        Returns:
        a new copy of the data bits (not null)