![]() |
![]() |
Gwyddion Application Library Reference Manual | ![]() |
|
---|---|---|---|---|
Top | Description |
#include <app/gwymoduleutils-file.h> gboolean gwy_get_gboolean8 (const guchar **ppv
); gint16 gwy_get_gint16_le (const guchar **ppv
); gint16 gwy_get_gint16_be (const guchar **ppv
); guint16 gwy_get_guint16_le (const guchar **ppv
); guint16 gwy_get_guint16_be (const guchar **ppv
); gint32 gwy_get_gint32_le (const guchar **ppv
); gint32 gwy_get_gint32_be (const guchar **ppv
); guint32 gwy_get_guint32_le (const guchar **ppv
); guint32 gwy_get_guint32_be (const guchar **ppv
); gint64 gwy_get_gint64_le (const guchar **ppv
); gint64 gwy_get_gint64_be (const guchar **ppv
); guint64 gwy_get_guint64_le (const guchar **ppv
); guint64 gwy_get_guint64_be (const guchar **ppv
); gfloat gwy_get_gfloat_le (const guchar **ppv
); gfloat gwy_get_gfloat_be (const guchar **ppv
); gdouble gwy_get_gdouble_le (const guchar **ppv
); gdouble gwy_get_gdouble_be (const guchar **ppv
); gdouble gwy_get_pascal_real_le (const guchar **ppv
); gdouble gwy_get_pascal_real_be (const guchar **ppv
); gboolean gwy_app_channel_check_nonsquare (GwyContainer *data
,gint id
); gboolean gwy_app_channel_title_fall_back (GwyContainer *data
,gint id
); guint gwy_app_channel_remove_bad_data (GwyDataField *dfield
,GwyDataField *mfield
); #define GWY_TEXT_HEADER_ERROR enum GwyTextHeaderError; GwyTextHeaderParser; GQuark gwy_text_header_error_quark (void
); GHashTable * gwy_text_header_parse (gchar *header
,const GwyTextHeaderParser *parser
,gpointer user_data
,GError **error
); const gchar * gwy_text_header_context_get_section (const GwyTextHeaderContext *context
); guint gwy_text_header_context_get_lineno (const GwyTextHeaderContext *context
); GwyTextHeaderContext;
Functions gwy_app_channel_check_nonsquare()
and
gwy_app_channel_title_fall_back()
perform common tasks improving the
imported of channels from foreign data files. Typically one calls them on
all imported channel ids after storing the data fields the the container,
if they are useful for a given file type.
The group of functions gwy_get_gint16_le()
, gwy_get_gint16_be()
, etc.
is intended to portably read packed binary data structures that are commonly
found in SPM files. They all work identically: the binary data value is
read from the buffer, converted if necessary, and the provided
buffer pointer is moved to point after the value to faciliate sequential
reading.
As no buffer size is passed, obviously no buffer size checking is performed. The caller has to ensure the buffer is large enough -- it is expected the caller checks the total buffer size before starting to parse it.
For example to portably read the following packed struct stored in big-endian byte order:
1 2 3 4 5 |
struct { guint16 xres; guint16 yres; gfloat measure; } header; |
one can do (after checking the buffer size):
1 2 3 4 |
const guchar *p = buffer; header.xres = gwy_get_guint16_be(&p); header.yres = gwy_get_guint16_be(&p); header.measure = gwy_get_gfloat_be(&p); |
and p
will point after measure
in buffer
after this snippet is finished.
The data types used in header
do not matter (provided they are large
enough to hold the values), the exact types are determined by the functions
used. Therefore the reading would work identically if header
was defined
using common types:
1 2 3 4 5 |
struct { gint xres; gint yres; gdouble measure; } header; |
gboolean gwy_get_gboolean8 (const guchar **ppv
);
Reads a boolean value stored as a signle byte from a binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to boolean (stored as a signle byte) in a memory buffer. |
Returns : |
The gboolean value read from the buffer. |
Since 2.3
gint16 gwy_get_gint16_le (const guchar **ppv
);
Reads a signed 16bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian signed 16bit integer in a memory buffer. |
Returns : |
The gint16 value read from the buffer. |
Since 2.3
gint16 gwy_get_gint16_be (const guchar **ppv
);
Reads a signed 16bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian signed 16bit integer in a memory buffer. |
Returns : |
The gint16 value read from the buffer. |
Since 2.3
guint16 gwy_get_guint16_le (const guchar **ppv
);
Reads an unsigned 16bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian unsigned 16bit integer in a memory buffer. |
Returns : |
The guint16 value read from the buffer. |
Since 2.3
guint16 gwy_get_guint16_be (const guchar **ppv
);
Reads an unsigned 16bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian unsigned 16bit integer in a memory buffer. |
Returns : |
The guint16 value read from the buffer. |
Since 2.3
gint32 gwy_get_gint32_le (const guchar **ppv
);
Reads a signed 32bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian signed 32bit integer in a memory buffer. |
Returns : |
The gint32 value read from the buffer. |
Since 2.3
gint32 gwy_get_gint32_be (const guchar **ppv
);
Reads a signed 32bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian signed 32bit integer in a memory buffer. |
Returns : |
The gint32 value read from the buffer. |
Since 2.3
guint32 gwy_get_guint32_le (const guchar **ppv
);
Reads an unsigned 32bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian unsigned 32bit integer in a memory buffer. |
Returns : |
The guint32 value read from the buffer. |
Since 2.3
guint32 gwy_get_guint32_be (const guchar **ppv
);
Reads an unsigned 32bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian unsigned 32bit integer in a memory buffer. |
Returns : |
The guint32 value read from the buffer. |
Since 2.3
gint64 gwy_get_gint64_le (const guchar **ppv
);
Reads a signed 64bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian signed 64bit integer in a memory buffer. |
Returns : |
The gint64 value read from the buffer. |
Since 2.3
gint64 gwy_get_gint64_be (const guchar **ppv
);
Reads a signed 64bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian signed 64bit integer in a memory buffer. |
Returns : |
The gint64 value read from the buffer. |
Since 2.3
guint64 gwy_get_guint64_le (const guchar **ppv
);
Reads an unsigned 64bit integer value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian unsigned 64bit integer in a memory buffer. |
Returns : |
The guint64 value read from the buffer. |
Since 2.3
guint64 gwy_get_guint64_be (const guchar **ppv
);
Reads an unsigned 64bit integer value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian unsigned 64bit integer in a memory buffer. |
Returns : |
The guint64 value read from the buffer. |
Since 2.3
gfloat gwy_get_gfloat_le (const guchar **ppv
);
Reads a single-precision IEEE float value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian single-precision IEEE float in a memory buffer. |
Returns : |
The gfloat value read from the buffer. |
Since 2.3
gfloat gwy_get_gfloat_be (const guchar **ppv
);
Reads a single-precision IEEE float value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian single-precision IEEE float in a memory buffer. |
Returns : |
The gfloat value read from the buffer. |
Since 2.3
gdouble gwy_get_gdouble_le (const guchar **ppv
);
Reads a double-precision IEEE float value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian double-precision IEEE float in a memory buffer. |
Returns : |
The gdouble value read from the buffer. |
Since 2.3
gdouble gwy_get_gdouble_be (const guchar **ppv
);
Reads a double-precision IEEE float value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian double-precision IEEE float in a memory buffer. |
Returns : |
The gdouble value read from the buffer. |
Since 2.3
gdouble gwy_get_pascal_real_le (const guchar **ppv
);
Reads a six-byte Pascale Real value from a little-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a little-endian six-byte Pascal Real in a memory buffer. |
Returns : |
The floating point value read from the buffer as a gdouble. |
Since 2.3
gdouble gwy_get_pascal_real_be (const guchar **ppv
);
Reads a six-byte Pascale Real value from a big-endian binary data buffer, moving the buffer pointer to point just after the value.
|
Pointer to a pointer to a big-endian six-byte Pascal Real in a memory buffer. |
Returns : |
The floating point value read from the buffer as a gdouble. |
Since 2.3
gboolean gwy_app_channel_check_nonsquare (GwyContainer *data
,gint id
);
Sets `realsquare' for a channel highly non-square pixels.
The threshold for highly non-square is somewhat arbitrary. Fortunately, most files encoutered in practice have the measure ratio either very close to 1, larger or equal than 2.
|
A data container. |
|
Data channel id. |
Returns : |
TRUE if the channel was found to have highly non-square pixels
and `realsquare' was set (otherwise it was unset). |
Since 2.3
gboolean gwy_app_channel_title_fall_back (GwyContainer *data
,gint id
);
Adds a channel title based on data field units.
The guess is very simple, but probably better than `Unknown channel' in most cases. If there already is a title it is left intact, making use of this function as a fall-back easier.
|
A data container. |
|
Data channel id. |
Returns : |
TRUE if the title was set (either by this function or before). |
Since 2.3
guint gwy_app_channel_remove_bad_data (GwyDataField *dfield
,GwyDataField *mfield
);
Replaces bad data points with some neutral values.
Since Gwyddion has no concept of bad data points, they are usually marked with a mask and replaced with some neutral values upon import, leaving the user to decide how to proceed further. This helper function performs such replacement, using the average of all good points as the neutral replacement value (at this moment).
|
A data field. The values of bad data points are ignored and might be even left uninitialized. |
|
A mask field containing 1.0 in place of good data points, 0.0 in place of bad points. It will be inverted to become the mask of bad points. |
Returns : |
The number of bad data points replaced. If zero is returned, all points are good and there is no need for masking. |
Since 2.14
#define GWY_TEXT_HEADER_ERROR gwy_text_header_error_quark()
Error domain for text header parsing. Errors in this domain will be from the GwyTextHeaderError enumeration. See GError for information on error domains.
Since 2.18
typedef enum { GWY_TEXT_HEADER_ERROR_SECTION_NAME, GWY_TEXT_HEADER_ERROR_SECTION_END, GWY_TEXT_HEADER_ERROR_SECTION_START, GWY_TEXT_HEADER_ERROR_PREFIX, GWY_TEXT_HEADER_ERROR_GARBAGE, GWY_TEXT_HEADER_ERROR_KEY, GWY_TEXT_HEADER_ERROR_VALUE, GWY_TEXT_HEADER_ERROR_TERMINATOR, } GwyTextHeaderError;
Section name is invalid. It is raised by the parser only for an empty section name. | |
Section ended when a different section
or no section was open. Note that
gwy_text_header_context_get_section()
|
|
Since 2.18
typedef struct { const gchar *comment_prefix; const gchar *section_template; const gchar *endsection_template; const gchar *section_accessor; const gchar *line_prefix; const gchar *key_value_separator; const gchar *terminator; gboolean (*item)(const GwyTextHeaderContext *context, GHashTable *hash, gchar *key, gchar *value, gpointer user_data, GError **error); gboolean (*section)(const GwyTextHeaderContext *context, const gchar *name, gpointer user_data, GError **error); gboolean (*endsection)(const GwyTextHeaderContext *context, const gchar *name, gpointer user_data, GError **error); void (*end)(const GwyTextHeaderContext *context, gsize length, gpointer user_data); gboolean (*error)(const GwyTextHeaderContext *context, GError *error, gpointer user_data); GDestroyNotify destroy_key; GDestroyNotify destroy_value; } GwyTextHeaderParser;
Text header parser specification.
Memory considerations: In general, the parser attempts to reuse the contents
of header
directly for the hash keys and values. There are two cases when
it cannot: sectioning implies that keys must be constructed dynamically
and the use of item
callback means the parser has no control on what is
inserted into the hash table.
This means that the item
callback must free key
if sectioning is used and
it is not going to actually use it as the hash table key. And, of course,
suitable destroy_key
and destroy_value
functions must be set.
const gchar * |
Prefix denoting comment lines. It is possible to specify multiple prefixes by separating them with newline ("\n"). |
const gchar * |
Section start template. It must contain the character "\x1a" in the place where the section name apprears. Example: "[Section \x1a]". |
const gchar * |
Section end template. It may or may not contain the
substitute character "\x1a" depending on whether the
section end markers contain the section name. It is
invalid to set endsection_template without setting
section_template . Example: "[Section \x1a End]". |
const gchar * |
Glue to put between the section name and key when
constructing hash table keys. It is invalid to set
section_accessor without setting section_template .
Typically, "::" is used. |
const gchar * |
Mandatory prefix of each line. Note this applies only to
key-value lines. The templates, such comments, sections and
terminators, must still include line_prefix if they start
with it. |
const gchar * |
The string separating keys and values on each line.
Typically, "=" or ":" is used. When left NULL ,
whitespace plays the role of the separator. Of
course, keys cannot contain whitespace then. |
const gchar * |
Line that marks end of the header. It is mandatory if
specified, GWY_TEXT_HEADER_ERROR_TERMINATOR is raised when
the header ends sooner than terminator is found. |
Callback called when a key-value pair is found. If set it is
responsible for inserting the pair to the hash table with
g_hash_table_replace() . It is free to insert a different pair or
nothing. It must return FALSE if it raises an error. |
|
Callback called when a section starts. It must return FALSE if
it raises an error. |
|
Callback called when a section end. It must return FALSE if
it raises an error. |
|
Callback called when the parsing finishes successfully, length
contains the length of parsed text in bytes. |
|
Callback called when an error occurs, including errors raised by
other user callbacks. If it returns TRUE the error is considered
fatal and the parsing terminates immediately. If it is left unset
no errors are fatal hence no errors are reported to the caller. |
|
GDestroyNotify |
Function to destroy keys, passed to g_hash_table_new_full() .
It is invalid to set destroy_key if item callback is not
set. |
GDestroyNotify |
Function to destroy values, passed to
g_hash_table_new_full() . It is invalid to set
destroy_value if item callback is not set. |
Since 2.18
GQuark gwy_text_header_error_quark (void
);
Returns error domain for expression parsin and evaluation.
See and use GWY_TEXT_HEADER_ERROR
.
Returns : |
The error domain. |
Since 2.18
GHashTable * gwy_text_header_parse (gchar *header
,const GwyTextHeaderParser *parser
,gpointer user_data
,GError **error
);
Parses a line-oriented text header into a hash table.
See GwyTextHeaderParser for details of memory and error handling.
Lines consisting only of whitespace are ignored.
|
Text header to parse. It must be NULL -terminated and writable.
Its contents will be modified to directly embed the hash keys
and/or values. It must not be freed while the returned hash
table is in use. |
|
Parser specification. |
|
User data passed to parser callbacks. |
|
Error to set on fatal errors. |
Returns : |
A newly created hash table with values indexed by they keys found in the header. |
Since 2.18
const gchar * gwy_text_header_context_get_section (const GwyTextHeaderContext *context
);
Gets the currently open section.
This function may be called if no sectioning is defined. It simply
returns NULL
then.
|
Header parsing context. |
Returns : |
The name of the currently open section, NULL if there is none. |
Since 2.18
guint gwy_text_header_context_get_lineno (const GwyTextHeaderContext *context
);
Gets the current header line.
|
Header parsing context. |
Returns : |
The current line number, starting from zero. |
Since 2.18
typedef struct _GwyTextHeaderContext GwyTextHeaderContext;
GwyTextHeaderContext represents the parsing state. It is an opaque data structure and should be only manipulated with the functions below.
Since 2.18