Table of Contents

Struct Symbols

Namespace
DatabentoDotNet
Assembly
DatabentoDotNet.Dbn.dll

The set of symbols a live subscription or a historical query covers: every symbol in the dataset, a list of symbols in some symbology, or a list of numeric instrument IDs.

public readonly struct Symbols : IEquatable<Symbols>
Implements
Inherited Members

Examples

Symbols two = Symbols.From(["AAPL", "MSFT"]);   // raw symbols, the common case
Symbols one = Symbols.From("ESH4");
Symbols ids = Symbols.FromIds([12345u, 67890u]);   // instrument ids
Symbols everything = Symbols.All;                  // the whole dataset

Console.WriteLine(two.ToApiString());   // AAPL,MSFT
Console.WriteLine(two.ChunkCount);      // 1 — the gateway takes 500 symbols per message

// Rejected here, while the offending symbol is still in your hand. The subscription line is
// '|'-separated, so a symbol carrying one would not produce a rejected subscription — it would
// produce a different, well-formed one, silently.
Symbols.From("AA|PL");   // throws ArgumentException

Remarks

Port of upstream's Symbols sum type (databento-rs/src/lib.rs): All, Symbols(Vec<String>), Ids(Vec<u32>). A readonly struct with factories rather than a set of string overloads on Subscribe, because an overload set cannot express "all symbols" — the wire spells that as the literal AllWireValue, and a caller who passes that string by hand has written a magic value the type system cannot check. PORTING.md §2.

Symbols are validated when the set is built, not when it is sent. A subscription line is |-separated with = between key and value and terminated by \n, so a symbol carrying any of those characters does not produce a rejected subscription — it produces a different, well-formed one, silently. That is the failure mode this library exists to turn back into an exception, and the earliest place to do it is here, where the offending symbol is still in the caller's hand.

An empty set is rejected, where upstream panics. Upstream's subscribe takes symbol_chunks.len() - 1 to find the last chunk; for an empty symbol list chunks(500) yields no chunks at all, and that subtraction underflows — a panic in a debug build and an enormous index in a release one. There is no meaningful empty subscription, so the set cannot be built in the first place.

Fields

AllWireValue

The wire value that means every symbol in the dataset.

public const string AllWireValue = "ALL_SYMBOLS"

Field Value

string

ChunkSize

The most symbols the gateway accepts in one subscription message. A larger set is split across several messages, only the last of which is marked is_last=1.

public const int ChunkSize = 500

Field Value

int

Remarks

The boundary is exact and getting it wrong is invisible from the outside: the gateway accepts a 501-symbol message without complaint and simply never subscribes the last symbol. Nothing on the wire says so.

Properties

All

Every symbol in the dataset.

public static Symbols All { get; }

Property Value

Symbols

ChunkCount

How many subscription messages this set takes: one per ChunkSize symbols, and always one for All.

public int ChunkCount { get; }

Property Value

int

Count

How many symbols this set names, or 1 for All.

public int Count { get; }

Property Value

int

Kind

Which of the three forms this set takes.

public SymbolsKind Kind { get; }

Property Value

SymbolsKind

Remarks

None for a default value, which is not a usable set — both ToChunks() and ToApiString() refuse it outright, and the live client's Subscription.Symbols is required so one cannot arrive by omission.

Methods

Equals(Symbols)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Symbols other)

Parameters

other Symbols

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

From(IEnumerable<string>)

A set naming several symbols, in the order given.

public static Symbols From(IEnumerable<string> symbols)

Parameters

symbols IEnumerable<string>

The symbols, in whatever symbology the subscription's stype_in names. Order is kept: it decides which chunk each symbol lands in, and the gateway echoes it back in error messages.

Returns

Symbols

The set.

Exceptions

ArgumentNullException

symbols is null.

ArgumentException

symbols is empty, or one of them is empty, white space, or carries a character the line protocol uses.

From(string)

A set naming one symbol.

public static Symbols From(string symbol)

Parameters

symbol string

The symbol, in whatever symbology the subscription's stype_in names.

Returns

Symbols

The set.

Exceptions

ArgumentException

symbol is empty, white space, or carries a character the line protocol uses.

FromIds(IEnumerable<uint>)

A set naming several numeric instrument IDs, in the order given.

public static Symbols FromIds(IEnumerable<uint> instrumentIds)

Parameters

instrumentIds IEnumerable<uint>

The instrument IDs. Pair them with InstrumentId.

Returns

Symbols

The set.

Exceptions

ArgumentNullException

instrumentIds is null.

ArgumentException

instrumentIds is empty.

FromIds(uint)

A set naming one numeric instrument ID.

public static Symbols FromIds(uint instrumentId)

Parameters

instrumentId uint

The instrument ID. Pair it with InstrumentId.

Returns

Symbols

The set.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

ToApiString()

The symbols= value the historical HTTP API takes: every symbol in the set, joined with commas into a single string, with no chunking.

public string ToApiString()

Returns

string

The rendered value, or AllWireValue for All.

Remarks

Port of upstream's Symbols::to_api_string() (databento-rs/src/lib.rs, called from historical/symbology.rs and historical/timeseries.rs). Unlike ToChunks(), this never splits: ChunkSize is a live line-protocol limit, and an HTTP form field carries no such restriction, so it must never be chunked here even for a set with more than ChunkSize symbols.

Exceptions

InvalidOperationException

This is a default value.

ToArray()

The symbols this set names, in order, in their wire spelling.

public ImmutableArray<string> ToArray()

Returns

ImmutableArray<string>

The symbols, or a single AllWireValue for All.

ToChunks()

The symbols= values this set produces, one per subscription message: comma-separated runs of at most ChunkSize symbols, or a single AllWireValue.

public ImmutableArray<string> ToChunks()

Returns

ImmutableArray<string>

The chunks, in order. Never empty.

Exceptions

InvalidOperationException

This is a default value.

ToString()

A short description, for diagnostics. Long sets are elided rather than dumped.

public override string ToString()

Returns

string

The description.

Operators

operator ==(Symbols, Symbols)

Equality operator.

public static bool operator ==(Symbols left, Symbols right)

Parameters

left Symbols

The left operand.

right Symbols

The right operand.

Returns

bool

true when the two name the same symbols in the same order.

operator !=(Symbols, Symbols)

Inequality operator.

public static bool operator !=(Symbols left, Symbols right)

Parameters

left Symbols

The left operand.

right Symbols

The right operand.

Returns

bool

true when the two differ.

Edit this page