Class Iso8211FieldReader

Namespace

EncDotNet.Iso8211

Assembly

EncDotNet.Iso8211.dll

Reads and extracts subfield values from ISO 8211 field data using the field's definition from the DDR.

public sealed class Iso8211FieldReader

Inheritance

object

Iso8211FieldReader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

var ddr = Iso8211DdrParser.Parse(ddrRecord);
var fieldDef = ddr.GetFieldDefinition("DSID");
var reader = new Iso8211FieldReader(fieldDef, fieldData);

var recordName = reader.GetSubfield<byte>("RCNM");
var recordId = reader.GetSubfield<int>("RCID");
var dataSetName = reader.GetSubfield<string>("DSNM");

Remarks

The Iso8211FieldReader provides a high-level interface for extracting typed subfield values from raw ISO 8211 field data. It uses the field definition from the Data Descriptive Record (DDR) to understand the structure and format of each subfield.

The reader eagerly parses all subfield boundaries upon construction, which simplifies handling of variable-width subfields. Actual value conversion is performed lazily when GetSubfield<T>(string) or similar methods are called.

For fields with repeating subfield groups, use GetSubfieldValues<T>(string) to retrieve all values, or GetSubfieldGroups() to iterate over each group.

Constructors

Iso8211FieldReader(Iso8211FieldDefinition, byte[], int)

Initializes a new instance of the Iso8211FieldReader class.

public Iso8211FieldReader(Iso8211FieldDefinition fieldDefinition, byte[] data, int lexicalLevel = 0)

Parameters

fieldDefinition Iso8211FieldDefinition

The field definition from the DDR describing this field's structure.

data byte[]

The raw field data to read. The reader reads the array in place, without copying it.

lexicalLevel int

The lexical level for character data (0 or 1 = ASCII/ISO 8859, 2 = UCS-2/UTF-16LE). When set to 2, variable-length character subfields use 2-byte terminators (0x1F 0x00 / 0x1E 0x00).

Exceptions

ArgumentNullException

Thrown when fieldDefinition or data is null.

Iso8211FieldReader(Iso8211FieldDefinition, ReadOnlyMemory<byte>, int)

Initializes a new instance of the Iso8211FieldReader class.

public Iso8211FieldReader(Iso8211FieldDefinition fieldDefinition, ReadOnlyMemory<byte> data, int lexicalLevel = 0)

Parameters

fieldDefinition Iso8211FieldDefinition

The field definition from the DDR describing this field's structure.

data ReadOnlyMemory<byte>

The raw field data to read, such as an Data. The reader reads it in place, without copying it.

lexicalLevel int

The lexical level for character data (0 or 1 = ASCII/ISO 8859, 2 = UCS-2/UTF-16LE). When set to 2, variable-length character subfields use 2-byte terminators (0x1F 0x00 / 0x1E 0x00).

Exceptions

ArgumentNullException

Thrown when fieldDefinition is null.

Iso8211FieldReader(Iso8211FieldDefinition, ReadOnlySpan<byte>, int)

Initializes a new instance of the Iso8211FieldReader class.

public Iso8211FieldReader(Iso8211FieldDefinition fieldDefinition, ReadOnlySpan<byte> data, int lexicalLevel = 0)

Parameters

fieldDefinition Iso8211FieldDefinition

The field definition from the DDR describing this field's structure.

data ReadOnlySpan<byte>

The raw field data to read. The reader keeps its own copy.

lexicalLevel int

The lexical level for character data (0 or 1 = ASCII/ISO 8859, 2 = UCS-2/UTF-16LE). When set to 2, variable-length character subfields use 2-byte terminators (0x1F 0x00 / 0x1E 0x00).

Exceptions

ArgumentNullException

Thrown when fieldDefinition is null.

Properties

Data

Gets the raw field data.

public ReadOnlySpan<byte> Data { get; }

Property Value

ReadOnlySpan<byte>

FieldDefinition

Gets the field definition used by this reader.

public Iso8211FieldDefinition FieldDefinition { get; }

Property Value

Iso8211FieldDefinition

GroupCount

Gets the number of subfield groups (repetitions) in this field.

public int GroupCount { get; }

Property Value

int

Remarks

For fields without repeating groups, this will be 1. For fields with repeating groups, this is the number of times the group repeats. A final repetition cut short by the end of the field data is not counted.

HasRepeatingGroups

Gets whether this field has repeating subfield groups.

public bool HasRepeatingGroups { get; }

Property Value

bool

SubfieldCount

Gets the number of parsed subfield instances.

public int SubfieldCount { get; }

Property Value

int

Remarks

For fields with repeating groups, this count includes all instances across all repetitions.

Methods

GetFixedSubfield<T>(string)

Gets the value of a non-repeating (fixed) subfield by name.

public T GetFixedSubfield<T>(string name)

Parameters

name string

The name of the subfield to retrieve.

Returns

T

The subfield value converted to type T.

Type Parameters

T

The type to convert the subfield value to.

Remarks

This method is equivalent to GetSubfield<T>(string) but is semantically clearer when used with fields that have both fixed and repeating subfields.

GetOrdinal(string)

Gets the ordinal of a subfield: its position in the field definition's SubfieldDefinitions.

public int GetOrdinal(string name)

Parameters

name string

The subfield name, such as "YCOO".

Returns

int

The zero-based ordinal of the first subfield with that name.

Examples

var reader = new Iso8211FieldReader(ddr.GetFieldDefinition("SG2D")!, field.Data);
var y = reader.GetOrdinal("YCOO");
var x = reader.GetOrdinal("XCOO");
for (var group = 0; group < reader.GroupCount; group++)
{
    points.Add((reader.GetSubfield<int>(group, y), reader.GetSubfield<int>(group, x)));
}

Remarks

Look the ordinal up once and pass it to GetSubfield<T>(int, int) to read many repetitions of a group without repeating the name lookup for each one.

Exceptions

KeyNotFoundException

Thrown when the field definition has no subfield with the specified name.

GetSubfieldAt<T>(int)

Gets the value of a subfield at a specific index.

public T GetSubfieldAt<T>(int index)

Parameters

index int

The index of the parsed subfield.

Returns

T

The subfield value converted to type T.

Type Parameters

T

The type to convert the subfield value to.

Exceptions

ArgumentOutOfRangeException

Thrown when index is outside the valid range.

GetSubfieldBytes(int, int)

Gets the raw bytes of a subfield in one repetition of the field's repeating group.

public ReadOnlySpan<byte> GetSubfieldBytes(int groupIndex, int ordinal)

Parameters

groupIndex int

The zero-based repetition.

ordinal int

The subfield's ordinal, from GetOrdinal(string).

Returns

ReadOnlySpan<byte>

A span containing the raw subfield data.

Exceptions

ArgumentOutOfRangeException

Thrown when ordinal is not a subfield of the repeating group, or the field data has no such repetition.

GetSubfieldBytes(string)

Gets the raw bytes of a subfield by name.

public ReadOnlySpan<byte> GetSubfieldBytes(string name)

Parameters

name string

The name of the subfield to retrieve.

Returns

ReadOnlySpan<byte>

A span containing the raw subfield data.

Remarks

For repeating subfields, this returns the bytes from the first occurrence. Use GetSubfieldBytes(int, int) or GetSubfieldBytes(string) to retrieve bytes for a specific group.

Exceptions

KeyNotFoundException

Thrown when no subfield with the specified name exists.

GetSubfieldBytesAt(int)

Gets the raw bytes of a subfield at a specific index.

public ReadOnlySpan<byte> GetSubfieldBytesAt(int index)

Parameters

index int

The index of the parsed subfield.

Returns

ReadOnlySpan<byte>

A span containing the raw subfield data.

Exceptions

ArgumentOutOfRangeException

Thrown when index is outside the valid range.

GetSubfieldGroups()

Enumerates groups of repeating subfields.

public IEnumerable<Iso8211SubfieldGroup> GetSubfieldGroups()

Returns

IEnumerable<Iso8211SubfieldGroup>

An enumerable of Iso8211SubfieldGroup instances, one for each repetition of the repeating subfield group.

Remarks

For fields without repeating groups, this returns a single group containing all subfields. Unlike GroupCount, the enumeration includes a final repetition cut short by the end of the field data. To read many repetitions without allocating a group object for each, use GetOrdinal(string) with GetSubfield<T>(int, int).

GetSubfieldValues<T>(string)

Gets all values of a repeating subfield by name.

public ImmutableArray<T> GetSubfieldValues<T>(string name)

Parameters

name string

The name of the subfield to retrieve.

Returns

ImmutableArray<T>

An immutable array containing all values of the specified subfield.

Type Parameters

T

The type to convert the subfield values to.

Exceptions

KeyNotFoundException

Thrown when no subfield with the specified name exists in the field definition.

GetSubfield<T>(int, int)

Gets the value of a subfield in one repetition of the field's repeating group.

public T GetSubfield<T>(int groupIndex, int ordinal)

Parameters

groupIndex int

The zero-based repetition, from 0 to GroupCount - 1. For a field without a repeating group, the only repetition is 0.

ordinal int

The subfield's ordinal, from GetOrdinal(string).

Returns

T

The subfield value converted to type T.

Type Parameters

T

The type to convert the subfield value to.

Exceptions

ArgumentOutOfRangeException

Thrown when ordinal is not a subfield of the repeating group, or the field data has no such repetition.

InvalidOperationException

Thrown when the subfield value cannot be converted to the requested type.

GetSubfield<T>(string)

Gets the value of a subfield by name.

public T GetSubfield<T>(string name)

Parameters

name string

The name of the subfield to retrieve.

Returns

T

The subfield value converted to type T.

Type Parameters

T

The type to convert the subfield value to. Supported types include: byte, sbyte, short, ushort, int, uint, long, ulong, float, double, and string.

Remarks

For repeating subfields, this returns the value from the first occurrence. Use GetSubfieldValues<T>(string) to retrieve all values.

Exceptions

KeyNotFoundException

Thrown when no subfield with the specified name exists.

InvalidOperationException

Thrown when the subfield value cannot be converted to the requested type.

TryGetSubfield<T>(int, int, out T)

Tries to get the value of a subfield in one repetition of the field's repeating group.

public bool TryGetSubfield<T>(int groupIndex, int ordinal, out T value)

Parameters

groupIndex int

The zero-based repetition.

ordinal int

The subfield's ordinal, from GetOrdinal(string).

value T

When this method returns, contains the subfield value if present; otherwise, the default value.

Returns

bool

true if the repetition contains the subfield; false if ordinal is not in the repeating group or the field data ends before it.

Type Parameters

T

The type to convert the subfield value to.

TryGetSubfield<T>(string, out T)

Tries to get the value of a subfield by name.

public bool TryGetSubfield<T>(string name, out T value)

Parameters

name string

The name of the subfield to retrieve.

value T

When this method returns, contains the subfield value if found; otherwise, the default value.

Returns

bool

true if the subfield was found; otherwise, false.

Type Parameters

T

The type to convert the subfield value to.