WEP: Redesign String and List APIs

Status

Draft (partially superseded by WEP-2026-05-16: String API checked/unchecked discipline, which overrides the rows for as_bytes, String::concat, get_byte/set_byte, and truncate_bytes, and introduces _unchecked siblings for truncate/insert/insert_str/remove.)

Context

Wado's String and List<T> are designed to feel familiar to Rust developers, but many commonly used methods from Rust's String/&str and Vec<T>/&[T] are missing or named differently. This proposal catalogs the gaps and adds the missing pieces.

Wado intentionally omits Rust concepts tied to ownership and lifetimes (as_str(), as_mut_slice(), into_boxed_str(), Cow, etc.). Everything else should be available.

Decision

List vs Rust's Vec<T> / &[T]

Mapping Table

"—" means intentionally excluded (see rationale below the table).

Also available via existing Wado features:

New List Methods — Signatures

impl<T> List<T> {
    pub fn first(&self) -> Option<T>;
    pub fn push(&mut self, value: T);                       // rename from append
    pub fn insert(&mut self, index: i32, value: T);
    pub fn remove(&mut self, index: i32) -> T;
    pub fn swap(&mut self, a: i32, b: i32);
    pub fn clear(&mut self);
    pub fn capacity(&self) -> i32;
    pub fn reserve(&mut self, additional: i32);
    pub fn shrink_to_fit(&mut self);
    pub fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I);
    pub fn reverse(&mut self);
    pub fn repeat(&self, n: i32) -> List<T>;
    pub fn windows(&self, size: i32) -> WindowsIter<T>;
    pub fn chunks(&self, size: i32) -> ChunksIter<T>;
}

impl<T: Eq> List<T> {
    pub fn contains(&self, value: &T) -> bool;
}

impl<T: Display> List<T> {
    pub fn join(&self, separator: String) -> String;
}

String vs Rust's String / &str

Mapping Table

Also available via existing Wado features:

Pattern Argument Design

Rust's str::contains, find, split, etc. accept a Pattern trait that works with &str, char, and closures. Wado simplifies this:

• String patterns: contains(pat: String), find(pat: String), split(sep: String) — substring matching.
• Char patterns: contains_char(ch: char), find_char(pred: fn(&char) -> bool) — character-level matching.
• starts_with / ends_with: Accept String. For single char, use s.starts_with(String::from('x')).

This avoids the complexity of a Pattern trait while covering the common cases.

String Byte-Index Convention

Following Rust, String methods that accept or return indices use byte indices, not char indices:

• find(pat) → Option<i32> (byte index)
• insert(i, ch) — i is a byte index
• remove(i) — i is a byte index
• truncate(n) — n is byte count

This is consistent with len() returning byte length and matches Rust's design. Methods panic if the index is not on a char boundary.

New String Methods — Signatures

impl String {
    pub fn push(&mut self, ch: char);                        // rename from append_char
    pub fn push_str(&mut self, s: String);                   // rename from append
    pub fn pop(&mut self) -> Option<char>;
    pub fn insert(&mut self, byte_index: i32, ch: char);
    pub fn insert_str(&mut self, byte_index: i32, s: String);
    pub fn remove(&mut self, byte_index: i32) -> char;
    pub fn truncate(&mut self, byte_len: i32);               // rename from truncate_bytes
    pub fn clear(&mut self);
    pub fn capacity(&self) -> i32;
    pub fn reserve(&mut self, additional: i32);
    pub fn shrink_to_fit(&mut self);
    pub fn as_bytes(&self) -> List<u8>;
    pub fn contains(&self, pat: String) -> bool;
    pub fn starts_with(&self, pat: String) -> bool;
    pub fn ends_with(&self, pat: String) -> bool;
    pub fn find(&self, pat: String) -> Option<i32>;          // byte index
    pub fn rfind(&self, pat: String) -> Option<i32>;         // byte index
    pub fn contains_char(&self, ch: char) -> bool;
    pub fn find_char(&self, pred: fn(&char) -> bool) -> Option<i32>;  // byte index
    pub fn split(&self, sep: String) -> StrSplitIter;           // Iterator<Item = String>
    pub fn splitn(&self, n: i32, sep: String) -> StrSplitNIter; // Iterator<Item = String>
    pub fn split_whitespace(&self) -> StrSplitWhitespaceIter;  // Iterator<Item = String>
    pub fn lines(&self) -> StrLinesIter;                       // Iterator<Item = String>
    pub fn replace(&self, from: String, to: String) -> String;
    pub fn replacen(&self, from: String, to: String, count: i32) -> String;
    pub fn to_lowercase(&self) -> String;
    pub fn to_uppercase(&self) -> String;
    pub fn repeat(&self, n: i32) -> String;
    pub fn char_indices(&self) -> StrCharIndicesIter;        // Iterator<Item = [i32, char]>
}

Renames and Deprecations

Per WEP-2026-05-16, old names are removed outright (no deprecation period) since Wado has no external users yet.

String::truncate_chars(n) is kept as-is — it has no Rust equivalent (Rust has no char-count truncation) and the _chars suffix makes the distinction clear.

Existing Wado-Specific Methods (Kept)

These have no direct Rust counterpart but are useful in Wado:

Consequences

Positive

1. Rust familiarity: Developers can transfer Rust knowledge directly.
2. Completeness: Common operations (contains, split, join, find, replace) no longer require manual loops.
3. Consistent naming: push = one element, push_str = string, extend = iterable — same vocabulary as Rust.

Negative

1. Breaking rename: append → push / push_str requires migration (mitigated by deprecation period).
2. Byte-index convention for String: Char-boundary panics can surprise users unfamiliar with UTF-8. Documented clearly.

Implementation Priority

1. High (most requested):
   • push / push_str (rename), clear, contains, starts_with, ends_with
   • String::split, String::replace, String::find
   • List::join, List::contains
2. Medium:
   • insert, remove, reverse, extend
   • String::lines, String::split_whitespace, String::repeat
   • List::first, List::repeat
3. Lower:
   • swap, windows, chunks
   • String::rfind, String::splitn, String::replacen, String::char_indices
   • String::to_lowercase, String::to_uppercase

Implementation TODOs

• [ ] Phase 1: Add new methods (high priority)
• [ ] Phase 1: Add new methods (medium priority)
• [ ] Phase 1: Add new methods (lower priority)
• [ ] Phase 2: Deprecation warnings for old names
• [ ] Phase 3: Remove deprecated aliases
• [ ] Update docs/cheatsheet.md
• [ ] Update docs/stdlib-core-prelude.md (auto-generated)
• [ ] Update docs/spec.md