Struct QrCode 

pub struct QrCode { /* private fields */ }

The encoded QR code symbol.

QrCode is Send + Sync, so it can be shared or moved across threads (e.g. for parallel rendering of many codes). This is verified at compile time below.

Implementations

impl QrCode

pub fn new<D: AsRef<[u8]>>(data: D) -> QrResult<Self>

Constructs a new QR code which automatically encodes the given data.

This method uses the “medium” error correction level and automatically chooses the smallest QR code.

use qrcode_rs::QrCode;

let code = QrCode::new(b"Some data").unwrap();

Errors

Returns error if the QR code cannot be constructed, e.g. when the data is too long.

pub fn new_deterministic<D: AsRef<[u8]>>(data: D) -> QrResult<Self>

Available on crate feature deterministic only.

Constructs a new QR code through the explicit deterministic API.

The encoder is deterministic by design: it uses no random seed or process-global state when selecting versions, modes, masks, or rendered modules. This feature-gated helper gives audit-sensitive callers a stable, named entry point for that contract.

Errors

Returns error if the QR code cannot be constructed, e.g. when the data is too long.

pub fn with_error_correction_level<D: AsRef<[u8]>>( data: D, ec_level: EcLevel, ) -> QrResult<Self>

Constructs a new QR code which automatically encodes the given data at a specific error correction level.

This method automatically chooses the smallest QR code.

use qrcode_rs::{QrCode, EcLevel};

let code = QrCode::with_error_correction_level(b"Some data", EcLevel::H).unwrap();

Errors

Returns error if the QR code cannot be constructed, e.g. when the data is too long.

pub fn with_limits<D: AsRef<[u8]>>( data: D, limits: ResourceLimits, ) -> QrResult<Self>

Constructs a QR code with an explicit input, version, and symbol-size budget.

The default QrCode::new constructor remains source-compatible and uses the library’s bounded defaults. This method is useful at trust boundaries where an application needs a stricter per-request budget. Input length is checked before parser allocation; the selected version and module dimensions are checked before returning the symbol.

Errors

Returns QrError::InvalidResourceLimits for a malformed budget, QrError::DataTooLong when the input cannot fit within the data or version budget, and QrError::RenderSizeExceeded when the resulting module dimensions exceed max_render_size.

pub fn new_micro<D: AsRef<[u8]>>(data: D) -> QrResult<Self>

Constructs a new Micro QR code which automatically encodes the given data.

This method uses the “medium” error correction level and automatically chooses the smallest Micro QR code.

use qrcode_rs::QrCode;

let code = QrCode::new_micro(b"123").unwrap();

Errors

Returns error if the data cannot be encoded as a Micro QR code, e.g. when the data is too long.

pub fn micro_with_error_correction_level<D: AsRef<[u8]>>( data: D, ec_level: EcLevel, ) -> QrResult<Self>

Constructs a new Micro QR code which automatically encodes the given data at a specific error correction level.

This method automatically chooses the smallest Micro QR code.

use qrcode_rs::{QrCode, EcLevel};

let code = QrCode::micro_with_error_correction_level(b"123", EcLevel::L).unwrap();

Errors

Returns error if the data cannot be encoded as a Micro QR code, e.g. when the data is too long, or when the error correction level is not supported by any Micro QR version.

pub fn with_version<D: AsRef<[u8]>>( data: D, version: Version, ec_level: EcLevel, ) -> QrResult<Self>

Constructs a new QR code for the given version and error correction level.

use qrcode_rs::{QrCode, Version, EcLevel};

let code = QrCode::with_version(b"Some data", Version::Normal(5), EcLevel::M).unwrap();

This method can also be used to generate Micro QR code.

use qrcode_rs::{QrCode, Version, EcLevel};

let micro_code = QrCode::with_version(b"123", Version::Micro(1), EcLevel::L).unwrap();

Errors

Returns error if the QR code cannot be constructed, e.g. when the data is too long, or when the version and error correction level are incompatible.

pub fn with_const_version<const N: i16, D: AsRef<[u8]>>( data: D, ec_level: EcLevel, ) -> QrResult<Self>

Constructs a new QR code with a compile-time checked normal QR version.

N must be in 1..=40. Invalid values fail during const evaluation when this fixed-version path is monomorphized.

use qrcode_rs::{EcLevel, QrCode, Version};

let code = QrCode::with_const_version::<5, _>(b"Some data", EcLevel::M).unwrap();
assert_eq!(code.version(), Version::Normal(5));

use qrcode_rs::{EcLevel, QrCode};

let _ = QrCode::with_const_version::<41, _>(b"Some data", EcLevel::M);

Errors

Returns error if the QR code cannot be constructed for version N, e.g. when the data is too long for that version and error correction level.

pub fn with_bits(bits: Bits, ec_level: EcLevel) -> QrResult<Self>

Constructs a new QR code with encoded bits.

Use this method only if there are very special need to manipulate the raw bits before encoding. Some examples are:

• Encode data using specific character set with ECI
• Use the FNC1 modes
• Avoid the optimal segmentation algorithm

See the Bits structure for detail.

#![allow(unused_must_use)]

use qrcode_rs::{QrCode, Version, EcLevel};
use qrcode_rs::bits::Bits;

let mut bits = Bits::new(Version::Normal(1));
bits.push_eci_designator(9);
bits.push_byte_data(b"\xca\xfe\xe4\xe9\xea\xe1\xf2 QR");
bits.push_terminator(EcLevel::L);
let qrcode = QrCode::with_bits(bits, EcLevel::L);

Errors

Returns error if the QR code cannot be constructed, e.g. when the bits are too long, or when the version and error correction level are incompatible.

pub fn batch<I, D>(inputs: I, ec_level: EcLevel) -> QrResult<Vec<Self>>

where I: IntoIterator<Item = D>, D: AsRef<[u8]>,

Encodes many inputs at once at the given error-correction level, stopping at the first input that fails to encode.

Examples

use qrcode_rs::{QrCode, EcLevel};

let codes = QrCode::batch(&["alpha", "beta", "gamma"], EcLevel::M).unwrap();
assert_eq!(codes.len(), 3);

pub fn batch_builder<I>(inputs: I) -> QrBatchBuilder<I>

Available on crate feature std only.

Creates a library-level batch builder for encoding, rendering, and packaging named outputs.

This convenience entry point is available with the std feature. It is useful when callers want stable output names plus helpers such as ZIP archives or PNG contact sheets without invoking the CLI.

Examples

use qrcode_rs::QrCode;

let rendered = QrCode::batch_builder(["alpha", "beta"])
    .file_extension("txt")
    .render::<char>()
    .unwrap();

assert_eq!(rendered.entries()[0].name(), "qr-0001.txt");

pub fn batch_render(codes: &[Self]) -> BatchRender<'_>

Creates a builder for rendering an already encoded batch into stable, named in-memory outputs.

This keeps existing encoded symbols reusable when callers need multiple render styles or want to decide packaging separately with the batch module.

use qrcode_rs::{EcLevel, QrCode};

let codes = QrCode::batch(["alpha", "beta"], EcLevel::M)?;
let rendered = QrCode::batch_render(&codes)
    .extension("txt")
    .build::<char>();

assert_eq!(rendered[0].name(), "qr-0001.txt");

pub fn par_batch<I, D>(inputs: I, ec_level: EcLevel) -> QrResult<Vec<Self>>

where I: IntoParallelIterator<Item = D>, I::Iter: IndexedParallelIterator, D: AsRef<[u8]> + Send,

Available on crate feature parallel only.

Encodes many inputs in parallel at the given error-correction level.

This method is available with the parallel feature. It preserves input order in the returned vector and returns the first encoding error in that same order. Small batches should continue to use batch; this is intended for larger, CPU-bound batches.

Examples

use qrcode_rs::{EcLevel, QrCode};

let codes = QrCode::par_batch(vec!["alpha", "beta", "gamma"], EcLevel::M).unwrap();
assert_eq!(codes.len(), 3);

pub fn stream<I, D>(inputs: I) -> QrCodeStream<I::IntoIter>

where I: IntoIterator<Item = D>, D: AsRef<[u8]>,

Lazily encodes inputs into QR codes with the default error-correction level.

Unlike batch, this returns an iterator and does not collect every generated code into memory.

Examples

use qrcode_rs::{EcLevel, QrCode};

let widths = QrCode::stream(["alpha", "beta"])
    .map(|code| code.map(|code| (code.error_correction_level(), code.width())))
    .collect::<Result<Vec<_>, _>>()
    .unwrap();

assert_eq!(widths, vec![(EcLevel::M, 21), (EcLevel::M, 21)]);

pub fn stream_with_error_correction_level<I, D>( inputs: I, ec_level: EcLevel, ) -> QrCodeStream<I::IntoIter>

where I: IntoIterator<Item = D>, D: AsRef<[u8]>,

Lazily encodes inputs into QR codes at ec_level.

The iterator yields one QrResult<QrCode> per input, so callers can stop at the first error with collect::<Result<Vec<_>, _>>() or handle errors per item while keeping memory usage bounded by the active item.

pub const fn version(&self) -> Version

Gets the version of this QR code.

pub const fn error_correction_level(&self) -> EcLevel

Gets the error correction level of this QR code.

pub const fn width(&self) -> usize

Gets the number of modules per side, i.e. the width of this QR code.

The width here does not contain the quiet zone paddings.

pub fn max_allowed_errors(&self) -> usize

Gets the maximum number of allowed erratic modules can be introduced before the data becomes corrupted. Note that errors should not be introduced to functional modules.

pub fn info(&self) -> Info

Returns metadata about this QR code (version, error-correction level, dimensions, module count, error tolerance, and data capacity).

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hello").unwrap();
let info = code.info();
assert_eq!(info.width(), code.width());
assert_eq!(info.module_count(), code.width() * code.width());
assert!(info.data_capacity_bytes() > 0);

pub fn analyze(&self) -> Analysis

Returns diagnostic stats for this code: dark-module ratio and the split between functional and data modules. Combine with QrCode::info for version / capacity. Computed on demand (scans the grid).

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hello").unwrap();
let a = code.analyze();
assert!(a.dark_ratio() > 0.0 && a.dark_ratio() < 1.0);
assert_eq!(a.functional_modules() + a.data_modules(), code.width() * code.width());

pub fn is_functional(&self, x: usize, y: usize) -> bool

Checks whether a module at coordinate (x, y) is a functional module or not.

pub fn to_debug_str(&self, on_char: char, off_char: char) -> String

Converts the QR code into a human-readable string. This is mainly for debugging only.

pub fn colors(&self) -> &[Color]

Returns the module colors as a borrowed slice — no allocation. Use this in preference to to_colors when you only need to read the modules.

The slice is row-major, with width() * width() entries and no quiet zone.

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hi").unwrap();
let colors = code.colors();
assert_eq!(colors.len(), code.width() * code.width());

pub fn module_view(&self) -> ModuleView<'_>

Returns a borrowed, read-only module-grid view.

This is the facade-friendly ModuleSource adapter for APIs that accept a borrowed QR module source without needing ownership of the full QrCode.

Examples

use qrcode_rs::{ModuleSource, QrCode};

let code = QrCode::new(b"hi").unwrap();
let view = code.module_view();
assert_eq!(view.width(), code.width());
assert_eq!(view.modules(), code.colors());

pub fn as_ref(&self) -> QrCodeRef<'_>

Returns a borrowed QR symbol view with module data and metadata.

Unlike to_colors, this does not allocate or clone the module grid. It is useful for renderers and analyzers that accept a QrSymbol and need version/error-correction metadata in addition to read-only module access.

Examples

use qrcode_rs::{ModuleSource, QrCode, QrSymbol};

let code = QrCode::new(b"hi").unwrap();
let borrowed = code.as_ref();
assert_eq!(borrowed.version(), code.version());
assert_eq!(borrowed.modules(), code.colors());

pub fn to_colors(&self) -> Vec<Color>

Converts the QR code to a vector of colors.

pub fn into_colors(self) -> Vec<Color>

Converts the QR code to a vector of colors.

pub fn render<P: Pixel>(&self) -> Renderer<'_, P>

Renders the QR code into an image. The result is an image builder, which you may do some additional configuration before copying it into a concrete image. Note: theimage crate itself also provides method to rotate the image, or overlay a logo on top of the QR code.

Examples

let image = QrCode::new(b"hello").unwrap()
                   .render()
                   .dark_color(Rgb([0, 0, 128]))
                   .light_color(Rgb([224, 224, 224])) // adjust colors
                   .quiet_zone(false)          // disable quiet zone (white border)
                   .min_dimensions(300, 300)   // sets minimum image size
                   .build();

pub fn render_builder<P: Pixel>(&self) -> Renderer<'_, P>

Returns the render builder for this QR code.

This is an explicit builder-style alias for render, useful when code wants the construction and rendering paths to read the same way (QrCode::builder(...).build()?.render_builder::<P>()...).

Examples

use qrcode_rs::QrCode;

let text = QrCode::new(b"hello").unwrap()
    .render_builder::<char>()
    .dark_color('#')
    .quiet_zone(false)
    .module_dimensions(1, 1)
    .build();

assert!(text.contains('#'));

pub async fn render_async<P>(&self) -> Result<P::Image, JoinError>

where P: Pixel + Send + 'static, P::Image: Send + 'static,

Available on crate feature async only.

Renders the QR code on Tokio’s blocking thread pool.

This opt-in async helper is available with the async feature. It clones the compact module grid and performs the synchronous render work inside tokio::task::spawn_blocking, so callers running inside a Tokio runtime do not execute CPU-heavy rendering on the async worker thread.

Errors

Returns tokio::task::JoinError if the blocking task is cancelled or panics.

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hello").unwrap();
let runtime = tokio::runtime::Builder::new_current_thread().build().unwrap();
let text = runtime.block_on(code.render_async::<char>()).unwrap();
assert!(!text.is_empty());

pub fn encode_with( registry: &PluginRegistry, encoder_name: &str, input: &[u8], config: &EncodeConfig, ) -> Result<EncodedOutput, PluginError>

Encodes raw input through a named plugin encoder.

This is the encoder-side counterpart to QrCode::render_with: it looks up encoder_name in registry, builds the dynamic encoder with config, and returns the encoder’s type-erased output.

Errors

Returns PluginError::EncoderNotFound when no encoder is registered with encoder_name, or another PluginError returned by the encoder.

pub fn render_with( &self, registry: &PluginRegistry, renderer_name: &str, config: &RenderConfig, ) -> Result<RenderOutput, PluginError>

Renders the QR code through a named plugin renderer.

The method looks up renderer_name in registry, copies this QR code’s module grid into a mutable ModuleGrid, applies all registered PostProcessor values in registration order, then renders the transformed grid through the selected dynamic renderer.

Errors

Returns PluginError::RendererNotFound when no renderer is registered with renderer_name, or another PluginError from grid construction, postprocessing, or rendering.

pub fn with_plugins<'a>( &'a self, registry: &'a PluginRegistry, ) -> QrCodePlugins<'a>

Binds this QR code to a plugin registry for fluent plugin rendering.

The returned view borrows both values and delegates to QrCode::render_with, so it has the same deterministic, explicit registry behavior without introducing global plugin state.

impl QrCode

pub fn builder<D: AsRef<[u8]>>(data: D) -> QrCodeBuilder<D>

Creates a QrCodeBuilder for configuring and constructing a QR code.

This is an ergonomic alternative to the with_* constructors. The builder uses the same encoding paths, so its output is identical to the equivalent constructor.

Examples

use qrcode_rs::{QrCode, EcLevel};

let code = QrCode::builder(b"https://example.com")
    .ec_level(EcLevel::H)
    .build()
    .unwrap();

pub fn rows(&self) -> Rows<'_>

Returns an iterator yielding one Row of modules at a time.

Each row iterates over the module Colors from left to right. The quiet zone is not included.

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hi").unwrap();
for row in code.rows() {
    for color in row {
    }
}

pub fn dark_modules(&self) -> DarkModules<'_>

Returns an iterator over the (x, y) coordinates of every dark module, convenient for custom rendering. The quiet zone is not included.

Examples

use qrcode_rs::QrCode;

let code = QrCode::new(b"hi").unwrap();
let dark_count = code.dark_modules().count();

pub fn for_url<D: AsRef<[u8]>>(url: D) -> QrResult<Self>

Encodes a URL, using high error correction (robust to print damage).

Errors

Returns an error only if the URL is too long to encode.

pub fn for_text<D: AsRef<[u8]>>(text: D) -> QrResult<Self>

Encodes plain text at the default (medium) error correction level.

Errors

Returns an error only if the text is too long to encode.

pub fn for_wifi(ssid: &str, password: &str, auth: &str) -> QrResult<Self>

Encodes a WiFi configuration that most phone cameras will offer to join.

auth is one of WPA, WEP or nopass. Special characters in the SSID/password are backslash-escaped per the WiFi QR specification.

Errors

Returns an error if the resulting payload is too long to encode.

Examples

use qrcode_rs::QrCode;

let code = QrCode::for_wifi("MyNetwork", "p\\a;ss", "WPA").unwrap();

pub fn for_vcard(name: &str, phone: &str, email: &str) -> QrResult<Self>

Encodes a minimal vCard 3.0 contact card.

Errors

Returns an error if the resulting payload is too long to encode.

Examples

use qrcode_rs::QrCode;

let code = QrCode::for_vcard("John Doe", "+1234567890", "john@example.com").unwrap();

pub fn for_gs1<D: AsRef<[u8]>>(data: D) -> QrResult<Self>

Encodes a GS1 data carrier (FNC1 in first position), e.g. a GTIN / application-identifier payload such as "010491234512345915970331301234561842". Uses medium error correction and the smallest fitting version.

Errors

Returns an error if the data is too long to encode.

Examples

use qrcode_rs::QrCode;

let code = QrCode::for_gs1("010491234512345915970331301234561842").unwrap();

pub fn structured_append<D: AsRef<[u8]>>( payload: D, symbols: u8, ec: EcLevel, ) -> QrResult<Vec<Self>>

Splits payload across symbols QR codes (2..=16) using Structured Append (ISO/IEC 18004 §7.4), each at error-correction level ec. Every symbol is the smallest version that fits its chunk plus the 20-bit Structured Append header.

This is a thin convenience over crate::structured_append::StructuredAppend; see that type for the split and parity details, and crate::structured_append::reassemble for recombining decoded symbols.

Errors

Returns QrError::InvalidStructuredAppend if symbols is not in 2..=16, or QrError::DataTooLong if a chunk cannot fit even version 40 at ec.

Examples

use qrcode_rs::{EcLevel, QrCode};

let codes = QrCode::structured_append(b"split across multiple symbols", 3, EcLevel::M)?;
assert_eq!(codes.len(), 3);

pub fn alt_text<D: AsRef<[u8]>>(data: D) -> String

Generates accessible alt text describing a QR code that encodes data.

URLs are described as “linking to …”; other payloads as “containing: …”. Use the result as the alt of an <img> or the aria-label of an inline SVG so assistive technology can describe the code without decoding it.

This is an associated function (it does not require a constructed QrCode), so the input data does not need to be retained on the code.

Examples

use qrcode_rs::QrCode;

assert_eq!(QrCode::alt_text("https://example.com"), "QR code linking to https://example.com");
assert_eq!(QrCode::alt_text("hello"), "QR code containing: hello");

pub fn alt_text_custom<D: AsRef<[u8]>, F: FnOnce(&[u8]) -> String>( data: D, f: F, ) -> String

Generates alt text with a custom formatter that receives the raw bytes.

Examples

use qrcode_rs::QrCode;

let alt = QrCode::alt_text_custom("hello", |data| {
    format!("A QR code with {} bytes", data.len())
});
assert_eq!(alt, "A QR code with 5 bytes");

impl QrCode

pub fn to_serializable(&self) -> QrCodeData

Available on crate feature serde only.

Serializes this QR code into a QrCodeData (requires the serde feature).

pub fn from_serializable(data: QrCodeData) -> Self

Available on crate feature serde only.

Reconstructs a QrCode from QrCodeData (requires the serde feature).

data is trusted: content.len() must equal width * width (checked in debug builds). Pair with QrCode::to_serializable.

Trait Implementations

impl Clone for QrCode

fn clone(&self) -> QrCode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Index<(usize, usize)> for QrCode

type Output = Color

The returned type after indexing.

fn index(&self, (x, y): (usize, usize)) -> &Color

Performs the indexing (container[index]) operation.

impl ModuleStorage for QrCode

fn get(&self, x: usize, y: usize) -> Color

Returns the color at (x, y).

fn set(&mut self, x: usize, y: usize, color: Color)

Sets the color at (x, y).

fn width(&self) -> usize

Returns the number of modules per row.

fn height(&self) -> usize

Returns the number of module rows.

fn modules(&self) -> &[Color]

Returns all modules in row-major order.

fn is_empty(&self) -> bool

Returns whether this storage has no modules.

impl QrSymbol for QrCode

fn version(&self) -> Version

Returns the encoded QR or Micro QR version.

fn error_correction_level(&self) -> EcLevel

Returns the encoded error-correction level.

fn quiet_zone(&self) -> u32

Returns the default quiet-zone width in modules for this symbol.