Top | ![]() |
![]() |
![]() |
![]() |
enum | GwyResultsValueType |
enum | GwyResultsReportType |
struct | GwyResults |
struct | GwyResultsClass |
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).
GwyResults *
gwy_results_new (void
);
Creates a new empty set of reported scalar values.
GwyResults *
gwy_results_copy (GwyResults *results
);
Creates a copy of a set of reported scalar values.
void gwy_results_add_header (GwyResults *results
,const gchar *label
);
Appends a header line to the set of reported scalar values.
void
gwy_results_add_separator (GwyResults *results
);
Appends a separator line to the set of reported scalar values.
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()
.
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.
results |
A set of reported scalar values. |
|
id |
Value identifier (unique in |
|
label |
Value label text (untranslated). |
|
translate_format |
|
|
format |
Format string for the value. |
|
... |
|
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*.
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.
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.
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.
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.
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.
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.
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.
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).
void gwy_results_add_correlation_matrix (GwyResults *results
,const gchar *id
,const gchar *label
,...
);
Appends a correlation 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.
void gwy_results_add_correlation_matrixv (GwyResults *results
,const gchar *id
,const gchar *label
,guint n
,const gchar **symbols
);
Appends a correlation matrix to a set of reported scalar values.
See gwy_results_add_correlation_matrix()
for discussion.
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.
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.
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.
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.
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.
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.
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.
void gwy_results_fill_correlation_matrix (GwyResults *results
,const gchar *id
,const gboolean *fixed_params
,const gdouble *correl_matrix
);
Fills a correlation matrix in a set of reported scalar values.
The value must have been created using gwy_results_add_correlation_matrix()
or gwy_results_add_correlation_matrixv()
.
Matrix correl_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
.
results |
A set of reported scalar values. |
|
id |
Value identifier. |
|
fixed_params |
Which parameters were fixed (their correlations are excluded in the report). Can be |
|
correl_matrix |
Full correlation matrix (including elements for fixed parameters). |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
.
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.
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.
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.
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.
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.
str |
String to append formatted row to. |
|
report_type |
Requested report style. |
|
fields |
String listing the |
|
... |
Sequence of |
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).
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.
Classic export with labels followed by colons and values (possibly errors) with units, aligned for readability. |
||
Four tab-separated columns: label, value, error and units. |
||
Four comma-separated quoted columns label, value, error and units. |
||
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. |
struct GwyResults;
GwyResults is an opaque data structure and should be only manipulated with the functions below.