PDComm.SecsItem

Class

An immutable SECS-II (SEMI E5) data item held in native memory: a list or a typed primitive value array.

public sealed class SecsItem : IDisposable

Create items with the From* factories, SecsItem.Primitive, SecsItem.CreateList or SecsItem.Decode. Every factory checks the item against a SecsLimits before memory is committed.

Each SecsItem owns its native memory; dispose it when you are done. A finalizer releases it if you forget. Items returned by SecsItem.GetChild, by GEM results and by other PDComm APIs are new, independent copies that the caller also owns: disposing a parent does not invalidate its children, and creating a list copies the children, which stay owned by the caller.

Read methods may run concurrently from several threads. Disposal waits for in-flight reads before the native memory is released.

var limits = new SecsLimits(4096, 1024, 32, 8);
using var label = SecsItem.FromAscii("Temperature", limits);
using var values = SecsItem.FromF8(new double[] { 23.5, -0.0 }, limits);
using var source = SecsItem.CreateList(new[] { label, values }, limits);
byte[] encoded = source.Encode();
using var decoded = SecsItem.Decode(encoded, limits);
using var decodedLabel = decoded.GetChild(0);
Console.WriteLine(decodedLabel.GetAscii());

Members

`CreateList`

Method

Creates a list item from copies of existing items.

public static SecsItem CreateList(ReadOnlySpan<SecsItem> children, SecsLimits limits)

Parameters

Name	Description
`children`	The child items, in order; may be empty. They are copied and stay owned by the caller.
`limits`	The limits the new list, including every copied child, must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws ArgumentException: An element of children is null.
Throws ObjectDisposedException: A child item has been disposed.
Throws PdcommException: The list exceeds limits (PdcommStatus.LimitExceeded).

`Decode`

Method

Decodes exactly one encoded SECS-II item.

public static SecsItem Decode(ReadOnlySpan<byte> data, SecsLimits limits)

Parameters

Name	Description
`data`	The encoded item: format byte, length bytes and payload, with no trailing bytes.
`limits`	The limits the decoded item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The input is incomplete (PdcommStatus.Truncated), malformed or followed by extra bytes (PdcommStatus.InvalidData), or exceeds limits (PdcommStatus.LimitExceeded). PdcommException.ErrorOffset identifies the start of the field that failed.

`Dispose`

Method

Releases the item's native memory.

public void Dispose()

Calling this method more than once has no effect. Items copied from this one stay valid.

`Encode`

Method

Encodes the item in SECS-II wire format.

public byte[] Encode()

Returns

A new array with the encoded item. Length headers use the minimal size; payload bytes are preserved.

Notes

Throws ObjectDisposedException: The item has been disposed.
Throws PdcommException: The native encoder failed.

`FromAscii`

Method

Creates an SecsFormat.Ascii item from text.

public static SecsItem FromAscii(string value, SecsLimits limits)

Parameters

Name	Description
`value`	The text; every character must be 7-bit ASCII (U+0000 to U+007F).
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws ArgumentNullException: value is null.
Throws ArgumentException: value contains a character above U+007F.
Throws PdcommException: The text exceeds limits (PdcommStatus.LimitExceeded).

`FromBinary`

Method

Creates a SecsFormat.Binary item from raw bytes.

public static SecsItem FromBinary(ReadOnlySpan<byte> values, SecsLimits limits)

Parameters

Name	Description
`values`	The bytes to store; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded).

`FromBoolean`

Method

Creates a SecsFormat.Boolean item from Boolean values, one byte each (1 for true, 0 for false).

public static SecsItem FromBoolean(ReadOnlySpan<bool> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromF4`

Method

Creates a SecsFormat.F4 item from Single IEEE 754 values, big-endian.

public static SecsItem FromF4(ReadOnlySpan<float> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromF8`

Method

Creates a SecsFormat.F8 item from Double IEEE 754 values, big-endian.

public static SecsItem FromF8(ReadOnlySpan<double> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromI1`

Method

Creates a SecsFormat.I1 item from SByte signed integers.

public static SecsItem FromI1(ReadOnlySpan<sbyte> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromI2`

Method

Creates a SecsFormat.I2 item from Int16 signed integers, big-endian.

public static SecsItem FromI2(ReadOnlySpan<short> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromI4`

Method

Creates a SecsFormat.I4 item from Int32 signed integers, big-endian.

public static SecsItem FromI4(ReadOnlySpan<int> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromI8`

Method

Creates a SecsFormat.I8 item from Int64 signed integers, big-endian.

public static SecsItem FromI8(ReadOnlySpan<long> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromJis8`

Method

Creates a SecsFormat.Jis8 item from JIS-8 encoded bytes.

public static SecsItem FromJis8(ReadOnlySpan<byte> values, SecsLimits limits)

Parameters

Name	Description
`values`	The JIS-8 bytes, stored unchanged; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded).

`FromU1`

Method

Creates a SecsFormat.U1 item from Byte unsigned integers.

public static SecsItem FromU1(ReadOnlySpan<byte> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromU2`

Method

Creates a SecsFormat.U2 item from UInt16 unsigned integers, big-endian.

public static SecsItem FromU2(ReadOnlySpan<ushort> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromU4`

Method

Creates a SecsFormat.U4 item from UInt32 unsigned integers, big-endian.

public static SecsItem FromU4(ReadOnlySpan<uint> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`FromU8`

Method

Creates a SecsFormat.U8 item from UInt64 unsigned integers, big-endian.

public static SecsItem FromU8(ReadOnlySpan<ulong> values, SecsLimits limits)

Parameters

Name	Description
`values`	The values to encode, in order; may be empty.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws PdcommException: The payload exceeds limits (PdcommStatus.LimitExceeded), checked before any native memory is allocated.

`GetAscii`

Method

Reads the text of an ASCII item.

public string GetAscii()

Returns

The item's characters, one per payload byte.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.Ascii.
Throws ObjectDisposedException: The item has been disposed.

`GetBinary`

Method

Reads the values of a Binary item as raw bytes.

public byte[] GetBinary()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.Binary.
Throws ObjectDisposedException: The item has been disposed.

`GetBoolean`

Method

Reads the values of a Boolean item as Boolean values; any nonzero byte is true.

public bool[] GetBoolean()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.Boolean.
Throws ObjectDisposedException: The item has been disposed.

`GetChild`

Method

Copies one child of a list item.

public SecsItem GetChild(nuint index)

Parameters

Name	Description
`index`	The zero-based position of the child.

Returns

A new, independent item that the caller owns and must dispose.

Notes

Throws ObjectDisposedException: The item has been disposed.
Throws PdcommException: The item is not a list (PdcommStatus.InvalidArgument), or index is not less than the list's SecsInfo.Count (PdcommStatus.OutOfRange).

`GetF4`

Method

Reads the values of an F4 item as Single values.

public float[] GetF4()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.F4.
Throws ObjectDisposedException: The item has been disposed.

`GetF8`

Method

Reads the values of an F8 item as Double values.

public double[] GetF8()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.F8.
Throws ObjectDisposedException: The item has been disposed.

`GetI1`

Method

Reads the values of an I1 item as SByte values.

public sbyte[] GetI1()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.I1.
Throws ObjectDisposedException: The item has been disposed.

`GetI2`

Method

Reads the values of an I2 item as Int16 values.

public short[] GetI2()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.I2.
Throws ObjectDisposedException: The item has been disposed.

`GetI4`

Method

Reads the values of an I4 item as Int32 values.

public int[] GetI4()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.I4.
Throws ObjectDisposedException: The item has been disposed.

`GetI8`

Method

Reads the values of an I8 item as Int64 values.

public long[] GetI8()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.I8.
Throws ObjectDisposedException: The item has been disposed.

`GetInfo`

Method

Gets the item's format, element count, encoded size and tree shape.

public SecsInfo GetInfo()

Returns

The item's shape.

Notes

Throws ObjectDisposedException: The item has been disposed.

`GetJis8`

Method

Reads the values of a Jis8 item as its JIS-8 bytes, unchanged.

public byte[] GetJis8()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.Jis8.
Throws ObjectDisposedException: The item has been disposed.

`GetPayload`

Method

Copies the raw payload bytes of a primitive item.

public byte[] GetPayload()

Returns

A new array with the payload exactly as encoded on the wire (big-endian for numeric formats).

Notes

Throws ObjectDisposedException: The item has been disposed.
Throws PdcommException: The item is a list (PdcommStatus.InvalidArgument).

`GetU1`

Method

Reads the values of a U1 item as Byte values.

public byte[] GetU1()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.U1.
Throws ObjectDisposedException: The item has been disposed.

`GetU2`

Method

Reads the values of a U2 item as UInt16 values.

public ushort[] GetU2()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.U2.
Throws ObjectDisposedException: The item has been disposed.

`GetU4`

Method

Reads the values of a U4 item as UInt32 values.

public uint[] GetU4()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.U4.
Throws ObjectDisposedException: The item has been disposed.

`GetU8`

Method

Reads the values of a U8 item as UInt64 values.

public ulong[] GetU8()

Returns

A new array with the decoded values; empty when the item has no values.

Notes

Throws InvalidOperationException: The item's format is not SecsFormat.U8.
Throws ObjectDisposedException: The item has been disposed.

`Primitive`

Method

Creates a primitive item from its raw payload bytes.

public static SecsItem Primitive(SecsFormat format, ReadOnlySpan<byte> data, SecsLimits limits)

Parameters

Name	Description
`format`	The item format; any format except `SecsFormat.List`.
`data`	The payload bytes, exactly as they appear on the wire: big-endian for numeric formats, a whole number of elements for the format's width, and only 7-bit characters for `SecsFormat.Ascii`.
`limits`	The limits the new item must satisfy.

Returns

A new item that the caller owns and must dispose.

Notes

Throws ArgumentException: format is SecsFormat.List.
Throws PdcommException: format is not a SECS-II format code (PdcommStatus.InvalidArgument), the payload does not fit the format (PdcommStatus.InvalidData), or it exceeds limits (PdcommStatus.LimitExceeded).

`TryCopyPayload`

Method

Copies the raw payload bytes of a primitive item into a caller-supplied span when it is large enough.

public bool TryCopyPayload(Span<byte> destination, out nuint required)

Parameters

Name	Description
`destination`	The span that receives the payload.
`required`	When this method returns, the payload size in bytes.

Returns

true if the payload was copied; false if destination is too small, in which case it is left unchanged.

Notes

Throws ObjectDisposedException: The item has been disposed.
Throws PdcommException: The item is a list (PdcommStatus.InvalidArgument).

`TryEncode`

Method

Encodes the item into a caller-supplied span when it is large enough.

public bool TryEncode(Span<byte> destination, out nuint required)

Parameters

Name	Description
`destination`	The span that receives the encoded item.
`required`	When this method returns, the encoded size in bytes.

Returns

true if the item was encoded; false if destination is too small, in which case it is left unchanged.

Notes

Throws ObjectDisposedException: The item has been disposed.
Throws PdcommException: The native encoder failed for a reason other than a short destination.