diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1999-05-03 21:54:10 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1999-05-03 21:54:10 (GMT) |
| commit | a3d84da7df8e3d4226eb937cbabd3384fabd2762 (patch) | |
| tree | 8576203277e9ce7e64da91f858650917b326934b /doc/html/DatatypesEnum.html | |
| parent | 2ea07058c9fd49188d57b15699fbca05510b4da1 (diff) | |
| download | hdf5-a3d84da7df8e3d4226eb937cbabd3384fabd2762.zip hdf5-a3d84da7df8e3d4226eb937cbabd3384fabd2762.tar.gz hdf5-a3d84da7df8e3d4226eb937cbabd3384fabd2762.tar.bz2 | |
[svn-r1244] Datatypes.html
DatatypesEnum.html
EnumMap.gif
Added enumeration datatypes -- First pass, only minimal editing.
Intro paragraph in Datatypes.html; details in DatatypesEnum.html.
EnumMap.gif is a figure for DatatypesEnum.html.
Tools.html
Added new h5toh4 supported object and data type.
H5.intro.html
Corrected transposed "start coordinates" in Example 1.
Diffstat (limited to 'doc/html/DatatypesEnum.html')
| -rw-r--r-- | doc/html/DatatypesEnum.html | 921 |
1 files changed, 921 insertions, 0 deletions
diff --git a/doc/html/DatatypesEnum.html b/doc/html/DatatypesEnum.html new file mode 100644 index 0000000..414ab2f --- /dev/null +++ b/doc/html/DatatypesEnum.html @@ -0,0 +1,921 @@ +<!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 --> + + +</body> +</html> |