GwyResults: Gwyddion Library Reference Manual

## GwyResults GwyResults — Reported set of scalar results |

## Functions

GwyResults * | gwy_results_new ()
GwyResults * | gwy_results_copy ()
void | gwy_results_add_header ()
void | gwy_results_add_separator ()
void | gwy_results_add_value ()
void | gwy_results_add_format ()
void | gwy_results_add_value_str ()
void | gwy_results_add_value_x ()
void | gwy_results_add_value_y ()
void | gwy_results_add_value_z ()
void | gwy_results_add_value_plain ()
void | gwy_results_add_value_int ()
void | gwy_results_add_value_angle ()
void | gwy_results_add_value_percents ()
void | gwy_results_add_value_yesno ()
void | gwy_results_add_covariance_matrix ()
void | gwy_results_add_covariance_matrixv ()
void | gwy_results_bind_formats ()
void | gwy_results_unbind_formats ()
void | gwy_results_set_unit ()
void | gwy_results_set_unit_str ()
void | gwy_results_fill_values ()
void | gwy_results_fill_values_with_errors ()
void | gwy_results_fill_format ()
void | gwy_results_fill_covariance_matrix ()
void | gwy_results_set_na ()
void | gwy_results_set_nav ()
gchar * | gwy_results_create_report ()
const gchar * | gwy_results_get_label ()
const gchar * | gwy_results_get_symbol ()
const gchar * | gwy_results_get_label_with_symbol ()
const gchar * | gwy_results_get_value ()
const gchar * | gwy_results_get_error ()
const gchar * | gwy_results_get_value_with_error ()
const gchar * | gwy_results_get_units ()
const gchar * | gwy_results_get_full ()
gboolean | gwy_results_value_is_na ()
void | gwy_format_result_table_row ()
void | gwy_format_result_table_rowv ()
void | gwy_format_result_table_strings ()
void | gwy_format_result_table_stringsv ()
void | gwy_format_result_table_mixed ()

## Types and Values

enum | GwyResultsValueType
enum | GwyResultsReportType
struct | GwyResults
struct | GwyResultsClass

## Object Hierarchy

        GObject
        ╰── GwyResults

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyResults is a helper for formatting ordered sets of scalar values for display and reports.

After creation, add rows with values to the report with functions such as `gwy_results_add_value()`. Simplified functions exists for common cases. A value which have the dimension of `x` can be added using `gwy_results_add_value_x()`. There are functions for angles, percentages, yes/no values, etc. and also report headers (sections) and separators.

Each value has a string `id` which can be used later to refer to it in functions such as `gwy_results_set_na()` (marking a value not available) or `gwy_results_get_value()` (getting formatted value for display).

Normal values also have units. You can give a fixed unit string using the "unit-str" parameter of `gwy_results_add_value()`. However, usually one specifies just the dimensionality by passing "power-x", "power-y", etc. parameters (or implicitly using function like `gwy_results_add_value_x()`). The units of `x` are then set with `gwy_results_set_unit()` with unit name "x" and GwyResults derives the units of individual values itself.

Once GwyResults is set up, numeric values can be filled using `gwy_results_fill_values()` or its alternatives. You can then obtain individual values formatted for display using `gwy_results_get_value()`, `gwy_results_get_full()`, etc. Or you can format an entire report with all the values using `gwy_results_create_report()` -- this is useful for saving the report to a text file. This can be repeated any number of times.

The labels passed during construction must persist through the GwyResults lifetime. They should be essentially always static translatable strings marked with `N_()`, but left untranslated.

Filling values is relatively cheap and does not invoke any formatting. Formatting only happens when strings or reports are actually requested, and then all values are formatted at once (and remembered). Therefore, an efficient usage of GwyResults is to fill all values first and then request whichever formatted values you want. Do not set and format values one by one (it would also prevent format binding from working in any useful way).

## Functions

### gwy_results_new ()

    GwyResults *
    gwy_results_new (void);

Creates a new empty set of reported scalar values.

#### Returns

A new set of reported scalar values.

Since: 2.50

### gwy_results_copy ()

    GwyResults *
    gwy_results_copy (GwyResults *results);

Creates a copy of a set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |

#### Returns

A new GwyResults which is an exact copy of `results` .

Since: 2.50

### gwy_results_add_header ()

    void
    gwy_results_add_header (GwyResults *results,
                            const gchar *label);

Appends a header line to the set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |
label | Header text (untranslated). |

Since: 2.50

### gwy_results_add_separator ()

    void
    gwy_results_add_separator (GwyResults *results);

Appends a separator line to the set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |

Since: 2.50

### gwy_results_add_value ()

    void
    gwy_results_add_value (GwyResults *results,
                           const gchar *id,
                           const gchar *label,
                           ...);

Appends a general value line to a set of reported scalar values.

Possible keys include:

`"type"`, value type (GwyResultsValueType)
`"power-t"`, power of unit `t` (gint)
`"power-u"`, power of unit `u` (gint, since 2.52)
`"power-v"`, power of unit `v` (gint, since 2.52)
`"power-x"`, power of unit `x` (gint)
`"power-y"`, power of unit `y` (gint)
`"power-z"`, power of unit `z` (gint)
`"power-w"`, power of unit `w` (gint)
`"precision"`, the mininum number of significant digits (gint, since 2.63)
`"is-angle"`, `TRUE` if the quantity should converted to degrees for humans, this overrides any unit powers (gboolean)
`"is-fitting-param"`, `TRUE` if the quantity should be reported as fixed parameter when it does not have error set (gboolean)
`"is-percents"`, `TRUE` if the quantity should converted to percents for humans, this overrides any unit powers (gboolean)
`"unit-str"`, fixed unit, this overrides any unit powers (gchar*)
`"translate-unit"`, `TRUE` if the fixed unit should be translated for humans (gboolean)
`"translate-string"`, `TRUE` if string values should be translated for humans (gboolean)
`"symbol"`, optional untranslatable symbol for the quantity (gchar*)

The type of value passed to `gwy_results_fill_values()` must match the type given here. The default properties are floating point value, zero unit powers, no fixed unit string, and all boolean properties `FALSE`.

In most cases this function is not necessary and you can use one of the convenience functions such as `gwy_results_add_value_z()` or `gwy_results_add_value_angle()`.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |
... | `NULL`-terminated sequence of key, value pairs specifying value properties. |

Since: 2.50

### gwy_results_add_format ()

    void
    gwy_results_add_format (GwyResults *results,
                            const gchar *id,
                            const gchar *label,
                            gboolean translate_format,
                            const gchar *format,
                            ...);

Appends a formatted value line to a set of reported scalar values.

This function creates a line that can contain multiple individual fields and must be filled using `gwy_results_fill_format()`.

The format string contains replaceable fields of the form "%{name}c" where `name` is the field name, used later in `gwy_results_fill_format()` and `c` is the format character which can be one of

`"y"`, yes/no value (gboolean)
`"i"`, integer value (gint)
`"s"`, string value (gchar*)
`"v"`, floating point value with units (gdouble)

All indivdual "v" fields share one value format and units.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |
translate_format | `TRUE` to translate the format string when formatting for humans. |
format | Format string for the value. |
... | `NULL`-terminated sequence of key, value pairs specifying value properties. See `gwy_results_add_value()`. |

Since: 2.50

### gwy_results_add_value_str ()

    void
    gwy_results_add_value_str (GwyResults *results,
                               const gchar *id,
                               const gchar *label);

Appends a string value line to a set of reported scalar values.

The corresponding value should be passed as gchar*.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_x ()

    void
    gwy_results_add_value_x (GwyResults *results,
                             const gchar *id,
                             const gchar *label);

Appends an `x` -like floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_y ()

    void
    gwy_results_add_value_y (GwyResults *results,
                             const gchar *id,
                             const gchar *label);

Appends an `y` -like floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.61

### gwy_results_add_value_z ()

    void
    gwy_results_add_value_z (GwyResults *results,
                             const gchar *id,
                             const gchar *label);

Appends a `z` -like floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_plain ()

    void
    gwy_results_add_value_plain (GwyResults *results,
                                 const gchar *id,
                                 const gchar *label);

Appends a unitless floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_int ()

    void
    gwy_results_add_value_int (GwyResults *results,
                               const gchar *id,
                               const gchar *label);

Appends an integer value line to a set of reported scalar values.

The corresponding value should be passed as gint.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_angle ()

    void
    gwy_results_add_value_angle (GwyResults *results,
                                 const gchar *id,
                                 const gchar *label);

Appends an angle-like floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_percents ()

    void
    gwy_results_add_value_percents (GwyResults *results,
                                    const gchar *id,
                                    const gchar *label);

Appends a percent-like floating point value line to a set of reported scalar values.

The corresponding value should be passed as gdouble.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_value_yesno ()

    void
    gwy_results_add_value_yesno (GwyResults *results,
                                 const gchar *id,
                                 const gchar *label);

Appends a yes/no value line to a set of reported scalar values.

The corresponding value should be passed as gboolean (which is the same as gint).

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |

Since: 2.50

### gwy_results_add_covariance_matrix ()

    void
    gwy_results_add_covariance_matrix (GwyResults *results,
                                       const gchar *id,
                                       const gchar *label,
                                       ...);

Appends a covariance matrix to a set of reported scalar values.

Covariance matrices are multi-line. They cannot be formatted using the standard functions such as `gwy_results_get_value()`. They are also omitted when formatting as CSV (`GWY_RESULTS_REPORT_CSV`) because CSV requires the same number of values on each line.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |
... | Sequence of `n` parameter symbols (as gchar*), where `n` is the matrix dimension. |

Since: 2.50

### gwy_results_add_covariance_matrixv ()

    void
    gwy_results_add_covariance_matrixv (GwyResults *results,
                                        const gchar *id,
                                        const gchar *label,
                                        guint n,
                                        const gchar **symbols);

Appends a covariance matrix to a set of reported scalar values.

See `gwy_results_add_covariance_matrix()` for discussion.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier (unique in `results` ). |
label | Value label text (untranslated). |
n | Matrix dimension. |
symbols | Array of `n` parameter symbols (as gchar*). |

Since: 2.50

### gwy_results_bind_formats ()

    void
    gwy_results_bind_formats (GwyResults *results,
                              const gchar *id,
                              ...);

Binds formats of several floating point values together.

This is useful when you do not want one of related values displayed in nm and another in µm (for instance), just because it is somewhat larger.

The values must already exist in `results` . Only values of the same type can be bound together -- and binding has any useful purpose for floating point values anyway. The values must also have the same unit powers.

Rebinding a value that is already bound to another group is not allowed. However it is possible to add more values to the group of the first value (`id` ). Single-value groups are not created.

#### Parameters

results | A set of reported scalar values. |
id | First value identifier to bind. |
... | Identifiers of other values to bind, `NULL`-terminated. |

Since: 2.50

### gwy_results_unbind_formats ()

    void
    gwy_results_unbind_formats (GwyResults *results,
                                const gchar *id,
                                ...);

Unbinds formats of floating point values.

The values are removed from their respective groups. It is not necessary for them to belong to the same group, or to any group.

#### Parameters

results | A set of reported scalar values. |
id | First value identifier to unbind. |
... | Identifiers of other values to unbind, `NULL`-terminated. |

Since: 2.50

### gwy_results_set_unit ()

    void
    gwy_results_set_unit (GwyResults *results,
                          const gchar *name,
                          GwySIUnit *unit);

Sets the unit corresponding to one axis in a set of reported scalar values, from an SI unit.

Unit names "u" and "v" are available since 2.52.

#### Parameters

results | A set of reported scalar values. |
name | Unit name, one of "t", "w", "x", "y" or "z". |
unit | The SI unit to use (`results` makes a copy; it does not take a reference). It can be `NULL`. |

Since: 2.50

### gwy_results_set_unit_str ()

    void
    gwy_results_set_unit_str (GwyResults *results,
                              const gchar *name,
                              const gchar *unitstr);

Sets the unit corresponding to one axis in a set of reported scalar values, from a string.

Unit names "u" and "v" are available since 2.52.

#### Parameters

results | A set of reported scalar values. |
name | Unit name, one of "t", "u", "v", "w", "x", "y" or "z". |
unitstr | The unit to use, as a string. It can be `NULL`. |

Since: 2.50

### gwy_results_fill_values ()

    void
    gwy_results_fill_values (GwyResults *results,
                             ...);

Fills the numerical values in a set of reported scalar values.

The types must correspond to the types given upon construction.

This function cannot be used for values created with `gwy_results_add_format()`. Use `gwy_results_fill_format()`.

If a value was previously set to N.A. using `gwy_results_set_na()`, filling its value removes this status.

#### Parameters

results | A set of reported scalar values. |
... | Sequence of id, value pairs specifying the individual values, terminated by `NULL`. |

Since: 2.50

### gwy_results_fill_values_with_errors ()

    void
    gwy_results_fill_values_with_errors (GwyResults *results,
                                         ...);

Fills the numerical values and their errors in a set of reported scalar values.

Do not set errors for yes/no values; it makes no sense.

See `gwy_results_fill_values()` for further remarks.

#### Parameters

results | A set of reported scalar values. |
... | Sequence of id, value, error triples specifying the individual values, terminated by `NULL`. |

Since: 2.50

### gwy_results_fill_format ()

    void
    gwy_results_fill_format (GwyResults *results,
                             const gchar *id,
                             ...);

Fills the values for a formatted line in a set of reported scalar values.

Even though the value is not atomic and may contain several individual fields, they have to be filled all in one function call.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |
... | List of names (string) and values (corresponding data type), terminated by `NULL`. |

Since: 2.50

### gwy_results_fill_covariance_matrix ()

    void
    gwy_results_fill_covariance_matrix (GwyResults *results,
                                        const gchar *id,
                                        const gboolean *fixed_params,
                                        const gdouble *covar_matrix);

Fills a covariance matrix in a set of reported scalar values.

The value must have been created using `gwy_results_add_covariance_matrix()` or `gwy_results_add_covariance_matrixv()`.

Matrix `covar_matrix` is passed as a lower left triangular part of a symmetric matrix, the same way as GwyNLFitter returns it. The number of elements is `n` *(`n` +1)/2 where `n` is the matrix dimension, equal to the number of symbols. The length of `fixed_params` is `n` .

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |
fixed_params | Which parameters were fixed (their covariances are excluded in the report). Can be `NULL` if all parameters were free or you do not care. |
covar_matrix | Full covariance matrix (including elements for fixed parameters). |

Since: 2.50

### gwy_results_set_na ()

    void
    gwy_results_set_na (GwyResults *results,
                        const gchar *id,
                        ...);

Sets values in reported scalar values to N.A.

Such values are excluded from text reports and some representation of N.A. is returned when their formatted values are explicitly requested.

The N.A. state is removed simply by filling a value.

#### Parameters

results | A set of reported scalar values. |
id | First value identifier to set to N.A. |
... | Identifiers of other values to set to N.A., `NULL`-terminated. |

Since: 2.50

### gwy_results_set_nav ()

    void
    gwy_results_set_nav (GwyResults *results,
                         guint n,
                         const gchar **id);

Sets values in reported scalar values to N.A.

See `gwy_results_set_na()` for discussion.

#### Parameters

results | A set of reported scalar values. |
n | Number of strings in array `id` . |
id | Array of value identifiers to set to N.A. |

Since: 2.50

### gwy_results_create_report ()

    gchar *
    gwy_results_create_report (GwyResults *results,
                               GwyResultsReportType report_type);

Formats a text report for a set of scalar values.

Value lines that have never been filled or were declared N.A. using `gwy_results_set_na()` are skipped in the report.

#### Parameters

results | A set of reported scalar values. |
report_type | Requested report style. |

#### Returns

A newly allocated string with the report. The caller must free it with `g_free()`.

Since: 2.50

### gwy_results_get_label ()

    const gchar *
    gwy_results_get_label (GwyResults *results,
                           const gchar *id);

Gets the label corresponding to a value in a set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` .

Since: 2.50

### gwy_results_get_symbol ()

    const gchar *
    gwy_results_get_symbol (GwyResults *results,
                            const gchar *id);

Gets the symbol corresponding to a value in a set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . An empty string is returned when the value has no symbol.

Since: 2.50

### gwy_results_get_label_with_symbol ()

    const gchar *
    gwy_results_get_label_with_symbol (GwyResults *results,
                                       const gchar *id);

Gets the label and symbol corresponding to a value in a set of reported scalar values.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` .

Since: 2.50

### gwy_results_get_value ()

    const gchar *
    gwy_results_get_value (GwyResults *results,
                           const gchar *id);

Provides one formatted value in a set of reported scalar values.

This function returns just the value, without error or units.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . It must not be modified. It is only valid until another `results` method call.

Since: 2.50

### gwy_results_get_error ()

    const gchar *
    gwy_results_get_error (GwyResults *results,
                           const gchar *id);

Provides one formatted error in a set of reported scalar values.

This function returns just the error, without value or units.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . It must not be modified. It is only valid until another `results` method call.

Since: 2.50

### gwy_results_get_value_with_error ()

    const gchar *
    gwy_results_get_value_with_error (GwyResults *results,
                                      const gchar *id);

Provides one formatted value with error in a set of reported scalar values.

This function returns the value with error, but without units. If there is no error the returned string is identical to what `gwy_results_get_value()` returns.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . It must not be modified. It is only valid until another `results` method call.

Since: 2.50

### gwy_results_get_units ()

    const gchar *
    gwy_results_get_units (GwyResults *results,
                           const gchar *id);

Provides formatted units in a set of reported scalar values.

This function returns just the units, without value.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . It must not be modified. It is only valid until another `results` method call.

Since: 2.50

### gwy_results_get_full ()

    const gchar *
    gwy_results_get_full (GwyResults *results,
                          const gchar *id);

Provides formatted value with units in a set of reported scalar values.

This function returns the entire formatted value.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

A string owned by `results` . It must not be modified. It is only valid until another `results` method call.

Since: 2.50

### gwy_results_value_is_na ()

    gboolean
    gwy_results_value_is_na (GwyResults *results,
                             const gchar *id);

Checks whether a value in a set of reported scalar values is invalid.

A value is valid if it was set to a finite value and was has not been made N.A. using `gwy_results_set_na()` since. Otherwise it is invalid and this function returns `TRUE`.

#### Parameters

results | A set of reported scalar values. |
id | Value identifier. |

#### Returns

`TRUE` if the value is invalid.

Since: 2.50

### gwy_format_result_table_row ()

    void
    gwy_format_result_table_row (GString *str,
                                 GwyResultsReportType report_type,
                                 guint n,
                                 ...);

Formats a row of tabular results.

This is a helper function for formatting tabular results. It appends formatted sequence of real numbers to the string `str` and adds a newline.

Only `GWY_RESULTS_REPORT_TABSEP` and `GWY_RESULTS_REPORT_CSV` are valid styles for tabular data.

When the `GWY_RESULTS_REPORT_MACHINE` flag is included, the caller should generally also pass the values in base units (without any powers of 10), although this function has no means to actually enforce it.

#### Parameters

str | String to append formatted row to. |
report_type | Requested report style. |
n | Number of values. |
... | Sequence of `n` gdouble values to format. |

Since: 2.50

### gwy_format_result_table_rowv ()

    void
    gwy_format_result_table_rowv (GString *str,
                                  GwyResultsReportType report_type,
                                  guint n,
                                  const gdouble *values);

Formats a row of tabular results.

This is a helper function for formatting tabular results. It appends formatted sequence of real numbers to the string `str` and adds a newline.

See `gwy_format_result_table_row()` for discussion.

#### Parameters

str | String to append formatted row to. |
report_type | Requested report style. |
n | Number of values. |
values | Array of `n` real numbers to format. |

Since: 2.50

### gwy_format_result_table_strings ()

    void
    gwy_format_result_table_strings (GString *str,
                                     GwyResultsReportType report_type,
                                     guint n,
                                     ...);

Formats a row of string tabular results.

This is a helper function for formatting tabular results, usually used for table headers.

It appends the strings delimited with tabulators or as CSV to the string `str` and adds a newline. Only `GWY_RESULTS_REPORT_TABSEP` and `GWY_RESULTS_REPORT_CSV` are valid styles for tabular data.

The `GWY_RESULTS_REPORT_MACHINE` flags has no effect.

#### Parameters

str | String to append formatted header row to. |
report_type | Requested report style. |
n | Number of values. |
... | Sequence of `n` strings to format. |

Since: 2.50

### gwy_format_result_table_stringsv ()

    void
    gwy_format_result_table_stringsv (GString *str,
                                      GwyResultsReportType report_type,
                                      guint n,
                                      const gchar **values);

Formats a row of string tabular results.

This is a helper function for formatting tabular results, usually used for table headers.

It appends the strings delimited with tabulators or as CSV to the string `str` and adds a newline. Only `GWY_RESULTS_REPORT_TABSEP` and `GWY_RESULTS_REPORT_CSV` are valid styles for tabular data.

The `GWY_RESULTS_REPORT_MACHINE` flag has no effect.

#### Parameters

str | String to append formatted header row to. |
report_type | Requested report style. |
n | Number of values. |
values | Array of `n` strings to format. |

Since: 2.50

### gwy_format_result_table_mixed ()

    void
    gwy_format_result_table_mixed (GString *str,
                                   GwyResultsReportType report_type,
                                   const gchar *fields,
                                   ...);

This is a helper function for formatting tabular results. It appends formatted sequence of values to the string `str` and adds a newline.

Only `GWY_RESULTS_REPORT_TABSEP` and `GWY_RESULTS_REPORT_CSV` are valid styles for tabular data.

When the `GWY_RESULTS_REPORT_MACHINE` flag is included, the caller should generally also pass floating point values in base units (without any powers of 10), although this function has no means to actually enforce it.

#### Parameters

str | String to append formatted row to. |
report_type | Requested report style. |
fields | String listing the `n` fields in the row, which must be one of "isvy", as described in `gwy_results_add_format()`. |
... | Sequence of `n` values to format, of types corresponding to `fields` . |

Since: 2.54

## Types and Values

### enum GwyResultsValueType

Type of a scalar value in GwyResults.

Yes/no values never have units. Strings and integers can have units, if you specify them. The units are always formatted as base (without any power of 10 prefix).

#### Members

GWY_RESULTS_VALUE_FLOAT | Floating point number (gdouble). |
GWY_RESULTS_VALUE_STRING | String (gchar*). |
GWY_RESULTS_VALUE_INT | Integer (gint). |
GWY_RESULTS_VALUE_YESNO | Yes/no value (gboolean). |

Since: 2.50

### enum GwyResultsReportType

Style options for a text report created with GwyResults.

Multi-value lines created with `gwy_results_add_format()` are also split into four parts with `GWY_RESULTS_REPORT_TABSEP` and `GWY_RESULTS_REPORT_CSV`. The value part corresponds to the format and thus can be complicated. The error part is always empty.

#### Members

GWY_RESULTS_REPORT_COLON | Classic export with labels followed by colons and values (possibly errors) with units, aligned for readability. |
GWY_RESULTS_REPORT_TABSEP | Four tab-separated columns: label, value, error and units. |
GWY_RESULTS_REPORT_CSV | Four comma-separated quoted columns label, value, error and units. |
GWY_RESULTS_REPORT_MACHINE | Machine-readable report with base units, C number format (decimal dot) and untranslated labels. This is a flag and can be combined with other values. |

Since: 2.50

### struct GwyResults

    struct GwyResults;

GwyResults is an opaque data structure and should be only manipulated with the functions below.

Since: 2.50

### struct GwyResultsClass

    struct GwyResultsClass {
        GObjectClass parent_class;
    };