Package zeroecho.core.marshal

Class PairSeq

java.lang.Object

zeroecho.core.marshal.PairSeq

public final class PairSeq
extends Object

Immutable sequence of string key-value pairs with cursor-based iteration and simple text serialization.

A PairSeq stores pairs in a flat String[] array representation: [k0, v0, k1, v1, ...]. It is designed for compact transport of structured metadata where keys and values are UTF-8–safe strings (binary data should be Base64 encoded before storing).

Usage

 PairSeq seq = PairSeq.of("type", "SntruPrimePublicKeySpec",
                          "x509.b64", "BASE64ENCODED");

 for (PairSeq.Cursor c = seq.cursor(); c.next();) {
     System.out.println(c.key() + " = " + c.value());
 }
 

Serialization

• writeTo(Appendable) outputs each pair as k=v\n lines without escaping.
• readFrom(java.io.Reader) parses lines in the same format, ignoring blank lines and comments starting with #.

Thread-safety

Instances are immutable and safe to share across threads. The PairSeq.Cursor is not thread-safe and should be confined to a single thread.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	PairSeq.Cursor	Forward-only iterator over the pairs of a PairSeq.

Method Summary

Modifier and Type	Method	Description
PairSeq.Cursor	cursor()	Returns a forward-only cursor for iterating the pairs.
String	keyAt(int i)	Returns the key at the given index.
static PairSeq	of(String... kv)	Creates a new sequence from an even-length list of keys and values.
static PairSeq	readFrom(Reader reader)	Reads a PairSeq from a line-based text format.
int	size()	Returns the number of key-value pairs in this sequence.
String	valAt(int i)	Returns the value at the given index.
void	writeTo(Appendable out)	Appends all pairs to the target as key=value lines.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

of

public static PairSeq of(String... kv)

Creates a new sequence from an even-length list of keys and values.

Parameters:

kv - alternating key and value strings; must have even length

Returns:

new PairSeq with the given contents

Throws:

IllegalArgumentException - if kv is null or has odd length

size

public int size()

Returns the number of key-value pairs in this sequence.

Returns:

pair count

keyAt

public String keyAt(int i)

Returns the key at the given index.

Parameters:

i - index of the pair (0-based)

Returns:

key string

Throws:

ArrayIndexOutOfBoundsException - if i is out of range

valAt

public String valAt(int i)

Returns the value at the given index.

Parameters:

i - index of the pair (0-based)

Returns:

value string

Throws:

ArrayIndexOutOfBoundsException - if i is out of range

cursor

public PairSeq.Cursor cursor()

Returns a forward-only cursor for iterating the pairs.

Returns:

new cursor over this sequence

writeTo

public void writeTo(Appendable out)

Appends all pairs to the target as key=value lines.

No escaping is performed; callers must ensure keys and values do not contain newlines. Binary data should be stored as Base64.

Parameters:

out - appendable target

Throws:

UncheckedIOException - if the append fails

readFrom

public static PairSeq readFrom(Reader reader)
                        throws IOException

Reads a PairSeq from a line-based text format.

Each non-empty, non-comment line must have the form key=value. Lines without an equals sign or with empty keys are skipped. Comments start with #.

Parameters:

reader - character source

Returns:

parsed PairSeq

Throws:

IOException - if reading fails