Crate libyaml_safer
source ·Expand description
§libyaml-safer
This library is a fork of unsafe-libyaml translated to safe and idiomatic Rust.
unsafe-libyaml is libyaml translated from C to unsafe Rust with the assistance of c2rust.
[dependencies]
libyaml-safer = "0.1"
Compiler support: requires rustc 1.70
§Notes
This library uses the same test suite as unsafe-libyaml, which is also the “official” test suite for libyaml. The library was ported line by line, function by function, from unsafe-libyaml, with the aim of precisely matching its behavior, including performance and allocation patterns. Any observable difference in behavior, outside of API differences due to Rust conventions, is considered a bug.
One notable exception to the above is that this library uses the Rust standard
library in place of custom routines where possible. For example, most UTF-8 and
UTF-16 encoding and decoding is handled by the standard library, and
input/output callbacks are replaced with the applicable std::io::*
traits. Due
to the use of std::io
, this library cannot currently be no_std
.
Memory allocation patterns are generally preserved, except that standard library containers may overallocate buffers using different heuristics.
In places where libyaml routines are replaced by the standard library, certain errors may be reported with reduced fidelity compared with libyaml (e.g., error messages may look slightly different), but the same inputs should generate the same general errors.
§Compatibility and interoperability
While this library matches the behavior of libyaml, it is not intended as a
drop-in replacement. The shape of the API is idiomatic Rust, and while it is
possible to emulate the C API using this library, supporting this use case is
not a priority. Use unsafe-libyaml
if that is what you need.
§Performance
Performance is largely on par with unsafe-libyaml
. No significant effort has
been put into optimizing this library, beyond just choosing the most
straightforward ways to reasonably port concepts from the C-like code.
See
benches/bench.rs
for a very simple benchmark dealing with a very large (~700 KiB) YAML document.
On my machine (Ryzen 9 3950X) the parser from this library is slightly slower
and the emitter is slightly faster, but both within about ~1ms of their unsafe
counterparts. Run cargo bench
to test on your machine.
If there is demand, there are clear paths forward to optimize the parser. For example, due to it being ported directly from unsafe C-like code doing pointer arithmetic, it performs a completely unreasonable number of bounds checks for each input byte.
§License
MIT license, same as unsafe-libyaml and libyaml.
Structs§
- This structure holds aliases data.
- The document structure.
- The emitter structure.
- The event structure.
- The pointer position.
- The node structure.
- An element of a mapping node.
- The parser structure.
- Given an input stream of bytes, produce a stream of
Token
s. - This structure holds information about a potential simple key.
- The tag directive data.
- The token structure.
- The version directive data.
Enums§
- Line break type.
- The emitter states.
- The stream encoding.
- Mapping styles.
- Node types.
- The states of the parser.
- Scalar styles.
- Sequence styles.
Constants§
- The tag
!!bool
with the values:true
andfalse
. - The default mapping tag is
!!map
. - The default scalar tag is
!!str
. - The default sequence tag is
!!seq
. - The tag
!!float
for float values. - The tag
!!int
for integer values. - The tag
!!map
is used to denote mapping. - The tag
!!null
with the only possible value:null
. - The tag
!!seq
is used to denote sequences. - The tag
!!str
for string values. - The tag
!!timestamp
for date and time values.
Type Aliases§
- An element of a sequence node.