Class QrCode

java.lang.Object
io.nayuki.qrcodegen.QrCode

public final class QrCode
extends java.lang.Object
A QR Code symbol, which is a type of two-dimension barcode. Invented by Denso Wave and described in the ISO/IEC 18004 standard.

Instances of this class represent an immutable square grid of dark and light cells. The class provides static factory functions to create a QR Code from text or binary data. The class covers the QR Code Model 2 specification, supporting all versions (sizes) from 1 to 40, all 4 error correction levels, and 4 character encoding modes.

Ways to create a QR Code object:

(Note that all ways require supplying the desired error correction level.)

See Also:
QrSegment
  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  QrCode.Ecc
    The error correction level in a QR Code symbol.
  • Field Summary

    Fields
    Modifier and Type Field Description
    QrCode.Ecc errorCorrectionLevel
    The error correction level used in this QR Code, which is not null.
    int mask
    The index of the mask pattern used in this QR Code, which is between 0 and 7 (inclusive).
    static int MAX_VERSION
    The maximum version number (40) supported in the QR Code Model 2 standard.
    static int MIN_VERSION
    The minimum version number (1) supported in the QR Code Model 2 standard.
    int size
    The width and height of this QR Code, measured in modules, between 21 and 177 (inclusive).
    int version
    The version number of this QR Code, which is between 1 and 40 (inclusive).
  • Constructor Summary

    Constructors
    Constructor Description
    QrCode​(int ver, QrCode.Ecc ecl, byte[] dataCodewords, int msk)
    Constructs a QR Code with the specified version number, error correction level, data codeword bytes, and mask number.
  • Method Summary

    Modifier and Type Method Description
    static QrCode encodeBinary​(byte[] data, QrCode.Ecc ecl)
    Returns a QR Code representing the specified binary data at the specified error correction level.
    static QrCode encodeSegments​(java.util.List<QrSegment> segs, QrCode.Ecc ecl)
    Returns a QR Code representing the specified segments at the specified error correction level.
    static QrCode encodeSegments​(java.util.List<QrSegment> segs, QrCode.Ecc ecl, int minVersion, int maxVersion, int mask, boolean boostEcl)
    Returns a QR Code representing the specified segments with the specified encoding parameters.
    static QrCode encodeText​(java.lang.String text, QrCode.Ecc ecl)
    Returns a QR Code representing the specified Unicode text string at the specified error correction level.
    boolean getModule​(int x, int y)
    Returns the color of the module (pixel) at the specified coordinates, which is false for light or true for dark.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • version

      public final int version
      The version number of this QR Code, which is between 1 and 40 (inclusive). This determines the size of this barcode.
    • size

      public final int size
      The width and height of this QR Code, measured in modules, between 21 and 177 (inclusive). This is equal to version × 4 + 17.
    • errorCorrectionLevel

      public final QrCode.Ecc errorCorrectionLevel
      The error correction level used in this QR Code, which is not null.
    • mask

      public final int mask
      The index of the mask pattern used in this QR Code, which is between 0 and 7 (inclusive).

      Even if a QR Code is created with automatic masking requested (mask = −1), the resulting object still has a mask value between 0 and 7.

    • MIN_VERSION

      public static final int MIN_VERSION
      The minimum version number (1) supported in the QR Code Model 2 standard.
      See Also:
      Constant Field Values
    • MAX_VERSION

      public static final int MAX_VERSION
      The maximum version number (40) supported in the QR Code Model 2 standard.
      See Also:
      Constant Field Values
  • Constructor Details

    • QrCode

      public QrCode​(int ver, QrCode.Ecc ecl, byte[] dataCodewords, int msk)
      Constructs a QR Code with the specified version number, error correction level, data codeword bytes, and mask number.

      This is a low-level API that most users should not use directly. A mid-level API is the encodeSegments(List,Ecc,int,int,int,boolean) function.

      Parameters:
      ver - the version number to use, which must be in the range 1 to 40 (inclusive)
      ecl - the error correction level to use
      dataCodewords - the bytes representing segments to encode (without ECC)
      msk - the mask pattern to use, which is either −1 for automatic choice or from 0 to 7 for fixed choice
      Throws:
      java.lang.NullPointerException - if the byte array or error correction level is null
      java.lang.IllegalArgumentException - if the version or mask value is out of range, or if the data is the wrong length for the specified version and error correction level
  • Method Details

    • encodeText

      public static QrCode encodeText​(java.lang.String text, QrCode.Ecc ecl)
      Returns a QR Code representing the specified Unicode text string at the specified error correction level. As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
      Parameters:
      text - the text to be encoded (not null), which can be any Unicode string
      ecl - the error correction level to use (not null) (boostable)
      Returns:
      a QR Code (not null) representing the text
      Throws:
      java.lang.NullPointerException - if the text or error correction level is null
      DataTooLongException - if the text fails to fit in the largest version QR Code at the ECL, which means it is too long
    • encodeBinary

      public static QrCode encodeBinary​(byte[] data, QrCode.Ecc ecl)
      Returns a QR Code representing the specified binary data at the specified error correction level. This function always encodes using the binary segment mode, not any text mode. The maximum number of bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
      Parameters:
      data - the binary data to encode (not null)
      ecl - the error correction level to use (not null) (boostable)
      Returns:
      a QR Code (not null) representing the data
      Throws:
      java.lang.NullPointerException - if the data or error correction level is null
      DataTooLongException - if the data fails to fit in the largest version QR Code at the ECL, which means it is too long
    • encodeSegments

      public static QrCode encodeSegments​(java.util.List<QrSegment> segs, QrCode.Ecc ecl)
      Returns a QR Code representing the specified segments at the specified error correction level. The smallest possible QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.

      This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and byte) to encode text in less space. This is a mid-level API; the high-level API is encodeText(String,Ecc) and encodeBinary(byte[],Ecc).

      Parameters:
      segs - the segments to encode
      ecl - the error correction level to use (not null) (boostable)
      Returns:
      a QR Code (not null) representing the segments
      Throws:
      java.lang.NullPointerException - if the list of segments, any segment, or the error correction level is null
      DataTooLongException - if the segments fail to fit in the largest version QR Code at the ECL, which means they are too long
    • encodeSegments

      public static QrCode encodeSegments​(java.util.List<QrSegment> segs, QrCode.Ecc ecl, int minVersion, int maxVersion, int mask, boolean boostEcl)
      Returns a QR Code representing the specified segments with the specified encoding parameters. The smallest possible QR Code version within the specified range is automatically chosen for the output. Iff boostEcl is true, then the ECC level of the result may be higher than the ecl argument if it can be done without increasing the version. The mask number is either between 0 to 7 (inclusive) to force that mask, or −1 to automatically choose an appropriate mask (which may be slow).

      This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and byte) to encode text in less space. This is a mid-level API; the high-level API is encodeText(String,Ecc) and encodeBinary(byte[],Ecc).

      Parameters:
      segs - the segments to encode
      ecl - the error correction level to use (not null) (boostable)
      minVersion - the minimum allowed version of the QR Code (at least 1)
      maxVersion - the maximum allowed version of the QR Code (at most 40)
      mask - the mask number to use (between 0 and 7 (inclusive)), or −1 for automatic mask
      boostEcl - increases the ECC level as long as it doesn't increase the version number
      Returns:
      a QR Code (not null) representing the segments
      Throws:
      java.lang.NullPointerException - if the list of segments, any segment, or the error correction level is null
      java.lang.IllegalArgumentException - if 1 ≤ minVersion ≤ maxVersion ≤ 40 or −1 ≤ mask ≤ 7 is violated
      DataTooLongException - if the segments fail to fit in the maxVersion QR Code at the ECL, which means they are too long
    • getModule

      public boolean getModule​(int x, int y)
      Returns the color of the module (pixel) at the specified coordinates, which is false for light or true for dark. The top left corner has the coordinates (x=0, y=0). If the specified coordinates are out of bounds, then false (light) is returned.
      Parameters:
      x - the x coordinate, where 0 is the left edge and size−1 is the right edge
      y - the y coordinate, where 0 is the top edge and size−1 is the bottom edge
      Returns:
      true if the coordinates are in bounds and the module at that location is dark, or false (light) otherwise