3.4 Output Routines
3.4.1 Defining a Layout
Definitions are ordinary value objects. A LayoutBuilder validates names, types, dimensions, fixed
parameter values, data options, and the protocol version when build is called. For example:
sdds::DataOptions data;
data.mode = sdds::DataMode::Binary;
data.majorOrder = sdds::MajorOrder::Row;
sdds::ParameterDefinition step;
step.name = "Step";
step.type = sdds::Type::Int32;
sdds::ColumnDefinition position;
position.name = "x";
position.units = "m";
position.type = sdds::Type::Double;
sdds::LayoutBuilder builder;
builder.setDescription("example data", "SDDS++ example")
.setDataOptions(data)
.addParameter(step)
.addColumn(position);
sdds::Layout layout = builder.build();
ParameterDefinition, ArrayDefinition, and ColumnDefinition contain the metadata fields
described in Section 1.1. AssociateDefinition represents an associate header command. SDDS++
selects an output protocol version that is at least WriterOptions::minimumVersion and is sufficient for
the features and types in the layout.
3.4.2 Writing Pages
- Writer::create — Creates or replaces a path-backed data set.
- Writer::toStdout — Writes an SDDS stream to standard output.
- Writer::toSink — Writes to an application-provided OutputSink.
- beginPage — Starts a page that will be populated field by field.
- setParameter, setArray, and setColumn — Set values on the active page with layout and
type validation.
- commitPage — Validates and writes the active page.
- write — Writes a complete Page; overloads permit copying or moving the page values.
A complete output loop has the following form:
auto writer = sdds::Writer::create("output.sdds", layout);
for (std::int32_t stepNumber = 0; stepNumber != 10; ++stepNumber) {
std::vector<double> x = generatePositions(stepNumber);
writer.beginPage(static_cast<std::int64_t>(x.size()));
writer.setParameter("Step", stepNumber);
writer.setColumn("x", std::move(x));
writer.commitPage();
}
writer.close();
setColumn also accepts a starting row and can extend an internal column in place. This is useful when
data arrives in blocks. All required page values and compatible row counts must be present when
commitPage is called. As with Reader, the Writer destructor closes an open object, while explicit close
reports finalization errors directly.