Paragraph And Run

featherdoc::Paragraph is the editing handle for a Word paragraph. featherdoc::Run is the editing handle for text inside a paragraph with its own run-level formatting, language, and direction metadata.

Common Tasks

Use this page when editing text runs or paragraph layout:

• Replace a whole paragraph: call Paragraph::set_text(...).

• Add styled text inside a paragraph: call add_run(...) and then set run font, color, language, or direction metadata.

• Insert adjacent content: use insert_paragraph_before(...), insert_paragraph_after(...), insert_run_before(...), or insert_run_after(...).

• Preserve nearby formatting: use the insert_*_like_* helpers before changing text.

• Tune layout: use paragraph alignment, bidirectional layout, and indent APIs.

Success And Failure Semantics

Return shape	Success	Failure or no-op
bool	true means the current paragraph or run XML node changed.	false means the current node was missing, unsupported, or unchanged.
std::optional<T>	Contains the requested formatting, layout, language, or direction value.	Empty means the property is not explicitly set or cannot be resolved.
Paragraph / Run	Returned handles point at inserted or appended paragraph/run nodes.	Use the returned handle for follow-up formatting.
Iterator references	Paragraph & and Run & represent the current iterator position.	Call has_next() before advancing when iterating existing content.

Short Example

auto paragraph = doc.body_template().append_paragraph("Status:");
auto value = paragraph.add_run(" approved", featherdoc::formatting_flag::bold);
value.set_font_family("Aptos");
paragraph.set_alignment(featherdoc::paragraph_alignment::center);

Typed Signature Guide

Use this table when you need the exact argument shape before writing code. Indexes are zero-based where an API accepts an index. Methods returning bool report whether the underlying XML node could be changed.

Signature	Parameters	Return semantics
bool set_text(const std::string &text) const	text: replacement paragraph or run text.	true when the current node was rewritten.
Run add_run(const std::string &text, formatting_flag formatting = formatting_flag::none)	text: appended text. formatting: optional basic formatting flag.	New Run handle for the appended run.
Paragraph insert_paragraph_before(const std::string &text, formatting_flag formatting = formatting_flag::none)	text: inserted paragraph text. formatting: optional first-run formatting.	New paragraph handle inserted before the current paragraph.
Paragraph insert_paragraph_after(const std::string &text, formatting_flag formatting = formatting_flag::none)	text: inserted paragraph text. formatting: optional first-run formatting.	New paragraph handle inserted after the current paragraph.
bool set_alignment(paragraph_alignment alignment) const	alignment: one of the documented paragraph alignment enum values.	true when paragraph properties were updated.
bool set_indent_left_twips(std::uint32_t indent_twips) const	indent_twips: left indent in twips.	true when the paragraph indent was updated.
Run insert_run_before(const std::string &text, formatting_flag formatting = formatting_flag::none)	text: inserted run text. formatting: optional basic formatting flag.	New run handle inserted before the current run.
Run insert_run_after(const std::string &text, formatting_flag formatting = formatting_flag::none)	text: inserted run text. formatting: optional basic formatting flag.	New run handle inserted after the current run.
bool set_font_family(std::string_view font_family) const	font_family: primary Latin font family name.	true when run properties were updated.
bool set_language(std::string_view language) const	language: BCP-47 style language tag such as en-US.	true when language metadata was updated.
bool set_rtl(bool enabled = true) const	enabled: true to mark the run right-to-left.	true when run direction metadata was updated.

Paragraph Text And Iteration

Method	Returns	Purpose
next()	Paragraph &	Advance the paragraph iterator to the next paragraph.
has_next() const	bool	Check whether the iterator can advance.
set_text(const std::string &text) const	bool	Replace all text in the current paragraph.
remove()	bool	Remove the current paragraph.
runs()	Run &	Access the run iterator for the current paragraph.
add_run(text, formatting_flag formatting = none)	Run	Append a run with optional basic formatting.
insert_paragraph_before(text, formatting)	Paragraph	Insert a paragraph before the current paragraph.
insert_paragraph_after(text, formatting)	Paragraph	Insert a paragraph after the current paragraph.
insert_paragraph_like_before()	Paragraph	Insert a paragraph before this one and copy paragraph properties.
insert_paragraph_like_after()	Paragraph	Insert a paragraph after this one and copy paragraph properties.

Paragraph Layout

Method	Returns	Purpose
bidi() const	std::optional<bool>	Inspect right-to-left paragraph layout metadata.
set_bidi(bool enabled = true) const	bool	Enable or disable right-to-left paragraph layout.
clear_bidi() const	bool	Remove explicit right-to-left paragraph metadata.
alignment() const	std::optional<paragraph_alignment>	Read paragraph alignment.
set_alignment(paragraph_alignment alignment) const	bool	Set paragraph alignment.
clear_alignment() const	bool	Remove explicit paragraph alignment.
indent_left_twips() const / indent_right_twips() const	std::optional<std::uint32_t>	Read left or right indent in twips.
first_line_indent_twips() const / hanging_indent_twips() const	std::optional<std::uint32_t>	Read first-line or hanging indent.
set_indent_left_twips(indent_twips) const	bool	Set the left indent in twips.
set_indent_right_twips(indent_twips) const	bool	Set the right indent in twips.
set_first_line_indent_twips(indent_twips) const	bool	Set the first-line indent.
set_hanging_indent_twips(indent_twips) const	bool	Set the hanging indent.

Run Text And Styling

Method	Returns	Purpose
get_text() const	std::string	Read the current run text.
set_text(const std::string &text) const	bool	Replace the current run text.
remove()	bool	Remove the current run.
insert_run_before(text, formatting)	Run	Insert a run before the current run.
insert_run_after(text, formatting)	Run	Insert a run after the current run.
insert_run_like_before()	Run	Insert a run before this one and copy run properties.
insert_run_like_after()	Run	Insert a run after this one and copy run properties.
style_id() const	std::optional<std::string>	Read the run style id.
font_family() const	std::optional<std::string>	Read the primary run font family.
set_font_family(font_family) const	bool	Set the primary run font family.
text_color() const	std::optional<std::string>	Read the run text color value.
bold() const / italic() const / underline() const	std::optional<bool>	Inspect basic run styling.
strikethrough() const	std::optional<bool>	Inspect strikethrough styling.
superscript() const / subscript() const	std::optional<bool>	Inspect vertical script styling.
font_size_points() const	std::optional<double>	Read the run font size in points.

Run Language And Direction

Method	Returns	Purpose
language() const	std::optional<std::string>	Read the primary language metadata.
east_asia_language() const	std::optional<std::string>	Read East Asian language metadata.
bidi_language() const	std::optional<std::string>	Read bidirectional language metadata.
set_language(language) const	bool	Set the primary language metadata.
set_east_asia_language(language) const	bool	Set East Asian language metadata.
set_bidi_language(language) const	bool	Set bidirectional language metadata.
rtl() const	std::optional<bool>	Inspect right-to-left run metadata.
set_rtl(bool enabled = true) const	bool	Enable or disable right-to-left run metadata.

Example

auto paragraph = doc.body_template().append_paragraph("Title");
paragraph.set_alignment(featherdoc::paragraph_alignment::center);

auto emphasized = paragraph.add_run(
    " approved",
    featherdoc::formatting_flag::bold);
emphasized.set_language("en-US");

auto &run = paragraph.runs();
if (run.has_next()) {
    run.next().set_font_family("Aptos");
}