// encoding/hex — RFC 4648 base16 (hexadecimal) over the io-streaming
// surface. Port of ref/hare/encoding/hex/hex.ha.
//
// The streaming DECODER (newdecoder/decode_reader, ref hex.ha:120,129)
// is DEFERRED — project #247, blocked on #199b. Hare's decode_reader
// returns errors::invalid on bad hex, which fits Hare's io::error (it
// spreads ...errors::error). ww's io.error (lib/io/types.ww:55-62) does
// NOT carry errors.invalid (the #199b deferral) and io.read's
// (size | eof | error) can't propagate it either, so a hex decoder
// *stream* cannot faithfully report invalid through io.read until #199b
// lands. decodestr ships as a direct transform meanwhile (its own
// return union carries errors.invalid; it is not io.error-constrained).
//
// Output is always lowercase per ref/hare/encoding/hex/README:13; the
// decoder accepts both upper- and lower-case per the same line
// (strconv.stou8 is case-insensitive, ref/hare/strconv/stou.ha:8-15).
package hex;

import errors;
import fmt;
import io;
import memio;
import strconv;
import strings;

// encoder — a write-only io stream that lowercase-hex-encodes writes
// before forwarding them to `out`. ref/hare/encoding/hex/hex.ha:14.
// `vt` at offset 0 for the intrusive stream→io.stream cast (&e.vt) and
// the writer's reverse `s: *encoder` cast — same shape as memio.stream.
// Hare keeps a shared const encoder_vtable; ww embeds the vtable INLINE
// and wires the writer slot post-construction (memio convention).
export type encoder = struct {
	vt:  io.vtable,
	out: io.handle,
	err: (void | io.error),
};

// newencoder — wire an encoder over `out`. ref/hare/encoding/hex/hex.ha:28.
// Returns BY VALUE (memio constructor convention, proven sret round-trip);
// the caller passes &enc.vt to the io dispatchers.
export fn newencoder(out: io.handle) encoder = {
	let r: encoder;
	r.vt.writer = (&encode_writer): *io.writer;
	r.out = out;
	r.err = void;
	return r;
};

// encode_writer — the encoder's io.writer slot. ref/hare/encoding/hex/hex.ha:36.
// Recovers the encoder via the offset-0 cast, lowercase-hex-encodes each
// byte (strconv.u8tos plus a leading "0" pad for single-digit nibbles,
// as Hare does), forwards to `out` via fmt.fprint, and caches the first
// error in `err` like Hare. Returns the count of bytes written to `out`
// (= 2 * len(in)).
fn encode_writer(s: io.stream, in: []u8) (size | io.error) = {
	let e: *encoder = s: *encoder;
	match (e.err) {
	case let er: io.error => return er;
	case void => void;
	};
	let z: size = 0;
	let i: i32 = 0;
	for (i < in.len) {
		let r: str = strconv.u8tos(in[i], strconv.base.HEX_LOWER);
		if (r.len == 1) {
			match (fmt.fprint(e.out, "0")) {
			case let b: size => z += b;
			case let er: io.error => { e.err = er; return er; };
			};
		};
		match (fmt.fprint(e.out, r)) {
		case let b: size => z += b;
		case let er: io.error => { e.err = er; return er; };
		};
		i += 1;
	};
	return z;
};

// encode — hex-encode `in` and write it to `out`; returns the byte count
// written. ref/hare/encoding/hex/hex.ha:91. Hare wraps io::writeall; ww
// has no io.writeall (fmt.fprint:498-501 — callers drive write-all over
// raw io.write) and encode_writer is whole-slice (never partial), so a
// single io.write is equivalent here.
export fn encode(out: io.handle, in: []u8) (size | io.error) = {
	let enc: encoder = newencoder(out);
	return io.write(&enc.vt, in);
};

// encodestr — hex-encode `in` and return it as a string.
// ref/hare/encoding/hex/hex.ha:68. Hare returns (str | nomem) and the
// caller frees; ww returns a bare `str` per the memio.string rule-9
// carve-out (memio.ww:208-214 — ww memio.dynamic has no nomem path) and
// leaks the backing buffer (no-GC, process-exit reclaims).
export fn encodestr(in: []u8) str = {
	let out: memio.stream = memio.dynamic();
	let enc: encoder = newencoder(&out.vt);
	match (io.write(&enc.vt, in)) {
	case let n: size => void;
	case let e: io.error => abort("hex.encodestr: dynamic memio write failed");
	};
	return memio.string(&out);
};

// decodestr — decode a string of hexadecimal bytes into a byte slice.
// ref/hare/encoding/hex/hex.ha:175. Hare returns ([]u8 | errors::invalid
// | nomem) and decodes by copying through a newdecoder stream; ww drops
// nomem (memio rule-9 carve-out, as encodestr) and decodes DIRECTLY —
// the streaming decoder is deferred to #247 (see file header). The
// decode logic mirrors Hare's decode_reader (hex.ha:154-170): odd length
// → invalid, then strconv.stou8 per 2-char pair (case-insensitive).
export fn decodestr(s: str) ([]u8 | errors.invalid) = {
	let in: []u8 = strings.toutf8(s);
	if ((in.len & 1) != 0) {
		let e: errors.invalid;
		return e;
	};
	let l: i32 = in.len / 2;
	// empty bypass: ww alloc([],0) routes through nomem (cf ascii.ww:143).
	if (l == 0) {
		let empty: []u8;
		empty.ptr = nil;
		empty.len = 0;
		return empty;
	};
	let out: []u8 = alloc([], l: u64)!;
	let i: i32 = 0;
	for (i < l) {
		let lo: i32 = i * 2;
		let oct: str = strings.frombytes(in[lo : lo + 2]);
		let u: u8 = match (strconv.stou8(oct, strconv.base.HEX)) {
		case let v: u8 => yield v;
		case let e: strconv.invalid  => { let er: errors.invalid; return er; };
		case let e: strconv.overflow => { let er: errors.invalid; return er; };
		};
		out[i] = u;
		i += 1;
	};
	out.len = l;
	return out;
};