243c60e8b5
Purpose: Thoughout doc set (UG, RM, Intro, FormatSpec, and index/TOC pages): Added/updated "Describes HDF5 Release ..." entry. In many cases, verified/updated "Last modified ..." entry. Platforms tested: IE 5
926 lines
32 KiB
HTML
926 lines
32 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Enumeration Data Types in the Data Type Interface (H5T)</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<h1>The Data Type Interface (H5T) <font size=-1><i>(contitnued)</i></font></h1>
|
|
|
|
<p align=right><font size=-1><i>
|
|
(Return to <a href="Datatypes.html#Datatypes_Enum">Data Types Interface (H5T)</a>.)
|
|
</font></i>
|
|
|
|
<h2>7. Enumeration Data Types</h2>
|
|
|
|
<h3>7.1. Introduction</h2>
|
|
|
|
<p>An HDF enumeration data type is a 1:1 mapping between a set of
|
|
symbols and a set of integer values, and an order is imposed on
|
|
the symbols by their integer values. The symbols are passed
|
|
between the application and library as character strings and all
|
|
the values for a particular enumeration type are of the same
|
|
integer type, which is not necessarily a native type.
|
|
|
|
<h3>7.2. Creation</h2>
|
|
|
|
<p>Creation of an enumeration data type resembles creation of a
|
|
compound data type: first an empty enumeration type is created,
|
|
then members are added to the type, then the type is optionally
|
|
locked.
|
|
|
|
<dl>
|
|
<dt><code>hid_t H5Tcreate(H5T_class_t <em>type_class</em>,
|
|
size_t <em>size</em>)</code>
|
|
<dd>This function creates a new empty enumeration data type based
|
|
on a native signed integer type. The first argument is the
|
|
constant <code>H5T_ENUM</code> and the second argument is the
|
|
size in bytes of the native integer on which the enumeration
|
|
type is based. If the architecture does not support a native
|
|
signed integer of the specified size then an error is
|
|
returned.
|
|
|
|
<pre>
|
|
/* Based on a native signed short */
|
|
hid_t hdf_en_colors = H5Tcreate(H5T_ENUM, sizeof(short));</pre>
|
|
|
|
|
|
<dt><code>hid_t H5Tenum_create(hid_t <em>base</em>)</code>
|
|
<dd>This function creates a new empty enumeration data type based
|
|
on some integer data type <em>base</em> and is a
|
|
generalization of the <code>H5Tcreate()</code> function. This
|
|
function is useful when creating an enumeration type based on
|
|
some non-native integer data type, but it can be used for
|
|
native types as well.
|
|
|
|
<pre>
|
|
/* Based on a native unsigned short */
|
|
hid_t hdf_en_colors_1 = H5Tenum_create(H5T_NATIVE_USHORT);
|
|
|
|
/* Based on a MIPS 16-bit unsigned integer */
|
|
hid_t hdf_en_colors_2 = H5Tenum_create(H5T_MIPS_UINT16);
|
|
|
|
/* Based on a big-endian 16-bit unsigned integer */
|
|
hid_t hdf_en_colors_3 = H5Tenum_create(H5T_STD_U16BE);</pre>
|
|
|
|
|
|
<dt><code>herr_t H5Tenum_insert(hid_t <em>etype</em>, const char
|
|
*<em>symbol</em>, void *<em>value</em>)</code>
|
|
<dd>Members are inserted into the enumeration data type
|
|
<em>etype</em> with this function. Each member has a symbolic
|
|
name <em>symbol</em> and some integer representation
|
|
<em>value</em>. The <em>value</em> argument must point to a value
|
|
of the same data type as specified when the enumeration type
|
|
was created. The order of member insertion is not important
|
|
but all symbol names and values must be unique within a
|
|
particular enumeration type.
|
|
|
|
<pre>
|
|
short val;
|
|
H5Tenum_insert(hdf_en_colors, "RED", (val=0,&val));
|
|
H5Tenum_insert(hdf_en_colors, "GREEN", (val=1,&val));
|
|
H5Tenum_insert(hdf_en_colors, "BLUE", (val=2,&val));
|
|
H5Tenum_insert(hdf_en_colors, "WHITE", (val=3,&val));
|
|
H5Tenum_insert(hdf_en_colors, "BLACK", (val=4,&val));</pre>
|
|
|
|
|
|
<dt><code>herr_t H5Tlock(hid_t <em>etype</em>)</code>
|
|
<dd>This function locks a data type so it cannot be modified or
|
|
freed unless the entire HDF5 library is closed. Its use is
|
|
completely optional but using it on an application data type
|
|
makes that data type act like a predefined data type.
|
|
|
|
<pre>
|
|
H5Tlock(hdf_en_colors);</pre>
|
|
|
|
</dl>
|
|
|
|
<h3>7.3. Integer Operations</h2>
|
|
|
|
<p>Because an enumeration data type is derived from an integer
|
|
data type, any operation which can be performed on integer data
|
|
types can also be performed on enumeration data types. This
|
|
includes:
|
|
|
|
<p>
|
|
<center>
|
|
<table>
|
|
<tr>
|
|
<td><code>H5Topen()</code></td>
|
|
<td><code>H5Tcreate()</code></td>
|
|
<td><code>H5Tcopy()</code></td>
|
|
<td><code>H5Tclose()</code></td>
|
|
</tr><tr>
|
|
<td><code>H5Tequal()</code></td>
|
|
<td><code>H5Tlock()</code></td>
|
|
<td><code>H5Tcommit()</code></td>
|
|
<td><code>H5Tcommitted()</code></td>
|
|
</tr><tr>
|
|
<td><code>H5Tget_class()</code></td>
|
|
<td><code>H5Tget_size()</code></td>
|
|
<td><code>H5Tget_order()</code></td>
|
|
<td><code>H5Tget_pad()</code></td>
|
|
</tr><tr>
|
|
<td><code>H5Tget_precision()</code></td>
|
|
<td><code>H5Tget_offset()</code></td>
|
|
<td><code>H5Tget_sign()</code></td>
|
|
<td><code>H5Tset_size()</code></td>
|
|
</tr><tr>
|
|
<td><code>H5Tset_order()</code></td>
|
|
<td><code>H5Tset_precision()</code></td>
|
|
<td><code>H5Tset_offset()</code></td>
|
|
<td><code>H5Tset_pad()</code></td>
|
|
</tr><tr>
|
|
<td><code>H5Tset_sign()</code></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>In addition, the new function <code>H5Tget_super()</code> will
|
|
be defined for all data types that are derived from existing
|
|
types (currently just enumeration types).
|
|
|
|
<dl>
|
|
<dt><code>hid_t H5Tget_super(hid_t <em>type</em>)</code>
|
|
<dd>Return the data type from which <em>type</em> is
|
|
derived. When <em>type</em> is an enumeration data type then
|
|
the returned value will be an integer data type but not
|
|
necessarily a native type. One use of this function would be
|
|
to create a new enumeration type based on the same underlying
|
|
integer type and values but with possibly different symbols.
|
|
|
|
<pre>
|
|
hid_t itype = H5Tget_super(hdf_en_colors);
|
|
hid_t hdf_fr_colors = H5Tenum_create(itype);
|
|
H5Tclose(itype);
|
|
|
|
short val;
|
|
H5Tenum_insert(hdf_fr_colors, "ouge", (val=0,&val));
|
|
H5Tenum_insert(hdf_fr_colors, "vert", (val=1,&val));
|
|
H5Tenum_insert(hdf_fr_colors, "bleu", (val=2,&val));
|
|
H5Tenum_insert(hdf_fr_colors, "blanc", (val=3,&val));
|
|
H5Tenum_insert(hdf_fr_colors, "noir", (val=4,&val));
|
|
H5Tlock(hdf_fr_colors);</pre>
|
|
</dl>
|
|
|
|
<h3>7.4. Type Functions</h2>
|
|
|
|
<p>A small set of functions is available for querying properties
|
|
of an enumeration type. These functions are likely to be used
|
|
by browsers to display data type information.
|
|
|
|
<dl>
|
|
<dt><code>int H5Tget_nmembers(hid_t <em>etype</em>)</code>
|
|
<dd>When given an enumeration data type <em>etype</em> this
|
|
function returns the number of members defined for that
|
|
type. This function is already implemented for compound data
|
|
types.
|
|
|
|
<br><br>
|
|
<dt><code>char *H5Tget_member_name(hid_t <em>etype</em>, int
|
|
<em>membno</em>)</code>
|
|
<dd>Given an enumeration data type <em>etype</em> this function
|
|
returns the symbol name for the member indexed by
|
|
<em>membno</em>. Members are numbered from zero to
|
|
<em>N</em>-1 where <em>N</em> is the return value from
|
|
<code>H5Tget_nmembers()</code>. The members are stored in no
|
|
particular order. This function is already implemented for
|
|
compound data types. If an error occurs then the null pointer
|
|
is returned. The return value should be freed by calling
|
|
<code>free()</code>.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Tget_member_value(hid_t <em>etype</em>, int
|
|
<em>membno</em>, void *<em>value</em>/*out*/)</code>
|
|
<dd>Given an enumeration data type <em>etype</em> this function
|
|
returns the value associated with the member indexed by
|
|
<em>membno</em> (as described for
|
|
<code>H5Tget_member_name()</code>). The value returned
|
|
is in the domain of the underlying integer
|
|
data type which is often a native integer type. The
|
|
application should ensure that the memory pointed to by
|
|
<em>value</em> is large enough to contain the result (the size
|
|
can be obtained by calling <code>H5Tget_size()</code> on
|
|
either the enumeration type or the underlying integer type
|
|
when the type is not known by the C compiler.
|
|
|
|
<pre>
|
|
int i, n = H5Tget_nmembers(hdf_en_colors);
|
|
for (i=0; i<n; i++) {
|
|
char *symbol = H5Tget_member_name(hdf_en_colors, i);
|
|
short val;
|
|
H5Tget_member_value(hdf_en_colors, i, &val);
|
|
printf("#%d %20s = %d\n", i, symbol, val);
|
|
free(symbol);
|
|
}</pre>
|
|
|
|
<p>
|
|
Output:
|
|
<pre>
|
|
#0 BLACK = 4
|
|
#1 BLUE = 2
|
|
#2 GREEN = 1
|
|
#3 RED = 0
|
|
#4 WHITE = 3</pre>
|
|
</dl>
|
|
|
|
<h3>7.5. Data Functions</h2>
|
|
|
|
<p>In addition to querying about the enumeration type properties,
|
|
an application may want to make queries about enumerated
|
|
data. These functions perform efficient mappings between symbol
|
|
names and values.
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5Tenum_valueof(hid_t <em>etype</em>, const char
|
|
*<em>symbol</em>, void *<em>value</em>/*out*/)</code>
|
|
<dd>Given an enumeration data type <em>etype</em> this function
|
|
returns through <em>value</em> the bit pattern associated with
|
|
the symbol name <em>symbol</em>. The <em>value</em> argument
|
|
should point to memory which is large enough to hold the result,
|
|
which is returned as the underlying integer data type specified
|
|
when the enumeration type was created, often a native integer
|
|
type.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Tenum_nameof(hid_t <em>etype</em>, void
|
|
*<em>value</em>, char *<em>symbol</em>, size_t
|
|
<em>size</em>)</code>
|
|
<dd>This function translates a bit pattern pointed to by
|
|
<em>value</em> to a symbol name according to the mapping
|
|
defined in the enumeration data type <em>etype</em> and stores
|
|
at most <em>size</em> characters of that name (counting the
|
|
null terminator) to the <em>symbol</em> buffer. If the name is
|
|
longer than the result buffer then the result is not null
|
|
terminated and the function returns failure. If <em>value</em>
|
|
points to a bit pattern which is not in the domain of the
|
|
enumeration type then the first byte of the <em>symbol</em>
|
|
buffer is set to zero and the function fails.
|
|
|
|
<pre>
|
|
short data[1000] = {4, 2, 0, 0, 5, 1, ...};
|
|
int i;
|
|
char symbol[32];
|
|
|
|
for (i=0; i<1000; i++) {
|
|
if (H5Tenum_nameof(hdf_en_colors, data+i, symbol,
|
|
sizeof symbol))<0) {
|
|
if (symbol[0]) {
|
|
strcpy(symbol+sizeof(symbol)-4, "...");
|
|
} else {
|
|
strcpy(symbol, "UNKNOWN");
|
|
}
|
|
}
|
|
printf("%d %s\n", data[i], symbol);
|
|
}
|
|
printf("}\n");</pre>
|
|
|
|
<p>
|
|
Output:
|
|
<pre>
|
|
|
|
4 BLACK
|
|
2 BLUE
|
|
0 RED
|
|
0 RED
|
|
5 UNKNOWN
|
|
1 GREEN
|
|
...</pre>
|
|
</dl>
|
|
|
|
<h3>7.6. Conversion</h2>
|
|
|
|
<p>Enumerated data can be converted from one type to another
|
|
provided the destination enumeration type contains all the
|
|
symbols of the source enumeration type. The conversion operates
|
|
by matching up the symbol names of the source and destination
|
|
enumeration types to build a mapping from source value to
|
|
destination value. For instance, if we are translating from an
|
|
enumeration type that defines a sequence of integers as the
|
|
values for the colors to a type that defines a different bit for
|
|
each color then the mapping might look like this:
|
|
|
|
<p><img src="EnumMap.gif" alt="Enumeration Mapping">
|
|
|
|
<p>That is, a source value of <code>2</code> which corresponds to
|
|
<code>BLUE</code> would be mapped to <code>0x0004</code>. The
|
|
following code snippet builds the second data type, then
|
|
converts a raw data array from one data type to another, and
|
|
then prints the result.
|
|
|
|
<pre>
|
|
/* Create a new enumeration type */
|
|
short val;
|
|
hid_t bits = H5Tcreate(H5T_ENUM, sizeof val);
|
|
H5Tenum_insert(bits, "RED", (val=0x0001,&val));
|
|
H5Tenum_insert(bits, "GREEN", (val=0x0002,&val));
|
|
H5Tenum_insert(bits, "BLUE", (val=0x0004,&val));
|
|
H5Tenum_insert(bits, "WHITE", (val=0x0008,&val));
|
|
H5Tenum_insert(bits, "BLACK", (val=0x0010,&val));
|
|
|
|
/* The data */
|
|
short data[6] = {1, 4, 2, 0, 3, 5};
|
|
|
|
/* Convert the data from one type to another */
|
|
H5Tconvert(hdf_en_colors, bits, 5, data, NULL);
|
|
|
|
/* Print the data */
|
|
for (i=0; i<6; i++) {
|
|
printf("0x%04x\n", (unsigned)(data[i]));
|
|
}</pre>
|
|
|
|
<p>
|
|
Output:
|
|
<pre>
|
|
|
|
0x0002
|
|
0x0010
|
|
0x0004
|
|
0x0001
|
|
0x0008
|
|
0xffff</pre>
|
|
|
|
<p>If the source data stream contains values which are not in the
|
|
domain of the conversion map then an overflow exception is
|
|
raised within the library, causing the application defined
|
|
overflow handler to be invoked (see
|
|
<code>H5Tset_overflow()</code>). If no overflow handler is
|
|
defined then all bits of the destination value will be set.
|
|
|
|
<p>The HDF library will not provide conversions between enumerated
|
|
data and integers although the application is free to do so
|
|
(this is a policy we apply to all classes of HDF data
|
|
types). However, since enumeration types are derived from
|
|
integer types it is permissible to treat enumerated data as
|
|
integers and perform integer conversions in that context.
|
|
|
|
<h3>7.7. Symbol Order</h2>
|
|
|
|
<p>Symbol order is determined by the integer values associated
|
|
with each symbol. When the integer data type is a native type,
|
|
testing the relative order of two symbols is an easy process:
|
|
simply compare the values of the symbols. If only the symbol
|
|
names are available then the values must first be determined by
|
|
calling <code>H5Tenum_valueof()</code>.
|
|
|
|
<pre>
|
|
short val1, val2;
|
|
H5Tenum_valueof(hdf_en_colors, "WHITE", &val1);
|
|
H5Tenum_valueof(hdf_en_colors, "BLACK", &val2);
|
|
if (val1 < val2) ...</pre>
|
|
|
|
<p>When the underlying integer data type is not a native type then
|
|
the easiest way to compare symbols is to first create a similar
|
|
enumeration type that contains all the same symbols but has a
|
|
native integer type (HDF type conversion features can be used to
|
|
convert the non-native values to native values). Once we have a
|
|
native type we can compare symbol order as just described. If
|
|
<code>foreign</code> is some non-native enumeration type then a
|
|
native type can be created as follows:
|
|
|
|
<pre>
|
|
int n = H5Tget_nmembers(foreign);
|
|
hid_t itype = H5Tget_super(foreign);
|
|
void *val = malloc(n * MAX(H5Tget_size(itype), sizeof(int)));
|
|
char *name = malloc(n * sizeof(char*));
|
|
int i;
|
|
|
|
/* Get foreign type information */
|
|
for (i=0; i<n; i++) {
|
|
name[i] = H5Tget_member_name(foreign, i);
|
|
H5Tget_member_value(foreign, i,
|
|
(char*)val+i*H5Tget_size(foreign));
|
|
}
|
|
|
|
/* Convert integer values to new type */
|
|
H5Tconvert(itype, H5T_NATIVE_INT, n, val, NULL);
|
|
|
|
/* Build a native type */
|
|
hid_t native = H5Tenum_create(H5T_NATIVE_INT);
|
|
for (i=0; i<n; i++) {
|
|
H5Tenum_insert(native, name[i], ((int*)val)[i]);
|
|
free(name[i]);
|
|
}
|
|
free(name);
|
|
free(val);</pre>
|
|
|
|
<p>It is also possible to convert enumerated data to a new type
|
|
that has a different order defined for the symbols. For
|
|
instance, we can define a new type, <code>reverse</code> that
|
|
defines the same five colors but in the reverse order.
|
|
|
|
<pre>
|
|
short val;
|
|
int i;
|
|
char sym[8];
|
|
short data[5] = {0, 1, 2, 3, 4};
|
|
|
|
hid_t reverse = H5Tenum_create(H5T_NATIVE_SHORT);
|
|
H5Tenum_insert(reverse, "BLACK", (val=0,&val));
|
|
H5Tenum_insert(reverse, "WHITE", (val=1,&val));
|
|
H5Tenum_insert(reverse, "BLUE", (val=2,&val));
|
|
H5Tenum_insert(reverse, "GREEN", (val=3,&val));
|
|
H5Tenum_insert(reverse, "RED", (val=4,&val));
|
|
|
|
/* Print data */
|
|
for (i=0; i<5; i++) {
|
|
H5Tenum_nameof(hdf_en_colors, data+i, sym, sizeof sym);
|
|
printf ("%d %s\n", data[i], sym);
|
|
}
|
|
|
|
puts("Converting...");
|
|
H5Tconvert(hdf_en_colors, reverse, 5, data, NULL);
|
|
|
|
/* Print data */
|
|
for (i=0; i<5; i++) {
|
|
H5Tenum_nameof(reverse, data+i, sym, sizeof sym);
|
|
printf ("%d %s\n", data[i], sym);
|
|
}</pre>
|
|
|
|
<p>
|
|
Output:
|
|
<pre>
|
|
0 RED
|
|
1 GREEN
|
|
2 BLUE
|
|
3 WHITE
|
|
4 BLACK
|
|
Converting...
|
|
4 RED
|
|
3 GREEN
|
|
2 BLUE
|
|
1 WHITE
|
|
0 BLACK</pre>
|
|
|
|
<h3>7.8. Equality</h2>
|
|
|
|
<p>The order that members are inserted into an enumeration type is
|
|
unimportant; the important part is the associations between the
|
|
symbol names and the values. Thus, two enumeration data types
|
|
will be considered equal if and only if both types have the same
|
|
symbol/value associations and both have equal underlying integer
|
|
data types. Type equality is tested with the
|
|
<code>H5Tequal()</code> function.
|
|
|
|
<h3>7.9. Interacting with C's <code>enum</code> Type</h2>
|
|
|
|
<p>Although HDF enumeration data types are similar to C
|
|
<code>enum</code> data types, there are some important
|
|
differences:
|
|
|
|
<p>
|
|
<center>
|
|
<table border width="80%">
|
|
<tr>
|
|
<th>Difference</th>
|
|
<th>Motivation/Implications</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>Symbols are unquoted in C but quoted in
|
|
HDF.</td>
|
|
<td valign=top>This allows the application to manipulate
|
|
symbol names in ways that are not possible with C.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>The C compiler automatically replaces all
|
|
symbols with their integer values but HDF requires
|
|
explicit calls to do the same.</td>
|
|
<td valign=top>C resolves symbols at compile time while
|
|
HDF resolves symbols at run time.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>The mapping from symbols to integers is
|
|
<em>N</em>:1 in C but 1:1 in HDF.</td>
|
|
<td valign=top>HDF can translate from value to name
|
|
uniquely and large <code>switch</code> statements are
|
|
not necessary to print values in human-readable
|
|
format.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>A symbol must appear in only one C
|
|
<code>enum</code> type but may appear in multiple HDF
|
|
enumeration types.</td>
|
|
<td valign=top>The translation from symbol to value in HDF
|
|
requires the data type to be specified while in C the
|
|
data type is not necessary because it can be inferred
|
|
from the symbol.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>The underlying integer value is always a
|
|
native integer in C but can be a foreign integer type in
|
|
HDF.</td>
|
|
<td valign=top>This allows HDF to describe data that might
|
|
reside on a foreign architecture, such as data stored in
|
|
a file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top>The sign and size of the underlying integer
|
|
data type is chosen automatically by the C compiler but
|
|
must be fully specified with HDF.</td>
|
|
<td valign=top>Since HDF doesn't require finalization of a
|
|
data type, complete specification of the type must be
|
|
supplied before the type is used. Requiring that
|
|
information at the time of type creation was a design
|
|
decision to simplify the library.</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The examples below use the following C data types:
|
|
|
|
<p>
|
|
<table width="90%" bgcolor="white">
|
|
<tr>
|
|
<td>
|
|
<code><pre>
|
|
/* English color names */
|
|
typedef enum {
|
|
RED,
|
|
GREEN,
|
|
BLUE,
|
|
WHITE,
|
|
BLACK
|
|
} c_en_colors;
|
|
|
|
/* Spanish color names, reverse order */
|
|
typedef enum {
|
|
NEGRO
|
|
BLANCO,
|
|
AZUL,
|
|
VERDE,
|
|
ROJO,
|
|
} c_sp_colors;
|
|
|
|
/* No enum definition for French names */
|
|
</pre></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Creating HDF Types from C Types</h3>
|
|
|
|
<p>An HDF enumeration data type can be created from a C
|
|
<code>enum</code> type simply by passing pointers to the C
|
|
<code>enum</code> values to <code>H5Tenum_insert()</code>. For
|
|
instance, to create HDF types for the <code>c_en_colors</code>
|
|
type shown above:
|
|
|
|
<p>
|
|
<table width="90%" bgcolor="white">
|
|
<tr>
|
|
<td>
|
|
<code><pre>
|
|
|
|
c_en_colors val;
|
|
hid_t hdf_en_colors = H5Tcreate(H5T_ENUM, sizeof(c_en_colors));
|
|
H5Tenum_insert(hdf_en_colors, "RED", (val=RED, &val));
|
|
H5Tenum_insert(hdf_en_colors, "GREEN", (val=GREEN,&val));
|
|
H5Tenum_insert(hdf_en_colors, "BLUE", (val=BLUE, &val));
|
|
H5Tenum_insert(hdf_en_colors, "WHITE", (val=WHITE,&val));
|
|
H5Tenum_insert(hdf_en_colors, "BLACK", (val=BLACK,&val));</pre></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Name Changes between Applications</h3>
|
|
|
|
<p>Occassionally two applicatons wish to exchange data but they
|
|
use different names for the constants they exchange. For
|
|
instance, an English and a Spanish program may want to
|
|
communicate color names although they use different symbols in
|
|
the C <code>enum</code> definitions. The communication is still
|
|
possible although the applications must agree on common terms
|
|
for the colors. The following example shows the Spanish code to
|
|
read the values assuming that the applications have agreed that
|
|
the color information will be exchanged using Enlish color
|
|
names:
|
|
|
|
<p>
|
|
<table width="90%" bgcolor="white">
|
|
<tr>
|
|
<td>
|
|
<code><pre>
|
|
|
|
c_sp_colors val, data[1000];
|
|
hid_t hdf_sp_colors = H5Tcreate(H5T_ENUM, sizeof(c_sp_colors));
|
|
H5Tenum_insert(hdf_sp_colors, "RED", (val=ROJO, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "GREEN", (val=VERDE, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "BLUE", (val=AZUL, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "WHITE", (val=BLANCO, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "BLACK", (val=NEGRO, &val));
|
|
|
|
H5Dread(dataset, hdf_sp_colors, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);</pre></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h4>Symbol Ordering across Applications</h3>
|
|
|
|
<p>Since symbol ordering is completely determined by the integer values
|
|
assigned to each symbol in the <code>enum</code> definition,
|
|
ordering of <code>enum</code> symbols cannot be preserved across
|
|
files like with HDF enumeration types. HDF can convert from one
|
|
application's integer values to the other's so a symbol in one
|
|
application's C <code>enum</code> gets mapped to the same symbol
|
|
in the other application's C <code>enum</code>, but the relative
|
|
order of the symbols is not preserved.
|
|
|
|
<p>For example, an application may be defined to use the
|
|
definition of <code>c_en_colors</code> defined above where
|
|
<code>WHITE</code> is less than <code>BLACK</code>, but some
|
|
other application might define the colors in some other
|
|
order. If each application defines an HDF enumeration type based
|
|
on that application's C <code>enum</code> type then HDF will
|
|
modify the integer values as data is communicated from one
|
|
application to the other so that a <code>RED</code> value
|
|
in the first application is also a <code>RED</code> value in the
|
|
other application.
|
|
|
|
<p>A case of this reordering of symbol names was also shown in the
|
|
previous code snippet (as well as a change of language), where
|
|
HDF changed the integer values so 0 (<code>RED</code>) in the
|
|
input file became 4 (<code>ROJO</code>) in the <code>data</code>
|
|
array. In the input file, <code>WHITE</code> was less than
|
|
<code>BLACK</code>; in the application the opposite is true.
|
|
|
|
<p>In fact, the ability to change the order of symbols is often
|
|
convenient when the enumeration type is used only to group
|
|
related symbols that don't have any well defined order
|
|
relationship.
|
|
|
|
<h4>Internationalization</h3>
|
|
|
|
<p>The HDF enumeration type conversion features can also be used
|
|
to provide internationalization of debugging output. A program
|
|
written with the <code>c_en_colors</code> data type could define
|
|
a separate HDF data type for languages such as English, Spanish,
|
|
and French and cast the enumerated value to one of these HDF
|
|
types to print the result.
|
|
|
|
<p>
|
|
<table width="90%" bgcolor="white">
|
|
<tr>
|
|
<td>
|
|
<code><pre>
|
|
|
|
c_en_colors val, *data=...;
|
|
|
|
hid_t hdf_sp_colors = H5Tcreate(H5T_ENUM, sizeof val);
|
|
H5Tenum_insert(hdf_sp_colors, "ROJO", (val=RED, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "VERDE", (val=GREEN, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "AZUL", (val=BLUE, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "BLANCO", (val=WHITE, &val));
|
|
H5Tenum_insert(hdf_sp_colors, "NEGRO", (val=BLACK, &val));
|
|
|
|
hid_t hdf_fr_colors = H5Tcreate(H5T_ENUM, sizeof val);
|
|
H5Tenum_insert(hdf_fr_colors, "OUGE", (val=RED, &val));
|
|
H5Tenum_insert(hdf_fr_colors, "VERT", (val=GREEN, &val));
|
|
H5Tenum_insert(hdf_fr_colors, "BLEU", (val=BLUE, &val));
|
|
H5Tenum_insert(hdf_fr_colors, "BLANC", (val=WHITE, &val));
|
|
H5Tenum_insert(hdf_fr_colors, "NOIR", (val=BLACK, &val));
|
|
|
|
void
|
|
nameof(lang_t language, c_en_colors val, char *name, size_t size)
|
|
{
|
|
switch (language) {
|
|
case ENGLISH:
|
|
H5Tenum_nameof(hdf_en_colors, &val, name, size);
|
|
break;
|
|
case SPANISH:
|
|
H5Tenum_nameof(hdf_sp_colors, &val, name, size);
|
|
break;
|
|
case FRENCH:
|
|
H5Tenum_nameof(hdf_fr_colors, &val, name, size);
|
|
break;
|
|
}
|
|
}</pre></code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>7.10. Goals That Have Been Met</h2>
|
|
|
|
<p>The main goal of enumeration types is to provide communication
|
|
of enumerated data using symbolic equivalence. That is, a
|
|
symbol written to a dataset by one application should be read as
|
|
the same symbol by some other application.
|
|
|
|
<p>
|
|
<table width="90%">
|
|
<tr>
|
|
<td valign=top><b>Architecture Independence</b></td>
|
|
<td valign=top>Two applications shall be able to exchange
|
|
enumerated data even when the underlying integer values
|
|
have different storage formats. HDF accomplishes this for
|
|
enumeration types by building them upon integer types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Preservation of Order Relationship</b></td>
|
|
<td valign=top>The relative order of symbols shall be
|
|
preserved between two applications that use equivalent
|
|
enumeration data types. Unlike numeric values that have
|
|
an implicit ordering, enumerated data has an explicit
|
|
order defined by the enumeration data type and HDF
|
|
records this order in the file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Order Independence</b></td>
|
|
<td valign=top>An application shall be able to change the
|
|
relative ordering of the symbols in an enumeration data
|
|
type. This is accomplished by defining a new type with
|
|
different integer values and converting data from one type
|
|
to the other.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Subsets</b></td>
|
|
<td valign=top>An application shall be able to read
|
|
enumerated data from an archived dataset even after the
|
|
application has defined additional members for the
|
|
enumeration type. An application shall be able to write
|
|
to a dataset when the dataset contains a superset of the
|
|
members defined by the application. Similar rules apply
|
|
for in-core conversions between enumerated data
|
|
types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Targetable</b></td>
|
|
<td valign=top>An application shall be able to target a
|
|
particular architecture or application when storing
|
|
enumerated data. This is accomplished by allowing
|
|
non-native underlying integer types and converting the
|
|
native data to non-native data.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Efficient Data Transfer</b></td>
|
|
<td valign=top>An application that defines a file dataset
|
|
that corresponds to some native C enumerated data array
|
|
shall be able to read and write to that dataset directly
|
|
using only Posix read and write functions. HDF already
|
|
optimizes this case for integers, so the same optimization
|
|
will apply to enumerated data.
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign=top><b>Efficient Storage</b></td>
|
|
<td valign=top>Enumerated data shall be stored in a manner
|
|
which is space efficient. HDF stores the enumerated data
|
|
as integers and allows the application to chose the size
|
|
and format of those integers.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<p align=right><font size=-1><i>
|
|
(Return to <a href="Datatypes.html#Datatypes_Enum">Data Types Interface (H5T)</a>.)
|
|
</font></i>
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
Data Types
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
<!-- Created: Thu Dec 4 14:57:32 EST 1997 -->
|
|
<!-- hhmts start -->
|
|
Last modified: 30 April 1999
|
|
<!-- hhmts end -->
|
|
|
|
<br>
|
|
Describes HDF5 Release 1.4 Beta, December 2000
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|