vatfluid 0.3.0

// Copyright (c) 2016 vatfluid developers
//
// Licensed under the Apache License, Version 2.0
// <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0> or the MIT
// license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. All files in the project carrying such notice may not be copied,
// modified, or distributed except according to those terms.

//! Zero allocation UTF-8 validation on `&[u8]` slices.
//! Allows for incomplete UTF-8 sequences.  Returns the position in the buffer that has been
//! validated successfully.
//!
//! ```
//! # #[macro_use]
//! # extern crate assert_matches;
//! # extern crate vatfluid;
//! #
//! use vatfluid::{Error, ErrorKind, Success, validate};
//!
//! # fn main() {
//! // A `Complete` result.
//! let buf = b"Hello, World!";
//! match validate(buf) {
//!     Ok(Success::Complete(pos)) => {
//!         assert!(pos == 13);
//!         assert!(pos == buf.len());
//!     }
//!     Ok(Success::Incomplete(_needed, _pos)) => {
//!         assert!(false);
//!     }
//!     Err(_e) => {
//!         assert!(false);
//!     }
//! }
//!
//! // An `Incomplete` result.
//! let inc_buf = vec![0xc2, 0xa2, 0xc2];
//! match validate(&inc_buf) {
//!     Ok(Success::Complete(_pos)) => {
//!         assert!(false);
//!     }
//!     Ok(Success::Incomplete(needed, pos)) => {
//!         assert!(needed == 1);
//!         assert!(pos == 2);
//!     }
//!     Err(_e) => {
//!         assert!(false);
//!     }
//! }
//!
//! // An `Error` result.
//! let error_buf = vec![0xf4, 0x90, 0x80, 0x80];
//! match validate(&error_buf) {
//!     Ok(Success::Complete(_pos)) => {
//!         assert!(false);
//!     }
//!     Ok(Success::Incomplete(_needed, _pos)) => {
//!         assert!(false);
//!     }
//!     Err(e) => {
//!         assert_matches!(e, Error(ErrorKind::BeyondMaximumCodePoint, _));
//!     }
//! }
//! # }
//! ```
#[macro_use]
extern crate error_chain;
#[cfg(test)]
#[macro_use]
extern crate assert_matches;

// mod error;
mod error;
mod parser;

pub use error::{Error, ErrorKind};
pub use parser::{validate, Success};

#[cfg(test)]
mod tests {
    use error::{Error, ErrorKind};
    use parser::{self, Success};

    // Smallest 1-byte (U+0000)
    const V1: [u8; 1] = [0x00];
    // 1-byte (U+0014)
    const V2: [u8; 1] = [0x14];
    // Largest valid 1-byte (U+007F)
    const V3: [u8; 1] = [0x7F];
    // Smallest 2-byte. (U+0080)
    // Smallest 11-bits code point 1000 0000 (U+0080), that won't fit in 7 bits.
    // 110 00000 10 000000
    const V4: [u8; 2] = [0xc2, 0x80];
    // 2-byte ¢ (U+00A2)
    const V5: [u8; 2] = [0xc2, 0xa2];
    // Largest 2-byte. (U+07FF)
    // Largest 11-bits code point 11111111111
    // 110 11111 10 111111
    const V6: [u8; 2] = [0xdf, 0xbf];
    // Smallest 3-byte (U+0800)
    // Smallest 16-bits code-point 00001000 00000000 (U+0800), that won't fit in 11 bits.
    // 1110 0000 10 100000 10 000000
    const V7: [u8; 3] = [0xe0, 0xa0, 0x80];
    /// 3-byte € (U+20AC)
    const V8: [u8; 3] = [0xe2, 0x82, 0xac];
    // Largest 3-byte (U+FFFF)
    // Largest 16-bits code-point 11111111 11111111 (U+FFFF)
    // 1110 1111 10 111111 10 111111
    const V9: [u8; 3] = [0xef, 0xbf, 0xbf];
    // Smallest 4-byte. (U+10000)
    // Smallest 21-bits code-point 00001 00000000 00000000 (U+10000), that won't fit in 16 bits.
    // 11110 000 10 010000 10 000000 10 000000
    const V10: [u8; 4] = [0xf0, 0x90, 0x80, 0x80];
    // 4-byte (U+10348)
    const V11: [u8; 4] = [0xf0, 0x90, 0x8d, 0x88];
    // Largest 4-byte
    // Largest 21-bits code point 10000 11111111 11111111 (U+10FFFF), allowed by spec.
    // 11110 100 10 001111 10 111111 10 111111
    const V12: [u8; 4] = [0xf4, 0x8f, 0xbf, 0xbf];

    // Invalid two-byte continuation byte. Must be 0x80 - 0xbf.
    const C1: [u8; 2] = [0xc0, 0x00];
    const C2: [u8; 2] = [0xc0, 0x7f];
    const C3: [u8; 2] = [0xc0, 0xc0];
    const C4: [u8; 2] = [0xc0, 0xff];

    // Invalid three-byte continuation byte in second byte. Must be 0x80 - 0xbf.
    const C5: [u8; 3] = [0xe0, 0x00, 0x80];
    const C6: [u8; 3] = [0xe0, 0x7f, 0x80];
    const C7: [u8; 3] = [0xe0, 0xc0, 0x80];
    const C8: [u8; 3] = [0xe0, 0xff, 0x80];

    // Invalid three-byte continuation byte in third byte. Must be 0x80 - 0xbf.
    const C9: [u8; 3] = [0xe0, 0x80, 0x00];
    const C10: [u8; 3] = [0xe0, 0x80, 0x7f];
    const C11: [u8; 3] = [0xe0, 0x80, 0xc0];
    const C12: [u8; 3] = [0xe0, 0x80, 0xff];

    // Invalid four-byte continuation byte in second byte. Must be 0x80 - 0xbf.
    const C13: [u8; 4] = [0xf0, 0x00, 0x80, 0x80];
    const C14: [u8; 4] = [0xf0, 0x7f, 0x80, 0x80];
    const C15: [u8; 4] = [0xf0, 0xc0, 0x80, 0x80];
    const C16: [u8; 4] = [0xf0, 0xff, 0x80, 0x80];

    // Invalid four-byte continuation byte in third byte. Must be 0x80 - 0xbf.
    const C17: [u8; 4] = [0xf0, 0x80, 0x00, 0x80];
    const C18: [u8; 4] = [0xf0, 0x80, 0x7f, 0x80];
    const C19: [u8; 4] = [0xf0, 0x80, 0xc0, 0x80];
    const C20: [u8; 4] = [0xf0, 0x80, 0xff, 0x80];

    // Invalid four-byte continuation byte in fourth byte. Must be 0x80 - 0xbf.
    const C21: [u8; 4] = [0xf0, 0x80, 0x80, 0x00];
    const C22: [u8; 4] = [0xf0, 0x80, 0x80, 0x7f];
    const C23: [u8; 4] = [0xf0, 0x80, 0x80, 0xc0];
    const C24: [u8; 4] = [0xf0, 0x80, 0x80, 0xff];

    // Smallest overlong 2-byte.
    // 110 00000 10 000000 (U+0000)
    const O1: [u8; 2] = [0xc0, 0x80];
    // Largest overlong 2-byte.
    // 110 00001 10 111111 (U+007F)
    const O2: [u8; 2] = [0xc1, 0xbf];
    // Smallest 3-byte overlong.
    // 1110 0000 10 000000 10 000000 (U+0000)
    const O3: [u8; 3] = [0xe0, 0x80, 0x80];
    // Larget 3-byte overlong.
    // 1110 0000 10 011111 10 111111 (U+07FF)
    const O4: [u8; 3] = [0xe0, 0x9f, 0xbf];
    // Smallest 4-byte overlong.
    // 11110 000 10 000000 10 000000 10 000000 (U+0000)
    const O5: [u8; 4] = [0xf0, 0x80, 0x80, 0x80];
    // Largest 4-byte overlong
    // 11110 000 10 00 1111 10 111111 10 111111 (U+FFFF)
    const O6: [u8; 4] = [0xf0, 0x8f, 0xbf, 0xbf];

    // Invalid 1 beyond maximum code point
    const I1: [u8; 4] = [0xf4, 0x90, 0x80, 0x80];

    // Single UTF-16 surrogates
    const I2: [u8; 3] = [0xed, 0xa0, 0x80];
    const I3: [u8; 3] = [0xed, 0xad, 0xbf];
    const I4: [u8; 3] = [0xed, 0xae, 0x80];
    const I5: [u8; 3] = [0xed, 0xaf, 0xbf];
    const I6: [u8; 3] = [0xed, 0xb0, 0x80];
    const I7: [u8; 3] = [0xed, 0xbe, 0x80];
    const I8: [u8; 3] = [0xed, 0xbf, 0xbf];

    const FAIL_FASTER: [u8; 21] = [0xce, 0xba, 0xe1, 0xbd, 0xb9, 0xcf, 0x83, 0xce, 0xbc, 0xce,
                                   0xb5, 0xf4, 0x90, 0x80, 0x80, 0x65, 0x64, 0x69, 0x74, 0x65,
                                   0x64];

    macro_rules! putf8(
        ($n:ident, $a:expr, $b:expr, $pat:pat) => {
            #[test]
            fn $n() {
                let expected = $a;
                let res = parser::validate(&expected);
                if $b {
                    assert!(res.is_ok());
                } else {
                    assert!(res.is_err());
                }
                // println!("res: {:?}", res);
                assert_matches!(res, $pat);
            }
        }
    );

    // Byte is beyond maximum allow code point.
    putf8!(greater_than_max_code_point,
           vec![0xf5],
           false,
           Err(Error(ErrorKind::BeyondMaximumCodePoint, _)));

    // Byte is beyond maximum allow code point.
    putf8!(fail_at_first_invalid_byte,
           FAIL_FASTER,
           false,
           Err(Error(ErrorKind::BeyondMaximumCodePoint, _)));

    // Two byte continuation errors
    putf8!(two_byte_continuation_0x00,
           C1,
           false,
           Err(Error(ErrorKind::TwoByteContinuation, _)));
    putf8!(two_byte_continuation_0x7f,
           C2,
           false,
           Err(Error(ErrorKind::TwoByteContinuation, _)));
    putf8!(two_byte_continuation_0xc0,
           C3,
           false,
           Err(Error(ErrorKind::TwoByteContinuation, _)));
    putf8!(two_byte_continuation_0xff,
           C4,
           false,
           Err(Error(ErrorKind::TwoByteContinuation, _)));

    // Three byte continuation errors, in second byte.
    putf8!(three_byte_continuation_0x00_0x80,
           C5,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(2), _)));
    putf8!(three_byte_continuation_0x7f_0x80,
           C6,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(2), _)));
    putf8!(three_byte_continuation_0xc0_0x80,
           C7,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(2), _)));
    putf8!(three_byte_continuation_0xff_0x80,
           C8,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(2), _)));

    // Three byte continuation errors, in third byte.
    putf8!(three_byte_continuation_0x80_0x00,
           C9,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(3), _)));
    putf8!(three_byte_continuation_0x80_0x7f,
           C10,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(3), _)));
    putf8!(three_byte_continuation_0x80_0xc0,
           C11,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(3), _)));
    putf8!(three_byte_continuation_0x80_0xff,
           C12,
           false,
           Err(Error(ErrorKind::ThreeByteContinuation(3), _)));

    // Four byte continuation errors, in second byte.
    putf8!(four_byte_continuation_0x00_0x80_0x80,
           C13,
           false,
           Err(Error(ErrorKind::FourByteContinuation(2), _)));
    putf8!(four_byte_continuation_0x7f_0x80_0x80,
           C14,
           false,
           Err(Error(ErrorKind::FourByteContinuation(2), _)));
    putf8!(four_byte_continuation_0xc0_0x80_0x80,
           C15,
           false,
           Err(Error(ErrorKind::FourByteContinuation(2), _)));
    putf8!(four_byte_continuation_0xff_0x80_0x80,
           C16,
           false,
           Err(Error(ErrorKind::FourByteContinuation(2), _)));

    // Four byte continuation errors, in third byte.
    putf8!(four_byte_continuation_0x80_0x00_0x80,
           C17,
           false,
           Err(Error(ErrorKind::FourByteContinuation(3), _)));
    putf8!(four_byte_continuation_0x80_0x7f_0x80,
           C18,
           false,
           Err(Error(ErrorKind::FourByteContinuation(3), _)));
    putf8!(four_byte_continuation_0x80_0xc0_0x80,
           C19,
           false,
           Err(Error(ErrorKind::FourByteContinuation(3), _)));
    putf8!(four_byte_continuation_0x80_0xff_0x80,
           C20,
           false,
           Err(Error(ErrorKind::FourByteContinuation(3), _)));

    // Four byte continuation errors, in fourth byte.
    putf8!(four_byte_continuation_0x80_0x80_0x00,
           C21,
           false,
           Err(Error(ErrorKind::FourByteContinuation(4), _)));
    putf8!(four_byte_continuation_0x80_0x80_0x7f,
           C22,
           false,
           Err(Error(ErrorKind::FourByteContinuation(4), _)));
    putf8!(four_byte_continuation_0x80_0x80_0xc0,
           C23,
           false,
           Err(Error(ErrorKind::FourByteContinuation(4), _)));
    putf8!(four_byte_continuation_0x80_0x80_0xff,
           C24,
           false,
           Err(Error(ErrorKind::FourByteContinuation(4), _)));

    // Two byte overlong errors.
    putf8!(smallest_two_byte_overlong,
           O1,
           false,
           Err(Error(ErrorKind::TwoByteOverlong, _)));
    putf8!(largest_two_byte_overlong,
           O2,
           false,
           Err(Error(ErrorKind::TwoByteOverlong, _)));

    // Three byte overlong errors.
    putf8!(smallest_three_byte_overlong,
           O3,
           false,
           Err(Error(ErrorKind::ThreeByteOverlong, _)));
    putf8!(largest_three_byte_overlong,
           O4,
           false,
           Err(Error(ErrorKind::ThreeByteOverlong, _)));

    // Four byte overlong errors.
    putf8!(smallest_four_byte_overlong,
           O5,
           false,
           Err(Error(ErrorKind::FourByteOverlong, _)));
    putf8!(largest_four_byte_overlong,
           O6,
           false,
           Err(Error(ErrorKind::FourByteOverlong, _)));

    // Invalid first byte.
    putf8!(invalid_first_byte,
           vec![0x80],
           false,
           Err(Error(ErrorKind::InvalidFirstByte(0x80), _)));

    // 1 greater than maximum code point
    putf8!(one_larger_than_maximum_code_point,
           I1,
           false,
           Err(Error(ErrorKind::BeyondMaximumCodePoint, _)));

    // UTF-16 single surrogates
    putf8!(utf16_surrogate_1,
           I2,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_2,
           I3,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_3,
           I4,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_4,
           I5,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_5,
           I6,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_6,
           I7,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));
    putf8!(utf16_surrogate_7,
           I8,
           false,
           Err(Error(ErrorKind::UTF16Surrogate, _)));

    // Empty buffer.
    putf8!(empty, vec![], true, Ok(Success::Complete(0)));

    // Incomplete input tests.
    putf8!(incomplete_two_byte,
           vec![0xc2],
           true,
           Ok(Success::Incomplete(1, 0)));
    putf8!(incomplete_two_byte_after_one_byte,
           vec![0x24, 0xc2],
           true,
           Ok(Success::Incomplete(1, 1)));
    putf8!(incomplete_two_after_two_byte,
           vec![0xc2, 0xa2, 0xc2],
           true,
           Ok(Success::Incomplete(1, 2)));

    // Valid input tests.
    putf8!(smallest_one_byte_code_point,
           V1,
           true,
           Ok(Success::Complete(1)));
    putf8!(valid_one_byte_code_point,
           V2,
           true,
           Ok(Success::Complete(1)));
    putf8!(largest_one_byte_code_point,
           V3,
           true,
           Ok(Success::Complete(1)));
    putf8!(smallest_two_byte_code_point,
           V4,
           true,
           Ok(Success::Complete(2)));
    putf8!(valid_two_byte_code_point,
           V5,
           true,
           Ok(Success::Complete(2)));
    putf8!(largest_two_byte_code_point,
           V6,
           true,
           Ok(Success::Complete(2)));
    putf8!(smallest_three_byte_code_point,
           V7,
           true,
           Ok(Success::Complete(3)));
    putf8!(valid_three_byte_code_point,
           V8,
           true,
           Ok(Success::Complete(3)));
    putf8!(largest_three_byte_code_point,
           V9,
           true,
           Ok(Success::Complete(3)));
    putf8!(smallest_four_byte_code_point,
           V10,
           true,
           Ok(Success::Complete(4)));
    putf8!(valid_four_byte_code_point,
           V11,
           true,
           Ok(Success::Complete(4)));
    putf8!(largest_four_byte_code_point,
           V12,
           true,
           Ok(Success::Complete(4)));
}