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.

The underlying w:sz value is parsed as strict unsigned half-point text in the range 1..UINT32_MAX. Empty values, signs, trailing characters, zero, and overflow return an empty optional instead of being partially accepted.

Text Mutation Transactions And Handles¶

Paragraph::set_text(...), Run::set_text(...), add_run(...), adjacent paragraph/run insertion, and the insert_*_like_* helpers build complete unpublished XML first. An allocation failure while creating a node name, attribute name or value, text, line break, or copied formatting returns false or an empty handle without leaving an empty paragraph, empty run, or partial formatting. The original XML and existing handles remain unchanged. Chinese text, emoji, surrounding whitespace, and CR/LF/CRLF input are handled as UTF-8.

After a successful Paragraph::set_text(...), the original Paragraph handle remains valid, while old Run handles into the replaced content and their descendants are invalid; reacquire runs from the paragraph. A successful Run::set_text(...) preserves the Run handle itself. Successful insertion and append operations add only the returned subtree and do not invalidate unremoved sibling handles.

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");
}