Error behavior is consistent and follows the overload form. Length = 0 is always handled gracefully — every operation short-circuits on an empty source or target and copies the length through, so there is no Length > 0 precondition anywhere in the API.
Rule 1: In-place (0-arg form)
- Behavior: Modifies self in-place. Empty self (
Length = 0) is a no-op. - Example:
self.Sin()— operates on the elements self already holds.
Rule 2: Transform (1-arg form) — SAFEST
- Behavior: Auto-resizes self to match source dimensions. If the source is empty, self is also resized to length 0 (the empty length is copied, not rejected).
- Remark pattern: "Size and Complex properties of calling object are adjusted automatically."
- Example:
self.Sin(X)— self is resized to match X.
Rule 3: Indexed forms
- Precondition: Valid index + length within array bounds.
- Behavior: Raises
EMtxVecRangeErroron array border overrun. - Remark pattern: "An exception is raised if array borders are overrun."
- Example:
self.Sin(X, XIndex, Len, DstIndex)— all indices must be valid.
Summary:
| Form | Precondition | Self resize? | Empty-length behavior | Error on violation |
|---|---|---|---|---|
self.Op() | none | No | no-op | none |
self.Op(X) | none | Yes (auto) | resizes self to 0 | none |
self.Op(X, idx, len, ...) | valid indices | No | no-op when len = 0 | EMtxVecRangeError on out-of-range |
Recommendation: Prefer the 1-arg form when possible — it auto-resizes and is safest.