fcb::FcbWriter Class Reference

Streaming writer for one .fcb file, mirroring Rust's own FcbWriter (writer/mod.rs) shape: each add_feature call encodes and spools that feature's bytes to a private temporary file rather than keeping every encoded feature in memory at once – the same reason Rust's own writer uses the tempfile crate. More...

#include <fcb/writer/fcb_writer.hpp>

Public Member Functions
	FcbWriter (nlohmann::ordered_json cj, FcbWriterOptions options, AttributeSchema attr_schema, std::optional< AttributeSchema > semantic_attr_schema)
	cj is the CityJSONSeq's metadata line (first line: type/ version/transform/metadata/etc).
	~FcbWriter ()
	FcbWriter (const FcbWriter &)=delete
FcbWriter &	operator= (const FcbWriter &)=delete
	FcbWriter (FcbWriter &&)=delete
FcbWriter &	operator= (FcbWriter &&)=delete
void	add_feature (const nlohmann::ordered_json &city_json_feature)
	Encodes and spools one CityJSONFeature line.
void	write (std::ostream &out)
	Finalizes the file: hilbert-sorts features by bbox (unless options.write_index is false or no features were added), builds the spatial and attribute indices, and streams the complete byte sequence – magic bytes, header, R-tree, attribute indices, features, in that order, byte-identical to what FcbWriter::write (writer/mod.rs:191-278) produces for the same input – to out, copying feature bytes from the spool file in fixed-size chunks rather than materializing them all at once.
std::vector< std::uint8_t >	write ()
	Convenience wrapper around write(std::ostream&) that returns the complete file as one buffer.

Detailed Description

Streaming writer for one .fcb file, mirroring Rust's own FcbWriter (writer/mod.rs) shape: each add_feature call encodes and spools that feature's bytes to a private temporary file rather than keeping every encoded feature in memory at once – the same reason Rust's own writer uses the tempfile crate.

This keeps PEAK memory during accumulation to roughly one feature at a time, regardless of how many features are added, so a caller that itself streams its CityJSONSeq input (parsing one line, calling add_feature, discarding the parsed JSON) never needs the whole input in memory either.

The write(std::ostream&) overload preserves that property all the way through finalization: it streams each feature's bytes from the spool straight to out in fixed-size chunks, so finalizing never holds more than one chunk of feature data in memory. The write() overload returning std::vector<std::uint8_t> is a convenience wrapper for smaller files/tests and does NOT have that property – it necessarily materializes the complete output in memory, since that is what its return type requires. Use the ostream overload (writing to an std::ofstream opened on the real output path) for anything where output size matters.

Usage:

FcbWriter w(std::move(cj_metadata), options, std::move(attr_schema), std::nullopt);
for (const auto& feature : features) w.add_feature(feature);
std::ofstream out("result.fcb", std::ios::binary);
w.write(out);

Not copyable or movable: it owns a live handle to its temp file for its entire lifetime, closed and removed only in the destructor.

Definition at line 70 of file fcb_writer.hpp.

Constructor & Destructor Documentation

FcbWriter() [1/3]

fcb::FcbWriter::FcbWriter	(	nlohmann::ordered_json	cj,
		FcbWriterOptions	options,
		AttributeSchema	attr_schema,
		std::optional< AttributeSchema >	semantic_attr_schema
	)

cj is the CityJSONSeq's metadata line (first line: type/ version/transform/metadata/etc).

attr_schema/ semantic_attr_schema must already reflect every feature that will be added (typically built via add_attributes over each feature's CityObjects, scanning all features once before constructing this, exactly as the Rust fcb CLI's own two-pass approach does).

Throws fcb::Error{IoError} if a temporary file cannot be created.

Definition at line 33 of file fcb_writer.cpp.

References fcb::FcbWriterOptions::attribute_indices, and fcb::IoError.

~FcbWriter()

fcb::FcbWriter::~FcbWriter

(

)

Definition at line 54 of file fcb_writer.cpp.

FcbWriter() [2/3]

fcb::FcbWriter::FcbWriter ( const FcbWriter &  )

delete

FcbWriter() [3/3]

fcb::FcbWriter::FcbWriter ( FcbWriter &&  )

delete

Member Function Documentation

add_feature()

void fcb::FcbWriter::add_feature

(

const nlohmann::ordered_json &

city_json_feature

)

Encodes and spools one CityJSONFeature line.

Throws fcb::Error{IoError} if called after write(), or if the spool write itself fails.

Definition at line 60 of file fcb_writer.cpp.

References fcb::cityfeature_to_index_entries(), FCB_FSEEK, fcb::IoError, fcb::NodeItem::min_x, and fcb::to_fcb_city_feature().

operator=() [1/2]

FcbWriter & fcb::FcbWriter::operator= ( const FcbWriter &  )

delete

operator=() [2/2]

FcbWriter & fcb::FcbWriter::operator= ( FcbWriter &&  )

delete

References offset.

write() [1/2]

std::vector< std::uint8_t > fcb::FcbWriter::write

(

)

Convenience wrapper around write(std::ostream&) that returns the complete file as one buffer.

Does NOT have the streaming overload's bounded-memory property – prefer the ostream overload for large output.

Definition at line 253 of file fcb_writer.cpp.

References write().

Referenced by write().

write() [2/2]

void fcb::FcbWriter::write

(

std::ostream &

out

)

Finalizes the file: hilbert-sorts features by bbox (unless options.write_index is false or no features were added), builds the spatial and attribute indices, and streams the complete byte sequence – magic bytes, header, R-tree, attribute indices, features, in that order, byte-identical to what FcbWriter::write (writer/mod.rs:191-278) produces for the same input – to out, copying feature bytes from the spool file in fixed-size chunks rather than materializing them all at once.

May be called only once (either overload); throws fcb::Error{IoError} otherwise.

Definition at line 96 of file fcb_writer.cpp.

References fcb::FcbWriterOptions::attribute_indices, fcb::BuiltBtreeIndex::branching_factor, fcb::build_packed_rtree(), fcb::build_static_btree(), fcb::BuiltBtreeIndex::bytes, fcb::calc_extent(), fcb::NodeItem::empty(), fcb::encode_packed_rtree(), FCB_FSEEK, fcb::HeaderWriterOptions::feature_count, fcb::FcbWriterOptions::geographical_extent, fcb::HeaderWriterOptions::geographical_extent, fcb::hilbert_sort(), fcb::FcbWriterOptions::index_node_size, fcb::HeaderWriterOptions::index_node_size, fcb::IoError, fcb::kDefaultBranchingFactor, fcb::key_kind_for_column(), kind, fcb::BuiltBtreeIndex::num_unique_items, fcb::to_fcb_header(), and fcb::FcbWriterOptions::write_index.

---

The documentation for this class was generated from the following files:

• include/fcb/writer/fcb_writer.hpp
• src/writer/fcb_writer.cpp