///|
/// Internal byte-level decoding layer for the AXML parser (not exported).
///
/// Error mapping contract (mirrored by whitebox tests):
/// - `UnexpectedEof(offset)`:以 `offset` 开头的读取项被截断(输入结束或超出
///   所在 chunk 的边界);
/// - `BadStringPool(offset, detail)`:字符串池结构或字符串内容在 `offset` 处
///   非法(偏移表越界、缺 NUL 终止符、非法 UTF-8/UTF-16 序列等);
/// - `UnsupportedEncoding(detail)`:字符串池 flags 指示既非 UTF-8 也非
///   UTF-16 的编码(未知标志位)。
///
/// 所有偏移均为输入缓冲区中的绝对字节偏移。

///|
/// Little-endian 定宽读取器。`limit` 是可读区域的开区间上界(输入末尾或
/// 所在 chunk 的末尾),任何越界读取都以 `UnexpectedEof(offset)` 报告
/// 被截断项的起始偏移。
fn read_u8(data : Bytes, off : Int32, limit : Int32) -> Int32 raise AxmlError {
  if off < 0 || off + 1 > limit || off + 1 > data.length() {
    raise UnexpectedEof(off)
  }
  data.at(off).to_int()
}

///|
fn read_u16(data : Bytes, off : Int32, limit : Int32) -> Int32 raise AxmlError {
  if off < 0 || off + 2 > limit || off + 2 > data.length() {
    raise UnexpectedEof(off)
  }
  let b0 = data.at(off).to_int()
  let b1 = data.at(off + 1).to_int()
  b0 | (b1 << 8)
}

///|
fn read_u32(data : Bytes, off : Int32, limit : Int32) -> Int32 raise AxmlError {
  if off < 0 || off + 4 > limit || off + 4 > data.length() {
    raise UnexpectedEof(off)
  }
  let b0 = data.at(off).to_int()
  let b1 = data.at(off + 1).to_int()
  let b2 = data.at(off + 2).to_int()
  let b3 = data.at(off + 3).to_int()
  b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)
}

///|
fn read_u32u(
  data : Bytes,
  off : Int32,
  limit : Int32,
) -> UInt32 raise AxmlError {
  if off < 0 || off + 4 > limit || off + 4 > data.length() {
    raise UnexpectedEof(off)
  }
  data.at(off).to_uint() |
  (data.at(off + 1).to_uint() << 8) |
  (data.at(off + 2).to_uint() << 16) |
  (data.at(off + 3).to_uint() << 24)
}

///|
/// 字符串池长度前缀(8 位形式):高位置位时由两字节组成。
/// 返回 (长度值, 后续位置)。
fn read_len8(
  data : Bytes,
  pos : Int32,
  limit : Int32,
) -> (Int32, Int32) raise AxmlError {
  let b = read_u8(data, pos, limit)
  if (b & 0x80) == 0 {
    return (b, pos + 1)
  }
  let b2 = read_u8(data, pos + 1, limit)
  (((b & 0x7F) << 8) | b2, pos + 2)
}

///|
/// 字符串池长度前缀(16 位形式):高位置位时由两个 16 位字组成。
/// 返回 (长度值, 后续位置)。
fn read_len16(
  data : Bytes,
  pos : Int32,
  limit : Int32,
) -> (Int32, Int32) raise AxmlError {
  let u = read_u16(data, pos, limit)
  if (u & 0x8000) == 0 {
    return (u, pos + 2)
  }
  let u2 = read_u16(data, pos + 2, limit)
  (((u & 0x7FFF) << 16) | u2, pos + 4)
}

///|
/// 校验后的 Unicode 标量值转 `Char`;防御性兜底,正常路径在校验后不会触发。
fn scalar_to_char(cp : Int32, at : Int32) -> Char raise AxmlError {
  match cp.to_char() {
    Some(c) => c
    None => raise BadStringPool(at, "invalid Unicode scalar value \{cp}")
  }
}

///|
/// 严格 UTF-8 解码:`off` 起 `len` 字节。拒绝过长编码、代理项码点与超出
/// U+10FFFF 的码点;非法字节以 `BadStringPool(非法字节偏移, detail)` 报告。
fn decode_utf8(
  data : Bytes,
  off : Int32,
  len : Int32,
) -> String raise AxmlError {
  if off < 0 || len < 0 || off + len > data.length() {
    raise UnexpectedEof(off)
  }
  let builder = StringBuilder(capacity=len)
  let end = off + len
  let mut i = off
  while i < end {
    let b0 = data.at(i).to_int()
    if b0 < 0x80 {
      builder.write_char(scalar_to_char(b0, i))
      i = i + 1
    } else if b0 >= 0xC2 && b0 < 0xE0 {
      if i + 2 > end {
        raise BadStringPool(i, "truncated UTF-8 sequence")
      }
      let b1 = data.at(i + 1).to_int()
      if b1 < 0x80 || b1 > 0xBF {
        raise BadStringPool(i + 1, "invalid UTF-8 continuation byte")
      }
      builder.write_char(scalar_to_char(((b0 & 0x1F) << 6) | (b1 & 0x3F), i))
      i = i + 2
    } else if b0 >= 0xE0 && b0 < 0xF0 {
      if i + 3 > end {
        raise BadStringPool(i, "truncated UTF-8 sequence")
      }
      let b1 = data.at(i + 1).to_int()
      let b2 = data.at(i + 2).to_int()
      if b1 < 0x80 || b1 > 0xBF {
        raise BadStringPool(i + 1, "invalid UTF-8 continuation byte")
      }
      if b2 < 0x80 || b2 > 0xBF {
        raise BadStringPool(i + 2, "invalid UTF-8 continuation byte")
      }
      let cp = ((b0 & 0x0F) << 12) | ((b1 & 0x3F) << 6) | (b2 & 0x3F)
      if cp < 0x800 {
        raise BadStringPool(i, "overlong UTF-8 encoding")
      }
      if cp >= 0xD800 && cp <= 0xDFFF {
        raise BadStringPool(i, "UTF-8 encoding of surrogate code point")
      }
      builder.write_char(scalar_to_char(cp, i))
      i = i + 3
    } else if b0 >= 0xF0 && b0 < 0xF5 {
      if i + 4 > end {
        raise BadStringPool(i, "truncated UTF-8 sequence")
      }
      let b1 = data.at(i + 1).to_int()
      let b2 = data.at(i + 2).to_int()
      let b3 = data.at(i + 3).to_int()
      if b1 < 0x80 || b1 > 0xBF {
        raise BadStringPool(i + 1, "invalid UTF-8 continuation byte")
      }
      if b2 < 0x80 || b2 > 0xBF {
        raise BadStringPool(i + 2, "invalid UTF-8 continuation byte")
      }
      if b3 < 0x80 || b3 > 0xBF {
        raise BadStringPool(i + 3, "invalid UTF-8 continuation byte")
      }
      let cp = ((b0 & 0x07) << 18) |
        ((b1 & 0x3F) << 12) |
        ((b2 & 0x3F) << 6) |
        (b3 & 0x3F)
      if cp < 0x10000 {
        raise BadStringPool(i, "overlong UTF-8 encoding")
      }
      if cp > 0x10FFFF {
        raise BadStringPool(i, "UTF-8 code point out of range")
      }
      builder.write_char(scalar_to_char(cp, i))
      i = i + 4
    } else {
      raise BadStringPool(i, "invalid UTF-8 lead byte")
    }
  }
  builder.to_string()
}

///|
/// UTF-16LE 解码:`off` 起 `units` 个 code unit。合并代理对;孤立代理以
/// `BadStringPool(代理位置, detail)` 报告。
fn decode_utf16(
  data : Bytes,
  off : Int32,
  units : Int32,
) -> String raise AxmlError {
  if off < 0 ||
    units < 0 ||
    off > data.length() ||
    units > (data.length() - off) / 2 {
    raise UnexpectedEof(off)
  }
  let builder = StringBuilder(capacity=units)
  let mut i = 0
  while i < units {
    let base = off + 2 * i
    let u = data.at(base).to_int() | (data.at(base + 1).to_int() << 8)
    if u >= 0xD800 && u <= 0xDBFF {
      if i + 1 >= units {
        raise BadStringPool(base, "unpaired UTF-16 high surrogate")
      }
      let next = off + 2 * (i + 1)
      let lo = data.at(next).to_int() | (data.at(next + 1).to_int() << 8)
      if lo < 0xDC00 || lo > 0xDFFF {
        raise BadStringPool(next, "unpaired UTF-16 high surrogate")
      }
      let cp = 0x10000 + ((u - 0xD800) << 10) + (lo - 0xDC00)
      builder.write_char(scalar_to_char(cp, base))
      i = i + 2
    } else if u >= 0xDC00 && u <= 0xDFFF {
      raise BadStringPool(base, "unpaired UTF-16 low surrogate")
    } else {
      builder.write_char(scalar_to_char(u, base))
      i = i + 1
    }
  }
  builder.to_string()
}

///|
/// 解码一个 UTF-8 字符串池条目:字符数前缀 + 字节数前缀 + 载荷 + NUL 终止符。
/// `chunk_end` 为所在字符串池 chunk 的开区间末尾。
fn decode_utf8_entry(
  data : Bytes,
  entry : Int32,
  chunk_end : Int32,
) -> String raise AxmlError {
  let (_, p1) = read_len8(data, entry, chunk_end)
  let (byte_len, p2) = read_len8(data, p1, chunk_end)
  if p2 + byte_len + 1 > chunk_end {
    raise BadStringPool(entry, "string entry exceeds string-pool chunk")
  }
  let s = decode_utf8(data, p2, byte_len)
  if data.at(p2 + byte_len).to_int() != 0 {
    raise BadStringPool(p2 + byte_len, "string entry lacks NUL terminator")
  }
  s
}

///|
/// 解码一个 UTF-16 字符串池条目:unit 数前缀 + 载荷 + 16 位 NUL 终止符。
fn decode_utf16_entry(
  data : Bytes,
  entry : Int32,
  chunk_end : Int32,
) -> String raise AxmlError {
  let (units, p1) = read_len16(data, entry, chunk_end)
  if p1 + 2 > chunk_end || units > (chunk_end - p1 - 2) / 2 {
    raise BadStringPool(entry, "string entry exceeds string-pool chunk")
  }
  let s = decode_utf16(data, p1, units)
  if data.at(p1 + 2 * units).to_int() != 0 ||
    data.at(p1 + 2 * units + 1).to_int() != 0 {
    raise BadStringPool(p1 + 2 * units, "string entry lacks NUL terminator")
  }
  s
}

///|
/// 解析 RES_STRING_POOL_TYPE chunk(chunk 起始于 `off`,长度 `csize`)。
/// 校验:headerSize==28、flags 仅含 SORTED/UTF8 位、count 与 offset 表、
/// stringsStart/stylesStart 一致性、每个条目完整且带 NUL 终止符。
fn parse_string_pool(
  data : Bytes,
  off : Int32,
  csize : Int32,
) -> StringPool raise AxmlError {
  let limit = off + csize
  let string_count = read_u32(data, off + 8, limit)
  let style_count = read_u32(data, off + 12, limit)
  let flags = read_u32(data, off + 16, limit)
  let strings_start = read_u32(data, off + 20, limit)
  let styles_start = read_u32(data, off + 24, limit)
  // 已知标志位:SORTED_FLAG(1) 与 UTF8_FLAG(0x100);其余位意味着未知编码。
  if flags < 0 || flags > 0x101 || (flags & 0x101) != flags {
    raise UnsupportedEncoding(
      "string pool at offset \{off} has unknown flags \{flags}",
    )
  }
  let encoding = if (flags & 0x100) == 0 { Utf16 } else { Utf8 }
  if string_count < 0 || style_count < 0 || string_count > (csize - 28) / 4 {
    raise BadStringPool(off, "string count \{string_count} exceeds chunk")
  }
  if style_count > (csize - 28 - 4 * string_count) / 4 {
    raise BadStringPool(off, "style count \{style_count} exceeds chunk")
  }
  let table_end = 28 + 4 * (string_count + style_count)
  if strings_start < table_end || strings_start > csize {
    raise BadStringPool(
      off,
      "stringsStart \{strings_start} is outside the string-pool chunk",
    )
  }
  if style_count == 0 {
    if styles_start != 0 {
      raise BadStringPool(
        off,
        "stylesStart \{styles_start} is set without style entries",
      )
    }
  } else if styles_start < strings_start || styles_start > csize {
    raise BadStringPool(
      off,
      "stylesStart \{styles_start} is outside the string-pool chunk",
    )
  }
  let strings : Array[String] = []
  let mut i = 0
  while i < string_count {
    let table_off = off + 28 + 4 * i
    let rel = read_u32(data, table_off, limit)
    if rel < 0 || rel >= csize - strings_start {
      raise BadStringPool(table_off, "string offset \{rel} is out of range")
    }
    let entry = off + strings_start + rel
    let s = if encoding is Utf8 {
      decode_utf8_entry(data, entry, limit)
    } else {
      decode_utf16_entry(data, entry, limit)
    }
    strings.push(s)
    i = i + 1
  }
  let styles : Bytes = if style_count == 0 {
    b""
  } else {
    Bytes::from_array(data[off + styles_start:limit].to_array())
  }
  { encoding, strings, styles, }
}

///|
/// `Res_value.dataType` 的支持子集映射;未知编码原样保留在 `Unknown` 中,
/// 便于上层降级而不丢失信息。
fn value_type_of(data_type : Int32) -> ValueType {
  match data_type {
    0x00 => Null
    0x01 => Reference
    0x02 => Attribute
    0x03 => String
    0x04 => Float
    0x05 => Dimension
    0x06 => Fraction
    0x10 => IntDec
    0x11 => IntHex
    0x12 => IntBoolean
    _ => Unknown(data_type)
  }
}

///|
/// 解析必须存在的字符串池引用;越界(含 -1)返回 `InvalidStringIndex`。
fn string_req(pool : StringPool, index : Int32) -> String raise AxmlError {
  if index < 0 || index >= pool.strings.length() {
    raise InvalidStringIndex(index)
  }
  pool.strings.at(index)
}

///|
/// 解析可选字符串池引用;`0xFFFFFFFF`(-1)表示不存在,其余越界值返回
/// `InvalidStringIndex`。
fn string_opt(pool : StringPool, index : Int32) -> String? raise AxmlError {
  if index == -1 {
    return None
  }
  if index < 0 || index >= pool.strings.length() {
    raise InvalidStringIndex(index)
  }
  Some(pool.strings.at(index))
}