mod error;
mod table;
pub use {
error::{MarspeakError, TableError},
table::Table,
};
pub struct Marspeak<'a> {
seed: u64,
threshold: u64,
table: &'a Table,
}
impl<'a> Marspeak<'a> {
pub fn encode(&self, text: &str) -> String {
let mut result = String::with_capacity(text.len());
let mut ordinal = 0;
for ch in text.chars() {
let cands = self.table.candidates(ch);
let cand = pick(cands, ch, self.seed, ordinal, self.threshold);
if cands.is_some() {
ordinal += 1;
}
result.push(cand.unwrap_or(ch));
}
result
}
pub fn decode(&self, text: &str) -> String {
text.chars()
.map(|ch| self.table.original(ch).unwrap_or(ch))
.collect()
}
}
pub struct Builder<'a> {
seed: u64,
intensity: f32,
table: &'a Table,
}
impl Builder<'static> {
pub fn new() -> Self {
Self {
seed: Default::default(),
intensity: 1.0,
table: Table::builtin(),
}
}
}
impl<'a> Builder<'a> {
pub fn seed(self, seed: u64) -> Self {
Self {
seed,
intensity: self.intensity,
table: self.table,
}
}
pub fn intensity(self, intensity: f32) -> Self {
Self {
seed: self.seed,
intensity,
table: self.table,
}
}
pub fn table<'b>(self, table: &'b Table) -> Builder<'b> {
Builder {
seed: self.seed,
intensity: self.intensity,
table,
}
}
pub fn build(self) -> Result<Marspeak<'a>, MarspeakError> {
if !(0.0..=1.0).contains(&self.intensity) {
return Err(MarspeakError::InvalidIntensity(self.intensity));
}
Ok(Marspeak {
seed: self.seed,
threshold: (self.intensity * 100.0).round() as u64,
table: self.table,
})
}
}
impl Default for Builder<'static> {
fn default() -> Self {
Self::new()
}
}
fn pick(cands: Option<&[char]>, ch: char, seed: u64, ordinal: u64, threshold: u64) -> Option<char> {
let cands = cands?;
if threshold == 0 {
return None;
}
let hash = mix(seed, ordinal, ch);
if hash % 100 >= threshold {
return None;
}
let idx = (hash ^ (hash >> 32)) % cands.len() as u64;
Some(cands[idx as usize])
}
fn mix(seed: u64, ordinal: u64, ch: char) -> u64 {
let seed_bytes = seed.to_le_bytes();
let ordinal_bytes = ordinal.to_le_bytes();
let ch_bytes = (ch as u32).to_le_bytes();
let mut bytes = [0u8; 20];
bytes[..8].copy_from_slice(&seed_bytes);
bytes[8..16].copy_from_slice(&ordinal_bytes);
bytes[16..20].copy_from_slice(&ch_bytes);
fnv1a(&bytes)
}
fn fnv1a(bytes: &[u8]) -> u64 {
let offset_basis = 0xcbf29ce484222325_u64;
let prime = 0x100000001b3_u64;
let mut hash_value = offset_basis;
for &byte in bytes {
hash_value ^= u64::from(byte);
hash_value = hash_value.wrapping_mul(prime);
}
hash_value
}
#[cfg(test)]
mod tests {
use super::{Builder, Marspeak, Table, fnv1a, mix, pick};
const TEXT: &str = "我昨天去了那家新开的面馆,碗里的牛肉炖得很烂,汤头也够鲜。\n\
老板说他从一九九八年就开始做这行了,中间搬过三次店面。\
Emoji 🎉 与 ASCII abc 混排。";
fn encoder(seed: u64, intensity: f32) -> Marspeak<'static> {
Builder::new()
.seed(seed)
.intensity(intensity)
.build()
.expect("intensity 在合法范围内")
}
#[test]
fn fnv1a_matches_reference_vectors() {
assert_eq!(fnv1a(b""), 0xcbf29ce484222325);
assert_eq!(fnv1a(b"a"), 0xaf63dc4c8601ec8c);
assert_eq!(fnv1a(b"foobar"), 0x85944171f73967e8);
}
#[test]
fn mix_matches_golden_values() {
let cases = [
((0, 0, '我'), 0x9f17257c2340932au64, 66u64),
((0, 1, '我'), 0x4806cde8b33ed8af, 47),
((0, 2, '我'), 0x123ac0ba513db460, 12),
((1, 0, '我'), 0xda39d5aa93d498cf, 51),
((0, 0, 'a'), 0x508acbd48aee9644, 32),
((42, 7, '天'), 0xf250f3e4bc8bc18e, 10),
];
for ((seed, ordinal, ch), want_hash, want_pct) in cases {
let hash = mix(seed, ordinal, ch);
assert_eq!(
hash, want_hash,
"mix({seed}, {ordinal}, {ch:?}) 应为 0x{want_hash:016x},实际 0x{hash:016x}"
);
assert_eq!(
hash % 100,
want_pct,
"mix({seed}, {ordinal}, {ch:?}) 的 %100 用于 intensity 判定"
);
}
}
#[test]
fn mix_is_deterministic() {
for ordinal in 0..50u64 {
assert_eq!(mix(42, ordinal, '我'), mix(42, ordinal, '我'));
}
assert_ne!(mix(0, 0, '我'), mix(1, 0, '我'));
assert_ne!(mix(0, 0, '我'), mix(0, 1, '我'));
}
#[test]
fn mix_is_well_distributed() {
let mut buckets = [0u32; 100];
for ordinal in 0..1000u64 {
buckets[(mix(0, ordinal, '我') % 100) as usize] += 1;
}
let covered = buckets.iter().filter(|&&c| c > 0).count();
assert_eq!(
covered, 100,
"1000 次采样应覆盖全部 100 个桶,实际只覆盖 {covered} 个"
);
}
#[test]
fn pick_returns_none_when_char_is_absent_from_table() {
assert_eq!(pick(None, '我', 0, 0, 100), None);
}
#[test]
fn pick_returns_none_at_zero_intensity() {
let cands = ['莪', '沃'];
assert_eq!(pick(Some(&cands), '我', 0, 0, 0), None);
assert_eq!(pick(Some(&cands), '我', 42, 7, 0), None);
}
#[test]
fn pick_threshold_boundary() {
let cands = ['A', 'B', 'C'];
assert_eq!(
pick(Some(&cands), '我', 0, 0, 66),
None,
"hash % 100 == 66,threshold 66 时应不替换(66 不小于 66)"
);
assert_eq!(
pick(Some(&cands), '我', 0, 0, 67),
Some('B'),
"hash % 100 == 66,threshold 67 时应替换,且下标为 1"
);
}
#[test]
fn pick_replacement_ratio_matches_threshold() {
let cands = ['A', 'B', 'C'];
let total = 10_000u64;
let cases = [(0u64, 0u64), (20, 2000), (60, 6000), (100, 10000)];
for (threshold, want) in cases {
let replaced = (0..total)
.filter(|&ordinal| pick(Some(&cands), '我', 0, ordinal, threshold).is_some())
.count() as u64;
let allowed = (want / 20).max(50); assert!(
replaced.abs_diff(want) <= allowed,
"threshold {threshold} 期望替换约 {want} 个,实际 {replaced} 个"
);
}
}
#[test]
fn pick_always_returns_a_candidate_and_covers_them_all() {
let cands = ['A', 'B', 'C'];
let mut seen = [false; 3];
for ordinal in 0..1000u64 {
let got = pick(Some(&cands), '我', 0, ordinal, 100).expect("threshold 100 必然替换");
let pos = cands
.iter()
.position(|&c| c == got)
.unwrap_or_else(|| panic!("返回了不在候选里的字符 {got:?}"));
seen[pos] = true;
}
assert!(
seen.iter().all(|&s| s),
"三个候选都应被选中,实际选中情况 {seen:?}"
);
}
#[test]
fn pick_is_deterministic() {
let cands = ['A', 'B', 'C'];
for ordinal in 0..100u64 {
assert_eq!(
pick(Some(&cands), '我', 42, ordinal, 60),
pick(Some(&cands), '我', 42, ordinal, 60)
);
}
}
#[test]
fn build_rejects_intensity_out_of_range() {
for intensity in [-0.1, 1.1, 2.0, f32::INFINITY, f32::NEG_INFINITY] {
assert!(
Builder::new().intensity(intensity).build().is_err(),
"intensity {intensity} 超出 [0.0, 1.0],必须报错"
);
}
assert!(
Builder::new().intensity(f32::NAN).build().is_err(),
"NaN 必须被拒"
);
}
#[test]
fn build_accepts_boundary_intensities() {
assert!(Builder::new().intensity(0.0).build().is_ok());
assert!(Builder::new().intensity(1.0).build().is_ok());
}
#[test]
fn zero_intensity_is_an_identity_transform() {
assert_eq!(
encoder(0, 0.0).encode(TEXT),
TEXT,
"intensity = 0.0 时 encode 必须原样返回"
);
}
#[test]
fn full_intensity_replaces_every_mappable_char() {
let table = Table::builtin();
let encoded = encoder(0, 1.0).encode(TEXT);
let mappable = TEXT
.chars()
.filter(|&ch| table.candidates(ch).is_some())
.count();
let changed = TEXT
.chars()
.zip(encoded.chars())
.filter(|(a, b)| a != b)
.count();
assert_eq!(
changed, mappable,
"intensity = 1.0 时,表里有映射的 {mappable} 个字符应全部被替换,实际替换了 {changed} 个"
);
}
#[test]
fn encode_preserves_char_count() {
for intensity in [0.0, 0.33, 0.7, 1.0] {
let encoded = encoder(7, intensity).encode(TEXT);
assert_eq!(
encoded.chars().count(),
TEXT.chars().count(),
"intensity {intensity}:单字符替换不应改变字符数"
);
}
}
#[test]
fn round_trip_is_identity() {
let cases = [
(0u64, 0.0f32),
(0, 0.3),
(0, 1.0),
(42, 0.5),
(u64::MAX, 1.0),
(7, 0.87),
];
for (seed, intensity) in cases {
let m = encoder(seed, intensity);
let encoded = m.encode(TEXT);
assert_eq!(
m.decode(&encoded),
TEXT,
"seed={seed} intensity={intensity} 时 decode(encode(s)) 必须等于 s"
);
}
}
#[test]
fn empty_string_round_trips() {
let m = encoder(0, 1.0);
assert_eq!(m.encode(""), "");
assert_eq!(m.decode(""), "");
}
#[test]
fn chars_without_mapping_pass_through() {
let m = encoder(0, 1.0);
assert_eq!(m.encode("ASCII 123 !@#"), "ASCII 123 !@#");
assert_eq!(m.encode("的"), "的");
assert_eq!(m.encode("🎉"), "🎉");
}
#[test]
fn decode_ignores_seed_and_intensity() {
let low = encoder(0, 0.0);
let high = encoder(u64::MAX, 1.0);
assert_eq!(low.decode("莪愛恏"), "我爱好");
assert_eq!(
high.decode("莪愛恏"),
"我爱好",
"decode 不依赖 seed 与 intensity——若哪天需要,说明设计出了问题"
);
}
#[test]
fn decode_restores_arbitrary_martian_text() {
assert_eq!(encoder(0, 0.0).decode("莪們"), "我们");
}
#[test]
fn seed_diversifies_output() {
let mut outs: Vec<String> = (0..8u64)
.map(|seed| encoder(seed, 1.0).encode(TEXT))
.collect();
outs.sort();
outs.dedup();
assert!(
outs.len() >= 4,
"8 个不同 seed 应产生至少 4 种不同输出,实际只有 {} 种",
outs.len()
);
}
#[test]
fn encode_is_reproducible() {
assert_eq!(
encoder(42, 0.6).encode(TEXT),
encoder(42, 0.6).encode(TEXT),
"同参数必须得到完全相同的输出"
);
}
#[test]
fn custom_table_overrides_builtin() {
let table = Table::parse("我\t莪,沃\n").unwrap();
let m = Builder::new().table(&table).intensity(1.0).build().unwrap();
assert_eq!(m.encode("爱"), "爱", "自定义表生效时内置表不应再参与");
let out = m.encode("我");
assert!(
out == "莪" || out == "沃",
"替换结果必须来自自定义表,实际 {out:?}"
);
assert_eq!(m.decode(&out), "我");
}
#[test]
fn ordinal_starts_at_zero_for_the_first_mapped_char() {
let cands = Table::builtin().candidates('你');
let at_zero =
pick(cands, '你', 0, 0, 100).expect("内置表里应有「你」,且 intensity = 1.0 必然替换");
assert_eq!(
encoder(0, 1.0).encode("你"),
at_zero.to_string(),
"第一个有映射的字符应使用 ordinal = 0"
);
}
#[test]
fn ordinal_only_advances_on_mapped_chars() {
let m = encoder(7, 1.0);
let packed = m.encode("你你你你你你你你");
let spaced = m.encode("你 你 你 你 你 你 你 你");
let stripped: String = spaced.chars().filter(|&ch| ch != ' ').collect();
assert_eq!(
packed, stripped,
"插入空格不应改变其他字符的替换结果:\n紧凑 {packed:?}\n带空格 {stripped:?}"
);
}
}