feat(lib): add forbid_unsafe feature to disable unsafe code

book/src/SUMMARY.md

@@ -11,6 +11,7 @@
 + [Using callbacks](./callbacks.md)
 + [Common regular expressions](./common-regex.md)
 + [Debugging](./debugging.md)
++ [Unsafe Code](./unsafe.md)
 + [Examples](./examples.md)
   + [Brainfuck interpreter](./examples/brainfuck.md)
   + [JSON parser](./examples/json.md)

book/src/unsafe.md

@@ -0,0 +1,32 @@
+# Unsafe Code
+
+By default, **Logos** uses unsafe code to avoid unnecessary bounds checks while
+accessing slices of the input `Source`.
+
+This unsafe code also exists in the code generated by the `Logos` derive macro,
+which generates a deterministic finite automata (DFA). Reasoning about the correctness
+of this generated code can be difficult - if the derivation of the DFA in `Logos`
+is correct, then this generated code will be correct and any mistakes in implementation
+would be caught given sufficient fuzz testing.
+
+Use of unsafe code is the default as this typically provides the fastest parser.
+
+## Disabling Unsafe Code
+
+However, for applications accepting untrusted input in a trusted context, this
+may not be a sufficient correctness justification.
+
+For those applications which cannot tolerate unsafe code, the feature `forbid-unsafe`
+may be enabled. This replaces unchecked accesses in the `Logos` crate with safe,
+checked alternatives which will panic on out-of-bounds access rather than cause
+undefined behavior. Additionally, code generated by the macro will not use the
+unsafe keyword, so generated code may be used in a crates using the 
+`#![forbid(unsafe_code)]` attribute.
+
+Disabling unsafe code will generally result in a slower parser overall, though rarely
+may end up slightly faster.
+
+There are too many variables to consider between compiler optimizations, the specific
+grammar being parsed, and the target processor to make definitive statements about
+performance of safe-only code. The automated benchmarks of this crate shows around a
+10% slowdown in safe-only code as of the time of this writing.

src/source.rs

@@ -12,6 +12,11 @@ use core::ops::{Deref, Range};
 /// Most notably this is implemented for `&str`. It is unlikely you will
 /// ever want to use this Trait yourself, unless implementing a new `Source`
 /// the `Lexer` can use.
+/// 
+/// SAFETY: Unless the unsafe functions of this trait are disabled with the `forbid_unsafe`
+/// feature, the correctness of the unsafe functions of this trait depend on the correct
+/// implementation of the `len` and `find_boundary` functions so generated code does not request
+/// out-of-bounds access.
 #[allow(clippy::len_without_is_empty)]
 pub trait Source {
     /// A type this `Source` can be sliced into.