Crate mangling

This crate provides for converting arbitrary byte streams into valid C-language identifiers ("mangled names") and back again.

Rationale

The functionality of this crate was hoisted out of a compiler that needed to translate identifiers for Java symbols (e.g. method names and signatures) into symbols valid for the generated assembly language. Although the mangling process can encode any stream of bytes into a (longer) string of ASCII characters, and then convert the output back again, it is not intended to provide general encoding/decoding facilities. Instead, it is meant to provide an easy, reliable way for compiler writers to generate human-recognizable identifiers without having to invent their own mangling scheme.

Example

let (before, after) = ("java/lang/Object", "_4java01_2f4lang01_2f6Object");
assert_eq!(after, mangle(before.as_bytes()));
assert_eq!(before.as_bytes(), demangle(after).unwrap().as_slice());

Requirements

1. Totality (every byte stream can be encoded into a unique mangled name)
2. Injectivity (each mangled name can be decoded to a unique byte stream)

Goals

1. Correctness (the implementation matches its documented behavior)
2. Consistency (the implementation behaves in a predictable manner)
3. Readability (mangled names are visibly related to input streams)
4. Compactness (mangled names are comparable in length to inputs)
5. Performance (processing is computationally efficient in time and space)

Modules

clib	Provides C-compatible interfaces to mangle and demangle functions.

Functions

demangle	Reverses the transformation performed by mangle.
mangle	Takes an iterator over bytes and produces a String whose contents obey the rules for an identifier in the C language.