Crate lstring

Source
Expand description

Key String: Optimized for map keys.

§Examples

String creation

// Explicit (static)
let literal = <KString>::from_static("literal");
// Using macro (static)
let literal: KString = kstring!("literal");
// Multiple literals will be concatenated
const CONST_STRING: KString = kstring!("const", "ant");
// Macro also accepts constants
const HELLO_WORLD: &str = "Hello world!";
static STATIC_STRING: KString = kstring!(HELLO_WORLD);

// Explicit (inline)
let inline = <KString>::try_inline("stack").unwrap();
let inline = <KString>::from_ref("stack");

// Formatted
let formatted: KString = kformat!("Hello {literal} and {inline}");

§Background

Considerations:

  • Large maps
  • Most keys live and drop without being used in any other way
  • Most keys are relatively small (single to double digit bytes)
  • Keys are immutable
  • Allow zero-cost abstractions between structs and maps (e.g. no allocating when dealing with struct field names)

Ramifications:

  • Inline small strings rather than going to the heap.
  • Preserve &'static str across strings (KString), references (KStringRef), and lifetime abstractions (KStringCow) to avoid allocating for struct field names.
  • Use Box<str> rather than String to use less memory.

Significant changes:

  • Because From<&'static str> is unsound it changed to From<&str>. To instantiate from static str use KString::from_static instead of From::from (or kstring macro).
  • Added default generic to types KStringBase and KStringCowBase which renamed to KString and KStringCow. Corresponding type aliases is removed. To instantiate types with default backend wrap it with angle brackets (KString::from_ref("abc") => <KString>::from_ref("abc")).
  • Added KStringWriter and kformat macros. Also added FromIterator trait impls.
  • Added from_utf8 and from_utf16 functions.

§Feature Flags

  • std (enabled by default) — Allow use of std
  • arc — O(1) clone support
  • max_inline — Inline (stack) strings use the full width of KStrings
  • unsafe (enabled by default) — Allow unsafe code

Modules§

backend

Macros§

kformat
A macro for formatting arguments into a KString.
kstring
Creates a KString from a static string literal.

Structs§

KString
A UTF-8 encoded, immutable string.
KStringCow
A reference to a UTF-8 encoded, immutable string.
KStringRef
A reference to a UTF-8 encoded, immutable string.
StackString
Fixed-size stack-allocated string

Enums§

KStringWriter
A writer that can append formatted text to either an inline StackString or a heap-allocated String.