Class CorporateActionsGetRangeParams
- Namespace
- DatabentoDotNet.Reference
- Assembly
- DatabentoDotNet.Reference.dll
The parameter set corporate_actions.get_range takes: which symbols, over what range of
which date, optionally narrowed to a set of events, countries, exchanges or security types.
public sealed record CorporateActionsGetRangeParams : IEquatable<CorporateActionsGetRangeParams>- Inheritance
-
CorporateActionsGetRangeParams
- Implements
- Inherited Members
Remarks
Port of upstream's corporate::GetRangeParams (corporate.rs:124-167). Named for its
endpoint rather than as a bare GetRangeParams, for the reason
AdjustmentFactorsGetRangeParams records: upstream can reuse that name in three
modules of one crate and C# cannot reuse it in one namespace.
The widest filter set in this namespace — four lists where the other two endpoints have two. Events and Exchanges exist only here, because only this endpoint returns rows that have an event and a listing exchange to filter on. All four behave alike: null or empty means the parameter is left out entirely rather than sent blank.
compression is not a property, because it is not a choice. Upstream hard-codes
compression=zstd (corporate.rs:42) and so does ToFormParameters(). The
response handler requires the frame — an uncompressed body would not parse — so a caller who
could set it could only break the request.
Properties
AllocateIsins
Whether the request may allocate new ISINs on an ISIN-limited plan. Defaults to true, as upstream's builder does.
public bool AllocateIsins { get; init; }Property Value
Remarks
A billing consequence hiding in a default: left alone, a request for symbols the plan has not
seen before can create new allocations against an ISIN-limited entitlement
(corporate.rs:163-167). Set it false and the API drops the rows that
would have done so rather than returning them. The default is upstream's and is kept, for the
reason AllocateIsins gives at length — that is the
endpoint where it bites hardest, and this property is the same decision.
No test that reaches the real API may leave this true without going through #57's gate. That is a rule about spending someone's entitlement, not a style preference.
Countries
The countries to filter for, or null to include every country.
public IReadOnlyList<Country>? Countries { get; init; }Property Value
Remarks
DateTimeRange
The request range: inclusive start, optional exclusive end.
public required ReferenceDateTimeRange DateTimeRange { get; init; }Property Value
Remarks
Filters on Index — which is what makes that property a request parameter here rather than a presentation choice. Omit the end and the response runs to the end of the data; see ReferenceDateTimeRange, which also records that the exclusive end is documented rather than probed.
Events
The event types to filter for, or null to include every event.
public IReadOnlyList<Event>? Events { get; init; }Property Value
Remarks
An open carrier, so a code this library has never seen still reaches the server. That
is the case #51 made Event a readonly record struct for rather than an
enum: a caller who read an unrecognised event code out of a response —
where Event keeps it verbatim — can turn round and filter on
it. A plain C# enum would have nothing to put in the list.
An empty sequence means the same thing as null: the parameter is left out. A default Event in the list is a caller mistake and is refused — see Render<T>(IEnumerable<T>?).
Exchanges
The listing exchanges to filter for, or null to include every exchange.
public IReadOnlyList<string>? Exchanges { get; init; }Property Value
Remarks
Bare strings, not a code type, and that is not an omission. list_enums reports
no group for exchange codes, so there is no dictionary to close over and nothing for an
IReferenceCode<TSelf> to be open against — Exchange
is a string for the same reason. A blank entry is refused rather than dropped;
see Render(IEnumerable<string>?).
Index
Which date DateTimeRange applies to. Defaults to EventDate, as upstream's builder does.
public CorporateActionIndex Index { get; init; }Property Value
Remarks
It changes which rows come back, not their order: upstream also sorts its buffered response
by it (corporate.rs:59-63) and GetRangeAsync(CorporateActionsGetRangeParams, CancellationToken)
streams, so the sort is not performed here. See CorporateActionIndex, which
also notes that two of the three name a nullable column.
SecurityTypes
The security types to filter for, or null to include every type.
public IReadOnlyList<SecurityType>? SecurityTypes { get; init; }Property Value
Remarks
StypeIn
public SType StypeIn { get; init; }Property Value
Symbols
The symbols to filter for.
public required Symbols Symbols { get; init; }Property Value
Methods
ToFormParameters()
Renders this parameter set as the form body corporate_actions.get_range posts.
public IReadOnlyList<KeyValuePair<string, string>> ToFormParameters()Returns
- IReadOnlyList<KeyValuePair<string, string>>
The form fields, in upstream's push order.
Remarks
The order is upstream's push order (corporate.rs:37-50), which is not the order the
properties are declared in: index leads, stype_in precedes symbols,
allocate_isins and compression sit before the range, and the four optional
filters come last in the order events, countries, exchanges,
security_types. It makes no difference to the API and it makes the rendered body
byte-comparable with upstream's, which is the cheapest way to tell this rendering apart from
a plausible one.
The five fields this shares with the other three reference renderers are written out here
too, and that is #55 answering the question ToFormParameters()
left it. The four bodies do share a contiguous {stype_in, symbols, allocate_isins,
compression} core, with index prepended by two of them. A helper for that core
would still leave each caller assembling around it, so a reader asking "what goes on the
wire for this endpoint" would need two files instead of one — and being readable in one place
is the whole value of these methods, which is also what their per-endpoint tests assert
against. Four explicit lists it is. SubmitJobParams
keeps its own Boolean helper private for the same reason.
For a request with no event, country, exchange or security-type filter and an open range,
the key set is exactly {index, stype_in, symbols, allocate_isins, compression, start}
— six fields, with nothing sent empty.
Exceptions
- InvalidOperationException
Symbols or DateTimeRange is left at its type's default value. required forces a caller to assign each property but does not stop them assigning default, and the accessors this reads refuse to render one.
- ArgumentException
A default Event, Country or SecurityType, or a blank exchange, appears in a filter list.
- ArgumentOutOfRangeException
Index is not a defined CorporateActionIndex.