From a3d84da7df8e3d4226eb937cbabd3384fabd2762 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Mon, 3 May 1999 16:54:10 -0500 Subject: [PATCH] [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. --- doc/html/Datatypes.html | 21 +- doc/html/DatatypesEnum.html | 921 ++++++++++++++++++++++++++++++++++++ doc/html/EnumMap.gif | Bin 0 -> 1682 bytes doc/html/H5.intro.html | 2 +- doc/html/Tools.html | 16 +- 5 files changed, 949 insertions(+), 11 deletions(-) create mode 100644 doc/html/DatatypesEnum.html create mode 100644 doc/html/EnumMap.gif diff --git a/doc/html/Datatypes.html b/doc/html/Datatypes.html index 604b4802f7..f0872b60b6 100644 --- a/doc/html/Datatypes.html +++ b/doc/html/Datatypes.html @@ -1150,7 +1150,21 @@ H5Tinsert (surf_id, "y", HOFFSET(surf_t,y), complex_id); -

7. Sharing Data Types among Datasets

+   +

7. Enumeration Data Types

+ + An HDF5 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. +

+ Details of enumeration data types and the related functions + are discussed on a separate + Enumeration Data Types page. + +

8. Sharing Data Types among Datasets

If a file has lots of datasets which have a common data type then the file could be made smaller by having all the datasets @@ -1196,7 +1210,7 @@ hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT); -

8. Data Conversion

+

9. Data Conversion

The library is capable of converting data from one type to @@ -1553,7 +1567,6 @@ H5Tregister(H5T_PERS_SOFT, "cus2be", conversion path whether that conversion path was actually used or not. -<<<<<<< Datatypes.html

@@ -1621,7 +1634,7 @@ And in this document, the -Last modified: Wed Dec 16 13:04:58 EST 1998 +Last modified: 30 April 1999 diff --git a/doc/html/DatatypesEnum.html b/doc/html/DatatypesEnum.html new file mode 100644 index 0000000000..414ab2f887 --- /dev/null +++ b/doc/html/DatatypesEnum.html @@ -0,0 +1,921 @@ + + + + Enumeration Data Types in the Data Type Interface (H5T) + + + + + +
+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     + Files   +
+ Datasets   + Data Types   + Dataspaces   + Groups   + References   +
+ Attributes   + Property Lists   + Error Handling   + Filters   + Caching   +
+ Chunking   + Debugging   + Environment   + DDL   + Ragged Arrays   + +
+
+
+ + +

The Data Type Interface (H5T) (contitnued)

+ +

+ (Return to Data Types Interface (H5T).) + + +

7. Enumeration Data Types

+ +

7.1. Introduction

+ +

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. + +

7.2. Creation

+ +

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. + +

+
hid_t H5Tcreate(H5T_class_t type_class, + size_t size) +
This function creates a new empty enumeration data type based + on a native signed integer type. The first argument is the + constant H5T_ENUM 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. + + 
+/* Based on a native signed short */
+hid_t hdf_en_colors = H5Tcreate(H5T_ENUM, sizeof(short));
+ + +
hid_t H5Tenum_create(hid_t base) +
This function creates a new empty enumeration data type based + on some integer data type base and is a + generalization of the H5Tcreate() 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. + + 
+/* 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);
+ + +
herr_t H5Tenum_insert(hid_t etype, const char + *symbol, void *value) +
Members are inserted into the enumeration data type + etype with this function. Each member has a symbolic + name symbol and some integer representation + value. The value 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. + + 
+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));
+ + +
herr_t H5Tlock(hid_t etype) +
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. + + 
+H5Tlock(hdf_en_colors);
+ +
+ +

7.3. Integer Operations

+ +

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: + +

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
H5Topen()H5Tcreate()H5Tcopy()H5Tclose()
H5Tequal()H5Tlock()H5Tcommit()H5Tcommitted()
H5Tget_class()H5Tget_size()H5Tget_order()H5Tget_pad()
H5Tget_precision()H5Tget_offset()H5Tget_sign()H5Tset_size()
H5Tset_order()H5Tset_precision()H5Tset_offset()H5Tset_pad()
H5Tset_sign()
+
+ +

In addition, the new function H5Tget_super() will + be defined for all data types that are derived from existing + types (currently just enumeration types). + +

+
hid_t H5Tget_super(hid_t type) +
Return the data type from which type is + derived. When type 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. + + 
+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);
+
+ +

7.4. Type Functions

+ +

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. + +

+
int H5Tget_nmembers(hid_t etype) +
When given an enumeration data type etype this + function returns the number of members defined for that + type. This function is already implemented for compound data + types. + +

+
char *H5Tget_member_name(hid_t etype, int + membno) +
Given an enumeration data type etype this function + returns the symbol name for the member indexed by + membno. Members are numbered from zero to + N-1 where N is the return value from + H5Tget_nmembers(). 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 + free(). + +

+
herr_t H5Tget_member_value(hid_t etype, int + membno, void *value/*out*/) +
Given an enumeration data type etype this function + returns the value associated with the member indexed by + membno (as described for + H5Tget_member_name()). 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 + value is large enough to contain the result (the size + can be obtained by calling H5Tget_size() on + either the enumeration type or the underlying integer type + when the type is not known by the C compiler. + + 
+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);
+}
+ +

+ Output: + 

+#0                BLACK = 4
+#1                 BLUE = 2
+#2                GREEN = 1
+#3                  RED = 0
+#4                WHITE = 3
+
+ +

7.5. Data Functions

+ +

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. + +

+
herr_t H5Tenum_valueof(hid_t etype, const char + *symbol, void *value/*out*/) +
Given an enumeration data type etype this function + returns through value the bit pattern associated with + the symbol name symbol. The value 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. + +

+
herr_t H5Tenum_nameof(hid_t etype, void + *value, char *symbol, size_t + size) +
This function translates a bit pattern pointed to by + value to a symbol name according to the mapping + defined in the enumeration data type etype and stores + at most size characters of that name (counting the + null terminator) to the symbol buffer. If the name is + longer than the result buffer then the result is not null + terminated and the function returns failure. If value + points to a bit pattern which is not in the domain of the + enumeration type then the first byte of the symbol + buffer is set to zero and the function fails. + + 
+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");
+ +

+ Output: + 

+
+4 BLACK
+2 BLUE
+0 RED
+0 RED
+5 UNKNOWN
+1 GREEN
+...
+
+ +

7.6. Conversion

+ +

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: + +

Enumeration Mapping + +

That is, a source value of 2 which corresponds to + BLUE would be mapped to 0x0004. 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. + + 

+/* 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]));
+}
+ +

+ Output: + 

+
+0x0002
+0x0010
+0x0004
+0x0001
+0x0008
+0xffff
+ +

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 + H5Tset_overflow()). If no overflow handler is + defined then all bits of the destination value will be set. + +

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. + +

7.7. Symbol Order

+ +

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 H5Tenum_valueof(). + + 

+short val1, val2;
+H5Tenum_valueof(hdf_en_colors, "WHITE", &val1);
+H5Tenum_valueof(hdf_en_colors, "BLACK", &val2);
+if (val1 < val2) ...
+ +

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 + foreign is some non-native enumeration type then a + native type can be created as follows: + + 

+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);
+ +

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, reverse that + defines the same five colors but in the reverse order. + + 

+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);
+}
+ +

+ Output: + 

+0 RED
+1 GREEN
+2 BLUE
+3 WHITE
+4 BLACK
+Converting...
+4 RED
+3 GREEN
+2 BLUE
+1 WHITE
+0 BLACK
+ +

7.8. Equality

+ +

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 + H5Tequal() function. + +

7.9. Interacting with C's enum Type

+ +

Although HDF enumeration data types are similar to C + enum data types, there are some important + differences: + +

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DifferenceMotivation/Implications
Symbols are unquoted in C but quoted in + HDF.This allows the application to manipulate + symbol names in ways that are not possible with C.
The C compiler automatically replaces all + symbols with their integer values but HDF requires + explicit calls to do the same.C resolves symbols at compile time while + HDF resolves symbols at run time.
The mapping from symbols to integers is + N:1 in C but 1:1 in HDF.HDF can translate from value to name + uniquely and large switch statements are + not necessary to print values in human-readable + format.
A symbol must appear in only one C + enum type but may appear in multiple HDF + enumeration types.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.
The underlying integer value is always a + native integer in C but can be a foreign integer type in + HDF.This allows HDF to describe data that might + reside on a foreign architecture, such as data stored in + a file.
The sign and size of the underlying integer + data type is chosen automatically by the C compiler but + must be fully specified with HDF.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.
+
+ +

The examples below use the following C data types: + +

+ + + + +
+ 
+/* 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 */
+
+
+ +

Creating HDF Types from C Types

+ +

An HDF enumeration data type can be created from a C + enum type simply by passing pointers to the C + enum values to H5Tenum_insert(). For + instance, to create HDF types for the c_en_colors + type shown above: + +

+ + + + +
+ 
+
+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));
 +
+ +

Name Changes between Applications

+ +

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 enum 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: + +

+ + + + +
+ 
+
+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);
 +
+ + +

Symbol Ordering across Applications

+ +

Since symbol ordering is completely determined by the integer values + assigned to each symbol in the enum definition, + ordering of enum 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 enum gets mapped to the same symbol + in the other application's C enum, but the relative + order of the symbols is not preserved. + +

For example, an application may be defined to use the + definition of c_en_colors defined above where + WHITE is less than BLACK, 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 enum type then HDF will + modify the integer values as data is communicated from one + application to the other so that a RED value + in the first application is also a RED value in the + other application. + +

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 (RED) in the + input file became 4 (ROJO) in the data + array. In the input file, WHITE was less than + BLACK; in the application the opposite is true. + +

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. + +

Internationalization

+ +

The HDF enumeration type conversion features can also be used + to provide internationalization of debugging output. A program + written with the c_en_colors 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. + +

+ + + + +
+ 
+
+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;
+    }
+}
 +
+ +

7.10. Goals That Have Been Met

+ +

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. + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Architecture IndependenceTwo 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.
Preservation of Order RelationshipThe 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.
Order IndependenceAn 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.
SubsetsAn 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.
TargetableAn 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.
Efficient Data TransferAn 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. +
Efficient StorageEnumerated 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.
+ + +

+ (Return to Data Types Interface (H5T).) + + +

+
+ + + +
+ Introduction to HDF5 
+ HDF5 Reference Manual 
+ Other HDF5 documents and links 
+ +		 + And in this document, the + HDF5 User's Guide:     + Files   +
+ Datasets   + Data Types   + Dataspaces   + Groups   + References   +
+ Attributes   + Property Lists   + Error Handling   + Filters   + Caching   +
+ Chunking   + Debugging   + Environment   + DDL   + Ragged Arrays   + +
+
+ + +
+
+HDF Help Desk +
+ + +Last modified: 30 April 1999 + + + + + diff --git a/doc/html/EnumMap.gif b/doc/html/EnumMap.gif new file mode 100644 index 0000000000000000000000000000000000000000..d06f06a09bb91ff5e2fbc70457dd5aef36ce5724 GIT binary patch literal 1682 zcmV;D25tFANk%v~VNn5b0Du4h00030|Nkri0000{0dW8T0{(=LsmtvTqnxzbi?iOm z#{h=nNS5Y_rs~SJ?hD8AOxN~}8u-rl{tpZahdv$gh)gP%%qGm}j7q1}s#OHNYPa03 zH>QvCkIT#Gx&4k$*7N+npSJfWI7m1WScsU2cc|FtsK)pxIms1C zd5P&{3F6V|`FZdMI!cPsvKjD}c`CZf%7Ut@6uKtMXG_OO%bB&yd4lWqsuvOrhQN!Q z&|_@Z{Dhpky!=!QY@LcNtLkfb`b+};vt9k0ZBD);4!1tct&Q!HUXorPe@_2Bj5P25 zYunF8J2nGX*aLVEmbFj};i0?ttYEAq0S)f*RT0pf{%!?TM3aWloV<8%=Dm9;5??rd z3TGuWD6%A$mm1|LNLk}#wvZ}Ys^qCN=u8t5B~qjb#^KPOIZHYHfWw|QoG@eJlX|XS zM3z;FQT3=)sJe~RIwnP#6={yJR=L#M z5DK-a7WcVY>t`^fqK+REZDsjvW1pEXNA3)H^Ip)5Z;|#a8tmznpI4VYR(ZALF|#F6 z=Iom3o!XCXkLK5gw-@1b#bNA)yqRy+dh}ueOzWm}ZkC8wf(1Rhj_HT}p%#nP*mBJ- zV}x&8Pbc|2?asS>f47`&^lab17KR(R`T8>c7e0@B-)>!j_tQ`6`Bc(&+woUlfJDu8 z)P9Csl-x}HF~=7!?S(^OVhCO6-A*LYhm&$#Vdzyk@wxS(h4Zl%$4xH|wIVq!`sbHc zOA(mTR@lXMh79fnLu6qVJ%uD*%<;ICHaU)H5{dTZ^J9KTNH!#c(pU*eSp!PRqjOoJ z#iV#Au6M>q@<5l&G;SVvjZJ-FM_rw7GPL3g(QQ-ba~>jA$9SRTHe-y0s>LCYq*=EG zqlgF^=b?^XF)1OCqDE+?RcI>6rBq6a8K_nMCR?bPo;hf4oKCT7YpJ1`W~)HRs!1)n zREQXi4$7tItcc3B=bsJCKx-3&l~w-XuzIRBrh%Bk#$^y0X$Gfz683?mQX@`@V5DXG z_o+t^>R0He)xyJDu}ox(*0vyy^pAoUe*4d}_>p?0c^ARhXH7BAsjp)EcDJlmQNrht ziKC)OZoz3W_D;HFMZ@mHJJx$GPY9FA?XUkuD=o2FS`0{%CNJhNy|qPo@Od)snkdNQ zcswwC3BDy?hS3Sh-_0E_31-ku4t+1fL!f-5c6{3D9L-{I6tL2{3U(}DhJoZ~)>^|n zVXvL38=*O{4};;9S6dK%jetBPu*Zex2WfL+VHwyAW#O?IiS-kmnz zMKsN--(+;d;h$3zO!QxBGydaruG1xm=L3clBrfKe3r2NdDSIn)MxN>#ws$(BH1FoM zd^x35t&jd)=`@|rwGdDCxB9~}btHGbVDS!7!XjpjbweC)tQ+o;r@0^RY8Lr8zG*-` zd{)!z%6PXJGcOj_;X-SDkjoO^BlqP#f4!I4htJfF@@d>G{FP5stDZjhUcCM%|KFHA zX)JvrGnl(ZW+uSdO?c~D$-$@s6xR*Mec8hq^>F6B`Ux#}S1aGF5GOs%fev&pgIoJF zq>w&kPCHZ!n31+5K7t)bVPjih*%T+Z8rmy|rpcT0Dz}Q@nGbE`Gg{nmcti#6Fo}5c zVcnLvC?rNviQ~KB{^0(m!z#{=4pN+;ad4H8?llmG9{eCQf;Axxv1t=RJX+`2w6(+F zX?~=$Sp-p6G!usGSlVim>?X%Kpv~uwaDtt=EO;?IN=|}N8Dk>N)G|l5QFpL|Bmk|QIR3jTkYaUvBtscU%3<{ zk$M@&U2<}H1ZaLU&dz1LkNXEc*35CvNS|;JRr!&3~j@?;|7=LI>%b3zvPMjq+T`|y^ z6*Qd(4PqB}zjn-qW+I_Q$lDn4N5n-~6riDdrbjm*ijRu40}-{TNxw$XldAM-DP5^c z8`aX6%9IMNoT*LO6VsdOv^hKNsUvFY)1aCGs6s937l>-qq-p`FN^L5ua_ZEm8dR!O cg=tl

Four parameters are required to describe a completely general hyperslab. Each parameter is an array whose rank is the same as that of the dataspace:

    -
  • start: a starting location for the hyperslab. In the example start is (1,0). +
  • start: a starting location for the hyperslab. In the example start is (0,1).
  • stride: the number of elements to separate each element or block to be selected. In the example stride is (4,3). If the stride parameter is set to NULL, the stride size defaults to 1 in each dimension.
  • count: the number of elements or blocks to select along each dimension. In the example, count is (2,4).
  • block: the size of the block selected from the dataspace. In the example, block is (3,2). If the block parameter is set to NULL, the block size defaults to a single element in each dimension, as if the block array was set to all 1s.
diff --git a/doc/html/Tools.html b/doc/html/Tools.html index 33ab2274bf..fbbf31d38a 100644 --- a/doc/html/Tools.html +++ b/doc/html/Tools.html @@ -326,10 +326,9 @@ These tools enable the user to examine HDF5 files interactively.

The -h option causes the following syntax summary to be displayed:
-

- h5toh4 file.h5 file.hdf
- h5toh4 file.h5
- h5toh4 -m file1.h5 file2.h5 ...
 + 
              h5toh4 file.h5 file.hdf
+              h5toh4 file.h5
+              h5toh4 -m file1.h5 file2.h5 ...

@@ -358,6 +357,11 @@ These tools enable the user to examine HDF5 files interactively. be fixed or extendable. The members of the compound datatype are constrained to be no more than rank 4. +

  • HDF5 dataset objects of single dimension and fixed length string + datatype are converted into HDF4 Vdata objects. The HDF4 Vdata is a + single field whose order is the length of the HDF5 string type. The + number of records of the Vdata is the length of the single dimension + which may be fixed or extendable. Other objects are not converted and are not recorded @@ -365,7 +369,7 @@ These tools enable the user to examine HDF5 files interactively.

    Attributes associated with any of the supported HDF5 objects are carried over to the HDF4 objects. - Attributes may be of integer or floating point datatype + Attributes may be of integer, floating point, or fixed length string datatype and they may have up to 32 fixed dimensions.

    All datatypes are converted to big-endian. @@ -432,7 +436,7 @@ Tools   HDF Help Desk
    -Last modified: 30 October 1998 +Last modified: 29 April 1999