docs: document MxSparseArray default-fill writes and bare-name array AddItem

This commit is contained in:
Joseph Doherty
2026-06-18 03:00:19 -04:00
parent 95b5b09a67
commit db9c68ca9c
2 changed files with 89 additions and 1 deletions
+14
View File
@@ -75,6 +75,20 @@ private static MxValue CreateNullValue(
}
```
### Sparse array expansion (write path, gateway only)
`MxSparseArray` — the `sparse_array_value` arm on `MxValue` — is a write-only
shorthand. The worker never produces or receives it; the gateway expands it into
a full `MxArray` before the command reaches the named pipe. Expansion allocates
a complete array of `total_length` slots, initializes every slot to the element
type's default (bool → `false`; numeric → `0`; string → `""`; time/timestamp →
Unix epoch), then writes each `MxSparseElement` at its declared index. The
resulting `array_value` is an ordinary `MxArray` that passes through the
conversion layer unchanged. The worker therefore still performs a single
whole-array COM write, preserving MXAccess parity. Unmentioned indices are
**reset** to their type default, not preserved from prior state — there is no
read-modify-write merge.
### Array projection
`ConvertArray` records the rank and per-dimension lengths so multi-dimensional `SAFEARRAY` shapes survive the round trip. The element type is resolved from the caller-supplied hint or the CLR element type via `ResolveArrayElementDataType`, then dispatched to the matching typed builder (`ConvertBoolArray`, `ConvertInt64Array`, `ConvertTimestampArray`, and so on).