Header lexy/dsl/byte.hpp

Rules that match one or more bytes.

Token rule lexy::dsl::byte and lexy::dsl::bytes

namespace lexy::dsl
    template <std::size_t N>
    constexpr token-rule auto bytes;

    constexpr token-rule auto byte = bytes<1>;

bytes is a token rule that matches N arbitrary bytes.


The input encoding is lexy::byte_encoding.


Matches and consumes N bytes.


lexy::expected_char_class ("byte"): if EOF was encountered early; at the position of the last byte it could consume. The rule then fails.

Parse tree

Single token node with the lexy::predefined_token_kind lexy::any_token_kind.

Combining lexy::dsl::capture with bytes does not do any endianness conversion.

Branch rule lexy::dsl::padding_bytes

namespace lexy::dsl
    template <std::size_t N, unsigned char Value = 0>
    constexpr branch-rule auto padding_bytes;

padding_bytes is a branch rule that matches N padding bytes.

Padding bytes are bytes whose value doesn’t matter: they’re only expected to have a certain value, but it’s okay, if they don’t.

(Branch) parsing

(Branch) parses lexy::dsl::bytes. If that succeeds, the branch is taken. It then checks if the N consumed bytes have the given Value.

  • All errors raised by parsing bytes, if not branch parsing. The rule then fails.

  • lexy::expected_literal if a byte did not have Value. The rule then recovers.

Branch parsing will not backtrack if the padding bytes do not have the given Value.

Binary integer branch rules

namespace lexy
    struct mismatched_byte_count {};

namespace lexy::dsl
    struct binary-integer-dsl_ // models branch-rule
        constexpr branch-rule operator()(token-rule bytes) const;

    constexpr binary-integer-dsl bint8;

    constexpr binary-integer-dsl bint16;
    constexpr binary-integer-dsl little_bint16;
    constexpr binary-integer-dsl big_bint16;

    constexpr binary-integer-dsl bint32;
    constexpr binary-integer-dsl little_bint32;
    constexpr binary-integer-dsl big_bint32;

    constexpr binary-integer-dsl bint64;
    constexpr binary-integer-dsl little_bint64;
    constexpr binary-integer-dsl big_bint64;

[little/big_]bintN is a branch rule that converts N / 8 bytes into an N bit integer.

Each rule has the associated bit width N and endianness: for the prefixed ones it is little/big endian, for the unprefixed ones it is the native endianness. The endianness doesn’t matter for bint8.

They delegate to the associated bytes rule, which can be specified using the function call operator. If none has been specified, they default to lexy::dsl::bytes.

(Branch) parsing

(Branch) parses bytes. If that succeeds, the branch is taken. It then checks that N / 8 bytes have been consumed.

  • All errors raised by parsing bytes. The rule then fails.

  • lexy::mismatched_byte_count: if bytes succeeded but did not consume N / 8 bytes; its range covers everything consumed by bytes. The rule then fails.


A std::uint_leastN_t which results in reading N / 8 bytes in the specified endianness. This conversion can never fail.

See also