diff --git a/src/bits.rs b/src/bits.rs index 022ad37..5d1f93f 100644 --- a/src/bits.rs +++ b/src/bits.rs @@ -99,6 +99,12 @@ impl Bits { /// The maximum number of bits allowed by the provided QR code version and /// error correction level. + /// + /// # Errors + /// + /// Returns `Err(QrError::InvalidVersion)` if it is not valid to use the + /// `ec_level` for the given version (e.g. `Version::Micro(1)` with + /// `EcLevel::H`). pub fn max_len(&self, ec_level: EcLevel) -> QrResult { self.version.fetch(ec_level, &DATA_LENGTHS) } @@ -179,6 +185,8 @@ pub enum ExtendedMode { impl Bits { /// Push the mode indicator to the end of the bits. /// + /// # Errors + /// /// If the mode is not supported in the provided version, this method /// returns `Err(QrError::UnsupportedCharacterSet)`. pub fn push_mode_indicator(&mut self, mode: ExtendedMode) -> QrResult<()> { @@ -239,6 +247,8 @@ impl Bits { /// 29 | GB-18030 (Simplified Chinese) /// 30 | EUC-KR (Korean) /// + /// # Errors + /// /// If the QR code version does not support ECI, this method will return /// `Err(QrError::UnsupportedCharacterSet)`. /// @@ -321,6 +331,10 @@ impl Bits { /// Encodes a numeric string to the bits. /// /// The data should only contain the characters 0 to 9. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. pub fn push_numeric_data(&mut self, data: &[u8]) -> QrResult<()> { self.push_header(Mode::Numeric, data.len())?; for chunk in data.chunks(3) { @@ -425,6 +439,10 @@ impl Bits { /// /// The data should only contain the charaters A to Z (excluding lowercase), /// 0 to 9, space, `$`, `%`, `*`, `+`, `-`, `.`, `/` or `:`. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. pub fn push_alphanumeric_data(&mut self, data: &[u8]) -> QrResult<()> { self.push_header(Mode::Alphanumeric, data.len())?; for chunk in data.chunks(2) { @@ -470,6 +488,10 @@ mod alphanumeric_tests { impl Bits { /// Encodes 8-bit byte data to the bits. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. pub fn push_byte_data(&mut self, data: &[u8]) -> QrResult<()> { self.push_header(Mode::Byte, data.len())?; for b in data { @@ -524,6 +546,13 @@ mod byte_tests { impl Bits { /// Encodes Shift JIS double-byte data to the bits. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. + /// + /// Returns `Err(QrError::InvalidCharacter)` if the data is not Shift JIS + /// double-byte data (e.g. if the length of data is not an even number). pub fn push_kanji_data(&mut self, data: &[u8]) -> QrResult<()> { self.push_header(Mode::Kanji, data.len() / 2)?; for kanji in data.chunks(2) { @@ -583,6 +612,11 @@ impl Bits { /// bits.push_alphanumeric_data(b"%10ABC123"); /// /// In QR code, the character `%` is used as the data field separator (0x1D). + /// + /// # Errors + /// + /// If the mode is not supported in the provided version, this method + /// returns `Err(QrError::UnsupportedCharacterSet)`. pub fn push_fnc1_first_position(&mut self) -> QrResult<()> { self.push_mode_indicator(ExtendedMode::Fnc1First) } @@ -607,6 +641,11 @@ impl Bits { /// ```ignore /// bits.push_fnc1_second_position(b'A' + 100); /// ``` + /// + /// # Errors + /// + /// If the mode is not supported in the provided version, this method + /// returns `Err(QrError::UnsupportedCharacterSet)`. pub fn push_fnc1_second_position(&mut self, application_indicator: u8) -> QrResult<()> { self.push_mode_indicator(ExtendedMode::Fnc1Second)?; self.push_number(8, u16::from(application_indicator)); @@ -670,6 +709,14 @@ static DATA_LENGTHS: [[usize; 4]; 44] = [ impl Bits { /// Pushes the ending bits to indicate no more data. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. + /// + /// Returns `Err(QrError::InvalidVersion)` if it is not valid to use the + /// `ec_level` for the given version (e.g. `Version::Micro(1)` with + /// `EcLevel::H`). pub fn push_terminator(&mut self, ec_level: EcLevel) -> QrResult<()> { let terminator_size = match self.version { Version::Micro(a) => a.as_usize() * 2 + 1, @@ -770,6 +817,13 @@ mod finish_tests { impl Bits { /// Push a segmented data to the bits, and then terminate it. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. + /// + /// Returns `Err(QrError::InvalidData)` if the segment refers to incorrectly + /// encoded byte sequence. pub fn push_segments(&mut self, data: &[u8], segments_iter: I) -> QrResult<()> where I: Iterator, @@ -787,6 +841,10 @@ impl Bits { } /// Pushes the data the bits, using the optimal encoding. + /// + /// # Errors + /// + /// Returns `Err(QrError::DataTooLong)` on overflow. pub fn push_optimal_data(&mut self, data: &[u8]) -> QrResult<()> { let segments = Parser::new(data).optimize(self.version); self.push_segments(data, segments) @@ -838,6 +896,11 @@ mod encode_tests { /// the result. /// /// This method will not consider any Micro QR code versions. +/// +/// # Errors +/// +/// Returns `Err(QrError::DataTooLong)` if the data is too long to fit even the +/// highest QR code version. pub fn encode_auto(data: &[u8], ec_level: EcLevel) -> QrResult { let segments = Parser::new(data).collect::>(); for version in &[Version::Normal(9), Version::Normal(26), Version::Normal(40)] { diff --git a/src/ec.rs b/src/ec.rs index dbe9594..857de08 100644 --- a/src/ec.rs +++ b/src/ec.rs @@ -98,6 +98,12 @@ fn test_interleave() { /// Constructs data and error correction codewords ready to be put in the QR /// code matrix. +/// +/// # Errors +/// +/// Returns `Err(QrError::InvalidVersion)` if it is not valid to use the +/// `ec_level` for the given version (e.g. `Version::Micro(1)` with +/// `EcLevel::H`). pub fn construct_codewords(rawbits: &[u8], version: Version, ec_level: EcLevel) -> QrResult<(Vec, Vec)> { let (block_1_size, block_1_count, block_2_size, block_2_count) = version.fetch(ec_level, &DATA_BYTES_PER_BLOCK)?; @@ -162,6 +168,12 @@ mod construct_codewords_test { /// Computes the maximum allowed number of erratic modules can be introduced to /// the QR code, before the data becomes truly corrupted. +/// +/// # Errors +/// +/// Returns `Err(QrError::InvalidVersion)` if it is not valid to use the +/// `ec_level` for the given version (e.g. `Version::Micro(1)` with +/// `EcLevel::H`). pub fn max_allowed_errors(version: Version, ec_level: EcLevel) -> QrResult { use crate::EcLevel::{L, M}; use crate::Version::{Micro, Normal}; diff --git a/src/lib.rs b/src/lib.rs index 4edb565..b748659 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -14,7 +14,9 @@ //! let image = code.render::>().build(); //! //! // Save the image. +//! # if cfg!(unix) { //! image.save("/tmp/qrcode.png").unwrap(); +//! # } //! //! // You can also render it into a string. //! let string = code.render() @@ -68,6 +70,10 @@ impl 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>(data: D) -> QrResult { Self::with_error_correction_level(data, EcLevel::M) } @@ -81,6 +87,10 @@ impl QrCode { /// /// 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_error_correction_level>(data: D, ec_level: EcLevel) -> QrResult { let bits = bits::encode_auto(data.as_ref(), ec_level)?; Self::with_bits(bits, ec_level) @@ -99,6 +109,11 @@ impl QrCode { /// /// 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_version>(data: D, version: Version, ec_level: EcLevel) -> QrResult { let mut bits = bits::Bits::new(version); bits.push_optimal_data(data.as_ref())?; @@ -128,6 +143,11 @@ impl QrCode { /// 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 with_bits(bits: bits::Bits, ec_level: EcLevel) -> QrResult { let version = bits.version(); let data = bits.into_bytes(); diff --git a/src/render/unicode.rs b/src/render/unicode.rs index 060066c..4ae97b8 100644 --- a/src/render/unicode.rs +++ b/src/render/unicode.rs @@ -22,14 +22,14 @@ impl Pixel for Dense1x2 { } impl Dense1x2 { - fn value(&self) -> u8 { + fn value(self) -> u8 { match self { Dense1x2::Dark => 1, Dense1x2::Light => 0, } } - fn parse_2_bits(sym: &u8) -> &'static str { - CODEPAGE[*sym as usize] + fn parse_2_bits(sym: u8) -> &'static str { + CODEPAGE[usize::from(sym)] } } @@ -68,7 +68,7 @@ impl RenderCanvas for Canvas1x2 { rows[0].iter().map(|top| (top * 2)).collect::>() } } - .iter() + .into_iter() // Mapping those 2-bit numbers to corresponding pixels. .map(Dense1x2::parse_2_bits) .collect::>() diff --git a/src/types.rs b/src/types.rs index 22c7e6f..95a716c 100644 --- a/src/types.rs +++ b/src/types.rs @@ -146,7 +146,9 @@ impl Version { /// inner array represents the content in each error correction level, in /// the order [L, M, Q, H]. /// - /// If the entry compares equal to the default value of T, this method + /// # Errors + /// + /// If the entry compares equal to the default value of `T`, this method /// returns `Err(QrError::InvalidVersion)`. pub fn fetch(self, ec_level: EcLevel, table: &[[T; 4]]) -> QrResult where