///| NRRD header serialization and data payload encoding (G3 write-side).
///| Contract (G2 v2 §3 / §7): `format_header` emits NRRD0005 text,
///| `encode_data` emits payload bytes, `assemble_attached` /
///| `assemble_detached` combine them WITHOUT any file IO — the core
///| returns only Bytes/String; filenames are chosen by the host and
///| must match the header's `data file` declaration.
///|
///| Value policy (G2 v2 §7.1): integer-typed values must be finite,
///| integral and inside the type range — violations raise with the
///| value and type, never silently truncate. uint32's high half is
///| carried exactly (Double -> Int64 within 2^53). Float values are
///| rounded to the nearest binary32 (ties-to-even, `Float::from_double`;
///| overflow saturates to +-inf). Double values are bit-exact,
///| including -0.0; NaN payload bits are not promised (semantic
///| comparison). ASCII integers use exact decimal Int64 formatting
///| (never a lossy float format); ASCII float32 writes the shortest
///| decimal that round-trips through the READER's two-step parse
///| (decimal -> binary64 -> binary32); ASCII double writes the
///| shortest binary64 round-trip string.
///|
///| Budget (G2 v2 §7.2): max 2^24 elements, overridable via `budget~`.
///| Checked as a defensive lower bound before building the output;
///| peak memory may exceed the naive product. The raw byte product is
///| additionally pre-checked with a division so `count * item` cannot
///| wrap Int.
///|
///| String fields (spec escaping, injection defense):
///| - v1 write contract: ALL writable strings (content, data file,
///| labels, space units, space, kinds, key:=value key and value)
///| are ASCII only. Non-ASCII code points are REJECTED with
///| NrrdError before any byte conversion — never silently
///| truncated to a low byte (U+010A -> 0x0A would inject a
///| newline into the header) and never panicked on (a
///| supplementary-plane UTF-16 traversal raises instead).
///| - `content` / `data file` are bare line strings: newline/CR and
///| other C0 controls are rejected; leading/trailing whitespace is
///| rejected (both readers trim, so it could not round-trip).
///| - `labels` / `space units` are quote-delimited: `"` is escaped as
///| `\"` (the only escape the spec defines); backslash is REJECTED
///| (the spec defines no backslash escape and readers disagree on
///| `\\`, so a literal backslash cannot be round-tripped safely);
///| newline/CR/controls are rejected.
///| - `kinds` are bare whitespace-separated tokens: whitespace,
///| quotes and controls inside a token are rejected.
///| - key:=value pairs: see `format_keyval_line` (spec escapes
///| `\n` and `\\`; keys that collide with standard field names are
///| rejected so custom pairs cannot shadow known fields).
///| Unknown-field / key:=value preservation is NOT implemented:
///| `NrrdHeader` carries only standard fields and `format_header`
///| emits only those (no replay of unvalidated fields).
///| Allocation budget: refuse to encode more than 2^24 elements.
fn max_encode_elements() -> Int {
16777216
}
///| Stringify a Double for error messages.
fn encode_value_repr(d : Double) -> String {
if d.is_nan() {
"nan"
} else if d.is_pos_inf() {
"+inf"
} else if d.is_neg_inf() {
"-inf"
} else {
d.to_string()
}
}
///| Integer-typed value policy (G2 v2 §7.1): finite, integral, in
///| range. Returns the value as Int64 (exact for every supported
///| integer type). Raises with value and type on any violation —
///| never silently truncates.
fn integer_bits(d : Double, t : String) -> Int64 raise NrrdError {
if d.is_nan() {
raise NrrdError("\{t}: NaN is not a valid integer value")
}
if d.is_inf() {
raise NrrdError("\{t}: infinity is not a valid integer value")
}
if d != d.trunc() {
raise NrrdError("\{t}: non-integral value \{encode_value_repr(d)}")
}
let (lo, hi) = int_value_range(t)
if d < lo.to_double() || d > hi.to_double() {
raise NrrdError(
"\{t}: value \{encode_value_repr(d)} out of range [\{lo.to_string()},\{hi.to_string()}]",
)
}
d.to_int64()
}
///| Raw bit pattern (Int64, low `item` bytes meaningful) for one
///| value of canonical type `t`. Integers are validated first;
///| float rounds to binary32; double keeps its exact bit pattern.
fn raw_value_bits(d : Double, t : String) -> Int64 raise NrrdError {
match t {
"int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" => integer_bits(d, t)
"float" => Float::reinterpret_as_int(Float::from_double(d)).to_int64()
_ => d.reinterpret_as_int64() // double
}
}
///| Write the low `item` bytes of `bits` at offset `at`, little- or
///| big-endian. Byte extraction masks after an arithmetic shift, so
///| negative Int64 patterns (two's complement) yield the right bytes.
fn write_bits(out : Array[Byte], at : Int, bits : Int64, item : Int, big : Bool) -> Unit {
let mut k = 0
while k < item {
let b = (bits >> (8 * k)).land(255L).to_int().to_byte()
if big {
out[at + item - 1 - k] = b
} else {
out[at + k] = b
}
k = k + 1
}
}
///| Reject non-ASCII code points, invalid UTF-16 code units and
///| C0 controls in a bare line string. v1 write contract: writable
///| strings are ASCII only; a non-ASCII code point is NEVER silently
///| truncated to its low byte (U+010A would become 0x0A and inject
///| a newline) and supplementary-plane UTF-16 traversal raises
///| instead of panicking.
fn check_line_value(s : String, field : String) -> Unit raise NrrdError {
let mut i = 0
while i < s.length() {
match s.get_char(i) {
Some(c) => {
let v = c.to_int()
if v > 127 {
raise NrrdError(
"\{field}: non-ASCII code point \{v.to_string()} is not representable (write strings are ASCII only)",
)
}
if v < 32 {
raise NrrdError(
"\{field}: control character \{v.to_string()} in string is not representable",
)
}
}
None => raise NrrdError(
"\{field}: invalid UTF-16 code unit at index \{i.to_string()}",
)
}
i = i + 1
}
}
///| Bare line strings additionally must not rely on leading/trailing
///| whitespace: both this library's parser and pynrrd trim the field
///| value, so such whitespace could not round-trip (silent change).
fn check_line_value_trimmed(s : String, field : String) -> Unit raise NrrdError {
check_line_value(s, field)
if s != s.trim().to_owned() {
raise NrrdError(
"\{field}: leading/trailing whitespace would not round-trip (values are trimmed on read)",
)
}
}
///| One quote-delimited token (labels / space units). Spec §1.6:
///| `"` is escaped as `\"` and that is the ONLY escape; backslash
///| has no spec escape, so it is rejected here to stay unambiguous
///| across readers (see module doc).
fn format_quoted_token(s : String, field : String) -> String raise NrrdError {
let out = StringBuilder()
out.write_string("\"")
let mut i = 0
while i < s.length() {
match s.get_char(i) {
Some(c) => {
let v = c.to_int()
if v > 127 {
raise NrrdError(
"\{field}: non-ASCII code point \{v.to_string()} is not representable (write strings are ASCII only)",
)
}
if c == '"' {
out.write_string("\\\"")
} else if c == '\\' {
raise NrrdError(
"\{field}: backslash in string has no spec escape and would not round-trip safely",
)
} else if v < 32 {
raise NrrdError(
"\{field}: control character \{v.to_string()} in string is not representable",
)
} else {
out.write_char(c)
}
}
None => raise NrrdError(
"\{field}: invalid UTF-16 code unit at index \{i.to_string()}",
)
}
i = i + 1
}
out.write_string("\"")
out.to_string()
}
///| Quote-delimited string list: `"a" "b"` (tokens delimited by a
///| single space, per spec §4/§6).
fn format_quoted_list(ss : Array[String], field : String) -> String raise NrrdError {
let out = StringBuilder()
let mut first = true
for s in ss {
if !first {
out.write_string(" ")
}
out.write_string(format_quoted_token(s, field))
first = false
}
out.to_string()
}
///| Bare whitespace-separated tokens (kinds). A token containing
///| whitespace would split in two; a token containing `"` would be
///| re-read as a quoted string — both are rejected to keep the
///| round-trip exact.
fn format_bare_list(ss : Array[String], field : String) -> String raise NrrdError {
let out = StringBuilder()
let mut first = true
for s in ss {
if s.is_empty() {
raise NrrdError("\{field}: empty token")
}
check_line_value_trimmed(s, field)
// interior whitespace would split one token into several on read
if s.contains(" ") || s.contains("\t") {
raise NrrdError("\{field}: whitespace in bare token is not representable")
}
if s.contains("\"") {
raise NrrdError("\{field}: double quote in bare token is not representable")
}
if !first {
out.write_string(" ")
}
out.write_string(s)
first = false
}
out.to_string()
}
///| One spatial vector: `(a,b,c)` with comma-separated components and
///| NO whitespace inside the vector (pynrrd splits vector lists on
///| whitespace, so an inner space would break the row). Components
///| must be finite: `parse_paren_vec` has no nan/inf literal path.
fn format_spatial_vec(v : Array[Double], field : String) -> String raise NrrdError {
if v.is_empty() {
raise NrrdError("\{field}: empty vector")
}
let out = StringBuilder()
out.write_string("(")
let mut first = true
for c in v {
if c.is_nan() || c.is_inf() {
raise NrrdError("\{field}: spatial vector components must be finite")
}
if !first {
out.write_string(",")
}
out.write_string(format_float(c))
first = false
}
out.write_string(")")
out.to_string()
}
///| `space directions` descriptor: rows delimited by whitespace
///| (spec §6: per-axis descriptors are delimited by spaces/tabs) with
///| `none` for non-spatial axes. NOTE: the probe's canonical dump
///| format uses " | " separators (format.mbt `format_directions`) for
///| diffing against pynrrd-reads.txt — that is a dump convention, not
///| a file format; file output follows the spec here.
fn format_directions_value(rows : Array[Array[Double]?]) -> String raise NrrdError {
let out = StringBuilder()
let mut first = true
for row in rows {
if !first {
out.write_string(" ")
}
match row {
Some(v) => out.write_string(format_spatial_vec(v, "space directions"))
None => out.write_string("none")
}
first = false
}
out.to_string()
}
///| Known standard field identifiers (normalized: lowercased, spaces
///| stripped, alias-collapsed). Used to stop custom key:=value pairs
///| from shadowing standard fields in readers with last-wins
///| semantics ("unknown fields must not override known fields").
fn is_standard_field_id(norm : String) -> Bool {
match canonical_field_id(norm) {
"dimension" | "sizes" | "type" | "encoding" | "endian" | "datafile" | "space" |
"spacedimension" | "spaceorigin" | "spacedirections" | "spaceunits" | "labels" |
"kinds" | "content" | "lineskip" | "byteskip" | "min" | "max" | "oldmin" | "oldmax" |
"sampleunits" | "units" | "centerings" | "spacings" | "thicknesses" | "axismins" |
"axismaxs" | "measurementframe" | "blocksize" => true
_ => false
}
}
///| One spec-escaped custom key:=value line (without trailing
///| newline). Spec §1.7 minimal escaping — writers MUST generate it:
///| `\n` (backslash-n) for newline, `\\` for backslash. `\r` and
///| other controls are rejected (no escape exists and they break
///| line structure). The key must not contain `:` (readers split at
///| the first colon, so `a:b:=v` would be misread), must not contain
///| `:=`, must not start with `#` (comment), must not collide with a
///| standard field name, and must not carry edge whitespace.
///| NOTE: NrrdHeader does not carry key:=value pairs — this helper is
///| for hosts that append custom pairs; preservation through this
///| library is unsupported (see module doc).
pub fn format_keyval_line(key : String, value : String) -> String raise NrrdError {
if key.is_empty() {
raise NrrdError("key:=value: empty key")
}
check_line_value_trimmed(key, "key:=value key")
if key.contains(":") {
raise NrrdError("key:=value: key must not contain ':'")
}
if key.get_char(0) == Some('#') {
raise NrrdError("key:=value: key must not start with '#' (would be a comment)")
}
if is_standard_field_id(normalize_field_name(key)) {
raise NrrdError(
"key:=value: key '\{key}' collides with a standard field name",
)
}
let out = StringBuilder()
out.write_string(key)
out.write_string(":=")
let mut i = 0
while i < value.length() {
match value.get_char(i) {
Some(c) => {
let v = c.to_int()
if v > 127 {
raise NrrdError(
"key:=value: non-ASCII code point \{v.to_string()} in value is not representable (write strings are ASCII only)",
)
}
if c == '\\' {
out.write_string("\\\\")
} else if c == '\n' {
out.write_string("\\n")
} else if v < 32 {
raise NrrdError(
"key:=value: control character \{v.to_string()} in value is not representable",
)
} else {
out.write_char(c)
}
}
None => raise NrrdError(
"key:=value: invalid UTF-16 code unit at index \{i.to_string()} in value",
)
}
i = i + 1
}
out.to_string()
}
///| Validate the pieces of a header that affect serialization
///| legality (type/encoding support, skip rejection, endian form).
fn check_writable(h : NrrdHeader) -> Unit raise NrrdError {
if h.line_skip != 0 || h.byte_skip != 0 {
raise NrrdError(
"line skip/byte skip are not supported (got \{h.line_skip}/\{h.byte_skip})",
)
}
let t = normalize_type(h.type_name)
let e = normalize_encoding(h.encoding)
check_supported_type(t)
check_supported_encoding(e)
match h.endian {
Some(en) => {
let low = en.to_lower()
if low != "little" && low != "big" {
raise NrrdError("endian must be little|big, got '\{en}'")
}
}
None => ()
}
}
///| Serialize an NRRD0005 header. Validates the header (structure
///| and spatial legality) and every string field against injection
///| (see module doc) before emitting anything. Unknown fields and
///| key:=value pairs are not carried by NrrdHeader and are never
///| replayed here.
pub fn format_header(h : NrrdHeader) -> String raise NrrdError {
// v1 ASCII write contract checked uniformly on every writable
// string BEFORE semantic validation or formatting (必修 1): a
// non-ASCII code point must always raise, regardless of which
// field carries it or what other legality rules apply.
match h.data_file {
Some(name) => check_line_value_trimmed(name, "data file")
None => ()
}
match h.content {
Some(c) => check_line_value_trimmed(c, "content")
None => ()
}
match h.space {
Some(sp) => check_line_value_trimmed(sp, "space")
None => ()
}
match h.labels {
Some(ls) =>
for s in ls {
check_line_value(s, "labels")
}
None => ()
}
match h.space_units {
Some(us) =>
for s in us {
check_line_value(s, "space units")
}
None => ()
}
match h.kinds {
Some(ks) =>
for s in ks {
check_line_value(s, "kinds")
}
None => ()
}
validate_header(h)
check_writable(h)
let t = normalize_type(h.type_name)
let e = normalize_encoding(h.encoding)
let out = StringBuilder()
out.write_string("NRRD0005\n")
out.write_string("type: \{t}\n")
out.write_string("dimension: \{h.dimension.to_string()}\n")
out.write_string("sizes: \{format_int_list(h.sizes)}\n")
out.write_string("encoding: \{e}\n")
match h.endian {
Some(en) => out.write_string("endian: \{en.to_lower()}\n")
None => ()
}
match h.space {
Some(sp) => {
check_line_value_trimmed(sp, "space")
out.write_string("space: \{sp}\n")
}
None => ()
}
match h.space_dimension {
Some(sd) => out.write_string("space dimension: \{sd.to_string()}\n")
None => ()
}
match h.space_origin {
Some(o) => out.write_string("space origin: \{format_spatial_vec(o, "space origin")}\n")
None => ()
}
if !h.space_directions.is_empty() {
out.write_string("space directions: \{format_directions_value(h.space_directions)}\n")
}
match h.space_units {
Some(us) => out.write_string("space units: \{format_quoted_list(us, "space units")}\n")
None => ()
}
match h.kinds {
Some(ks) => out.write_string("kinds: \{format_bare_list(ks, "kinds")}\n")
None => ()
}
match h.labels {
Some(ls) => out.write_string("labels: \{format_quoted_list(ls, "labels")}\n")
None => ()
}
match h.content {
Some(c) => out.write_string("content: \{c}\n")
None => ()
}
match h.data_file {
Some(name) => out.write_string("data file: \{name}\n")
None => ()
}
out.to_string()
}
///| Space-separated decimal integers for `sizes` / similar lists.
fn format_int_list(xs : Array[Int]) -> String {
let out = StringBuilder()
let mut first = true
for x in xs {
if !first {
out.write_string(" ")
}
out.write_string(x.to_string())
first = false
}
out.to_string()
}
///| Special-value tokens shared by the ASCII float writers
///| (spec §2 substring rules write-side subset): nan / inf / -inf /
///| signed zero. Returns None for non-zero finite values.
fn ascii_special_token(d : Double) -> String? {
if d.is_nan() {
Some("nan")
} else if d.is_pos_inf() {
Some("inf")
} else if d.is_neg_inf() {
Some("-inf")
} else if d == 0.0 {
Some(if is_neg_zero(d) { "-0.0" } else { "0.0" })
} else {
None
}
}
///| Parse a plain/scientific decimal string into (neg, digits, exp)
///| with value = 0.digits * 10^exp, digits without leading/trailing
///| zeros ("0" for zero). Handles the forms Double::to_string emits.
fn parse_decimal_spec(s : String) -> (Bool, String, Int)? {
let n = s.length()
let mut i = 0
let mut neg = false
if i < n && (char_at(s, i) == '-' || char_at(s, i) == '+') {
neg = char_at(s, i) == '-'
i = i + 1
}
let int_start = i
while i < n && char_at(s, i).is_ascii_digit() {
i = i + 1
}
let int_len = i - int_start
let mut frac_start = i
let mut frac_len = 0
if i < n && char_at(s, i) == '.' {
i = i + 1
frac_start = i
while i < n && char_at(s, i).is_ascii_digit() {
i = i + 1
}
frac_len = i - frac_start
}
if int_len == 0 && frac_len == 0 {
return None
}
let mut e_add = 0
if i < n && (char_at(s, i) == 'e' || char_at(s, i) == 'E') {
i = i + 1
let mut e_neg = false
if i < n && (char_at(s, i) == '-' || char_at(s, i) == '+') {
e_neg = char_at(s, i) == '-'
i = i + 1
}
let e_start = i
while i < n && char_at(s, i).is_ascii_digit() {
i = i + 1
}
if i == e_start {
return None
}
match parse_int_str(slice_str(s, e_start, i)) {
Some(v) => e_add = if e_neg { 0 - v } else { v }
None => return None
}
}
if i != n {
return None
}
// digits = int part + frac part, then strip leading/trailing zeros
let digits = StringBuilder()
let mut k = int_start
while k < int_start + int_len {
digits.write_char(char_at(s, k))
k = k + 1
}
k = frac_start
while k < frac_start + frac_len {
digits.write_char(char_at(s, k))
k = k + 1
}
let raw = digits.to_string()
let mut lead = 0
while lead < raw.length() && char_at(raw, lead) == '0' {
lead = lead + 1
}
if lead == raw.length() {
// zero: KEEP the sign (必修 2 — dropping it here turned a
// negative-zero candidate into a sign-less "0")
return Some((neg, "0", 0))
}
let mut trail = raw.length()
while trail > lead && char_at(raw, trail - 1) == '0' {
trail = trail - 1
}
let core = slice_str(raw, lead, trail)
// 0.raw * 10^(int_len + e_add); stripping `lead` zeros divides by 10^lead
let exp = int_len + e_add - lead
Some((neg, core, exp))
}
///| Rebuild a decimal string from (digits, exp), value =
///| 0.digits * 10^exp. Plain form for moderate exponents, otherwise
///| `d[.rest]e[+-]X`.
fn build_decimal(neg : Bool, digits : String, exp : Int) -> String {
let out = StringBuilder()
if neg {
out.write_string("-")
}
let e1 = exp - 1 // d1.d2... * 10^e1
if e1 >= -5 && e1 <= 20 {
if exp >= 1 {
if digits.length() >= exp {
out.write_string(slice_str(digits, 0, exp))
if digits.length() > exp {
out.write_string(".")
out.write_string(slice_str(digits, exp, digits.length()))
}
} else {
out.write_string(digits)
let mut z = digits.length()
while z < exp {
out.write_string("0")
z = z + 1
}
}
} else {
out.write_string("0.")
let mut z = exp
while z < 0 {
out.write_string("0")
z = z + 1
}
out.write_string(digits)
}
} else {
out.write_string(slice_str(digits, 0, 1))
if digits.length() > 1 {
out.write_string(".")
out.write_string(slice_str(digits, 1, digits.length()))
}
out.write_string("e")
if e1 >= 0 {
out.write_string("+")
}
out.write_string(e1.to_string())
}
out.to_string()
}
///| Round the decimal string `s` to `k` significant digits
///| (round-half-up on the dropped prefix; the caller verifies the
///| result by parsing back, so the tie rule is not load-bearing).
///| Returns None if `s` is not a plain/scientific decimal.
fn round_sig_str(s : String, k : Int) -> String? {
match parse_decimal_spec(s) {
Some((neg, digits, exp)) => {
if digits == "0" || digits.length() <= k {
return Some(if digits == "0" && !neg { "0" } else { build_decimal(neg, digits, exp) })
}
let prefix = slice_str(digits, 0, k)
let round_up = char_at(digits, k) >= '5'
let mut core = prefix
let mut exp2 = exp
if round_up {
// increment the k-digit prefix as a decimal integer
let chars = Array::make(k, '0')
let mut i = 0
while i < k {
chars[i] = char_at(prefix, i)
i = i + 1
}
let mut j = k - 1
let mut carry = true
while carry && j >= 0 {
if chars[j] == '9' {
chars[j] = '0'
j = j - 1
} else {
chars[j] = (chars[j].to_int() + 1).unsafe_to_char()
carry = false
}
}
if carry {
// 999... -> 1000... with an extra digit: normalize to 1 * 10^exp
core = "1"
exp2 = exp + 1
} else {
core = String::from_array(chars)
}
}
// strip trailing zeros ("1200" -> "12"; 0.x * 10^exp is unchanged)
let mut trail = core.length()
while trail > 1 && char_at(core, trail - 1) == '0' {
trail = trail - 1
}
core = slice_str(core, 0, trail)
Some(build_decimal(neg, core, exp2))
}
None => None
}
}
///| Shortest decimal round-trip token for one binary32 value under
///| the READER's two-step parse (decimal -> binary64 -> binary32 via
///| `Float::from_double`). The input double is first reduced to its
///| nearest binary32 (ties-to-even; overflow saturates to +-inf,
///| underflow keeps the sign of zero) — the token describes THAT
///| stored value, so zero/inf/nan are decided AFTER narrowing
///| (必修 2: deciding specials on the pre-narrow double loses the
///| sign of a negative underflow like -1.0e-50 -> -0.0). Candidate
///| strings are verified by parsing back through the exact read
///| path with sign-aware comparison (f32_step_eq), so the result
///| round-trips by construction (cross-check with
///| tests/fixtures/double_rounding_case.json).
fn ascii_float32_token(v : Double) -> String {
let w = Float::to_double(Float::from_double(v))
match ascii_special_token(w) {
Some(t) => t
None => {
let full = w.to_string()
let mut k = 1
while k <= 17 {
match round_sig_str(full, k) {
Some(tok) => match parse_double_str(tok) {
Some(p) =>
if f32_step_eq(p, w) {
return tok
}
None => ()
}
None => ()
}
k = k + 1
}
// 17 significant digits always round-trip a binary32 widened
// to binary64; fall back to the binary64 shortest repr.
normalize_numeric_string(full)
}
}
}
///| Candidate check for the float32 ASCII writer: parse the decimal
///| token back through the reader's two-step parse and compare to
///| the stored binary32 `w`. Equal as float32 AND, when both are
///| zero, the sign of zero must match (IEEE `==` alone treats
///| +0.0 == -0.0 as equal and would accept a sign-losing token).
fn f32_step_eq(parsed : Double, w : Double) -> Bool {
let got = Float::to_double(Float::from_double(parsed))
if got == 0.0 && w == 0.0 {
is_neg_zero(got) == is_neg_zero(w)
} else {
got == w
}
}
///| ASCII token for a binary64 value: shortest round-trip string.
fn ascii_double_token_out(d : Double) -> String {
match ascii_special_token(d) {
Some(t) => t
None => normalize_numeric_string(d.to_string())
}
}
///| One ASCII data token for canonical type `t`. Integers go through
///| exact Int64 decimal formatting (never a lossy float format).
fn ascii_encode_token(d : Double, t : String) -> String raise NrrdError {
match t {
"float" => ascii_float32_token(d)
"double" => ascii_double_token_out(d)
_ => integer_bits(d, t).to_string()
}
}
///| Encode values to an NRRD payload (file order: sizes[0] fastest).
///| Validates the header independently of parse_header (callers may
///| construct headers directly). `values.length()` must equal the
///| sizes product. Raw multi-byte data requires an explicit endian;
///| ASCII ignores endian. Integers reject non-integral / NaN / inf /
///| out-of-range values (G2 v2 §7.1).
pub fn encode_data(
values : Array[Double],
header : NrrdHeader,
budget~ : Int = max_encode_elements(),
) -> Bytes raise NrrdError {
validate_header(header)
if header.line_skip != 0 || header.byte_skip != 0 {
raise NrrdError(
"line skip/byte skip are not supported (got \{header.line_skip}/\{header.byte_skip})",
)
}
let t = normalize_type(header.type_name)
let e = normalize_encoding(header.encoding)
check_supported_type(t)
check_supported_encoding(e)
let count = product_count(header.sizes)
if e == "raw" {
let item = item_size(t)
// division-style pre-check: `count * item` must not wrap Int
if count < 0 || count > 2147483647 / item {
raise NrrdError("byte length overflow: \{count} x \{item} bytes")
}
}
if count > budget {
raise NrrdError(
"refusing to encode \{count} elements; allocation budget is \{budget}",
)
}
if values.length() != count {
raise NrrdError(
"sizes product \{count} does not match values length \{values.length()}",
)
}
match e {
"raw" => {
let item = item_size(t)
let big = match header.endian {
Some(en) => match en.to_lower() {
"big" => true
"little" => false
_ => raise NrrdError("endian must be little|big, got '\{en}'")
}
None => {
if item > 1 {
raise NrrdError("raw multi-byte data missing endian field")
}
false
}
}
let need = count * item
let out : Array[Byte] = Array::make(need, b'\x00')
let mut i = 0
while i < count {
write_bits(out, i * item, raw_value_bits(values[i], t), item, big)
i = i + 1
}
Bytes::from_array(out)
}
"ascii" => {
let out = StringBuilder()
let mut i = 0
while i < count {
if i > 0 {
out.write_string(" ")
}
out.write_string(ascii_encode_token(values[i], t))
i = i + 1
}
out.write_string("\n")
ascii_to_bytes(out.to_string())
}
_ => raise NrrdError("unreachable encoding")
}
}
///| Concatenate two byte strings (header text + payload).
fn concat_bytes(a : Bytes, b : Bytes) -> Bytes {
let n = a.length()
let m = b.length()
Bytes::from_array(Array::makei(n + m, i => if i < n { a[i] } else { b[i - n] }))
}
///| Attached NRRD file bytes: header text, the terminating blank
///| line, then the payload. The header must NOT declare a data file.
///| No file IO — the caller decides the file name and writes bytes.
pub fn assemble_attached(
h : NrrdHeader,
values : Array[Double],
budget~ : Int = max_encode_elements(),
) -> Bytes raise NrrdError {
match h.data_file {
Some(_) => raise NrrdError(
"attached output must not declare a data file (host chose attached layout)",
)
None => ()
}
let head = format_header(h)
let payload = encode_data(values, h, budget = budget)
concat_bytes(ascii_to_bytes(head + "\n"), payload)
}
///| Detached output: (header bytes, payload bytes). The header MUST
///| declare a data file name (host-assigned; the core just repeats it
///| — keeping the name consistent with what the host writes next to
///| the header is the host's responsibility). The header bytes end
///| with the terminating blank line, like an attached header.
pub fn assemble_detached(
h : NrrdHeader,
values : Array[Double],
budget~ : Int = max_encode_elements(),
) -> (Bytes, Bytes) raise NrrdError {
match h.data_file {
None => raise NrrdError(
"detached output requires a data file name (host-assigned)",
)
Some(_) => ()
}
let head = format_header(h)
let payload = encode_data(values, h, budget = budget)
(ascii_to_bytes(head + "\n"), payload)
}