mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2025-04-06 18:00:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

added anchors for reading_attributes and writing_attributes, and refs to them, also changed order of files in Doxygen.in

Browse Source
This commit is contained in:
edwardhartnett 2019-11-08 05:19:51 -07:00
parent 09fe16c847
commit c76dae1c5d
4 changed files with 106 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/Doxyfile.in
View File

@ -778,11 +778,11 @@ INPUT = \
@abs_top_srcdir@/libdispatch/dvar.c \
@abs_top_srcdir@/libdispatch/dvarget.c \
@abs_top_srcdir@/libdispatch/dvarinq.c \
@abs_top_srcdir@/libdispatch/dvarput.c \
@abs_top_srcdir@/libdispatch/datt.c \
@abs_top_srcdir@/libdispatch/dattget.c \
@abs_top_srcdir@/libdispatch/dattinq.c \
@abs_top_srcdir@/libdispatch/dattget.c \
@abs_top_srcdir@/libdispatch/dvarput.c \
@abs_top_srcdir@/libdispatch/dattput.c \
@abs_top_srcdir@/libdispatch/datt.c \
@abs_top_srcdir@/libdispatch/dgroup.c \
@abs_top_srcdir@/libdispatch/dtype.c \
@abs_top_srcdir@/libdispatch/dcompound.c \

40
libdispatch/datt.c
View File

@ -18,39 +18,22 @@
* properties as units, special values, maximum and minimum valid
* values, scaling factors, and offsets.
*
* For netCDF classic formats, attributes are defined when the dataset
* is first created, while the netCDF dataset is in define
* mode. Additional attributes may be added later by reentering define
* mode. For netCDF-4/HDF5 netCDF files, attributes may be defined at
* any time.
*
* A netCDF attribute has a netCDF variable to which it is assigned, a
* name, a type, a length, and a sequence of one or more values.
* It is also possible to have attributes that are not associated with
* any variable. These are called global attributes and are identified
* by using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
* related to the netCDF dataset as a whole and may be used for
* purposes such as providing a title or processing history for a
* netCDF dataset. In netCDF-4/HDF5 files, global attributes are
* associated with a hierarchical group.
*
* An attribute is designated by its variable ID and name. When an
* attribute name is not known, it may be designated by its variable
* ID and number in order to determine its name, using the function
* nc_inq_attname().
*
* The attributes associated with a variable are typically defined
* immediately after the variable is created, while still in define
* mode. In classic format files, the data type, length, and value of
* an attribute may be changed even when in data mode, as long as the
* changed attribute requires no more space than the attribute as
* originally defined. In netCDF-4/HDF5 files, attribute name, length,
* and value may be changed at any time.
*
* It is also possible to have attributes that are not associated with
* any variable. These are called global attributes and are identified
* by using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
* usually related to the netCDF dataset as a whole and may be used
* for purposes such as providing a title or processing history for a
* netCDF dataset. In netCDF-4/HDF5 files, global attributes are
* associated with a hierarchical group.
*
* Operations supported on attributes are:
* - Create an attribute, given its variable ID, name, data type,
* length, and value.
* length, and value.
* - Get attribute's data type and length from its variable ID and
name.
* - Get attribute's value from its variable ID and name.
@ -58,7 +41,6 @@
* - Get name of attribute from its number.
* - Rename an attribute.
* - Delete an attribute.
*
*/
/** @{*/
@ -67,7 +49,7 @@
* @name Deleting and Renaming Attributes
*
* Functions to delete or rename an attribute. */
/** @{ */
/**@{*/ /* Start doxygen member group. */
/**
* Rename an attribute.
@ -199,6 +181,6 @@ nc_del_att(int ncid, int varid, const char *name)
stat = ncp->dispatch->del_att(ncid, varid, name);
return stat;
}
/*! @} */
/**@}*/ /* End doxygen member group. */
/*! @} */
/**@}*/

53
libdispatch/dattget.c
View File

@ -10,22 +10,28 @@
#include "ncdispatch.h"
/**
* @anchor getting_attributes
* @name Getting Attributes
*
* Functions to get the values of attributes.
*
* The netCDF library reads all attributes into memory when the
* file is opened with nc_open(), or when the first attribute for that
* file or group (for global attributes) or variable is accessed by
* the user (after versuon 4.7.2). Getting an attribute copies the
* value from the in-memory store, and does not incur any file I/O
* penalties after the attributes have been read.
* For classic format files, the netCDF library reads all attributes
* into memory when the file is opened with nc_open().
*
* For netCDF-4/HDF5 files, since version 4.7.2, attributes are not
* read on file open. Instead, when the first read of a variable
* attribute is done, all attributes for that variable are
* read. Subsequent access to other attributes of that variable will
* not incur a disk read. Similarly, when the first NC_GLOBAL
* attribute is read in a group, all NC_GLOBAL attributes for that
* group will be read.
*
* @note All elements attribute data array are returned, so you must
* allocate enough space to hold them. If you don't know how much
* space to reserve, call nc_inq_attlen() first to find out the length
* of the attribute.
*/
/**@{*/ /* Start doxygen member group. */
/**
* @ingroup attributes
@ -36,6 +42,8 @@
* the type safe versions of this function be used for atomic data
* types.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -109,12 +117,14 @@ nc_get_att(int ncid, int varid, const char *name, void *value)
* This function gets a text attribute from the netCDF
* file. Type conversions are not permitted.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
* @param value Pointer that will get array of attribute value(s). Use
* nc_inq_attlen() to learn length.
*
* @note The handling of NULL terminators is not specified by
* netCDF. C programs can write attributes with or without NULL
* terminators. It is up to the reader to know whether NULL
@ -185,6 +195,8 @@ nc_get_att_text(int ncid, int varid, const char *name, char *value)
* @ingroup attributes
* Get an attribute of an signed char type.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -216,6 +228,8 @@ nc_get_att_schar(int ncid, int varid, const char *name, signed char *value)
* @ingroup attributes
* Get an attribute of an atomic type.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* This function gets an attribute of an atomic type from the netCDF
* file.
*
@ -281,6 +295,8 @@ nc_get_att_schar(int ncid, int varid, const char *name, signed char *value)
* @ingroup attributes
* Get an attribute of an signed char type.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -312,6 +328,8 @@ nc_get_att_uchar(int ncid, int varid, const char *name, unsigned char *value)
* @ingroup attributes
* Get an attribute array of type short.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -343,6 +361,8 @@ nc_get_att_short(int ncid, int varid, const char *name, short *value)
* @ingroup attributes
* Get an attribute array of type int.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -374,6 +394,8 @@ nc_get_att_int(int ncid, int varid, const char *name, int *value)
* @ingroup attributes
* Get an attribute array of type long.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -405,6 +427,8 @@ nc_get_att_long(int ncid, int varid, const char *name, long *value)
* @ingroup attributes
* Get an attribute array of type float.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -436,6 +460,8 @@ nc_get_att_float(int ncid, int varid, const char *name, float *value)
* @ingroup attributes
* Get an attribute array of type double.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -467,6 +493,8 @@ nc_get_att_double(int ncid, int varid, const char *name, double *value)
* @ingroup attributes
* Get an attribute array of type unsigned char.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -498,6 +526,8 @@ nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value)
* @ingroup attributes
* Get an attribute array of type unsigned short.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -529,6 +559,8 @@ nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value)
* @ingroup attributes
* Get an attribute array of type unsigned int.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -560,6 +592,8 @@ nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value)
* @ingroup attributes
* Get an attribute array of type long long.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -591,6 +625,8 @@ nc_get_att_longlong(int ncid, int varid, const char *name, long long *value)
* @ingroup attributes
* Get an attribute array of type unsigned long long.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute name.
@ -627,6 +663,8 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long *
* but this function will retrieve attributes which are of type
* variable-length string.
*
* Also see @ref getting_attributes "Getting Attributes"
*
* @note Note that unlike most other nc_get_att functions,
* nc_get_att_string() allocates a chunk of memory which is returned
* to the calling function. This chunk of memory must be specifically
@ -708,3 +746,4 @@ nc_get_att_string(int ncid, int varid, const char *name, char **value)
TRACE(nc_get_att_string);
return ncp->dispatch->get_att(ncid,varid,name,(void*)value, NC_STRING);
}
/**@}*/ /* End doxygen member group. */

46
libdispatch/dattput.c
View File

@ -9,10 +9,23 @@
#include "ncdispatch.h"
/**
* @anchor writing_attributes
* @name Writing Attributes
*
* Functions to write attributes.
*
* For netCDF classic formats, attributes are defined when the dataset
* is first created, while the netCDF dataset is in define
* mode. Additional attributes may be added later by reentering define
* mode. For netCDF-4/HDF5 netCDF files, attributes may be defined at
* any time.
*
* In classic format files, the data type, length, and value of an
* attribute may be changed even when in data mode, as long as the
* changed attribute requires no more space than the attribute as
* originally defined. In netCDF-4/HDF5 files, attribute name, length,
* and value may be changed at any time.
*
* Attribute data conversion automatically takes place when the type
* of the data does not match the xtype argument. All attribute data
* values are converted to xtype before being written to the file.
@ -31,6 +44,7 @@
*
*/
/**@{*/ /* Start doxygen member group. */
/**
* @ingroup attributes
* Write a string attribute.
@ -40,6 +54,8 @@
* only available in netCDF-4/HDF5 files, when ::NC_CLASSIC_MODEL has
* not been used in nc_create().
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -77,6 +93,8 @@ nc_put_att_string(int ncid, int varid, const char *name,
*
* Type conversion is not available with text attributes.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @note Whether or not this length includes the NULL character in C
* char arrays is a user decision. If the NULL character is not
* written, then all C programs must add the NULL character after
@ -146,6 +164,8 @@ int nc_put_att_text(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of any type.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -213,6 +233,8 @@ nc_put_att(int ncid, int varid, const char *name, nc_type xtype,
* @ingroup attributes
* Write an attribute of type signed char.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -245,6 +267,8 @@ nc_put_att_schar(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type unsigned char.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -277,6 +301,8 @@ nc_put_att_uchar(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type short.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -309,6 +335,8 @@ nc_put_att_short(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type int.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -341,6 +369,8 @@ nc_put_att_int(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type long.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -373,6 +403,8 @@ nc_put_att_long(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type float.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -405,6 +437,8 @@ nc_put_att_float(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type double.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -437,6 +471,8 @@ nc_put_att_double(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type unsigned char.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -469,6 +505,8 @@ nc_put_att_ubyte(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type unsigned short.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -501,6 +539,8 @@ nc_put_att_ushort(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type unsigned int.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -533,6 +573,8 @@ nc_put_att_uint(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type long long.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -566,6 +608,8 @@ nc_put_att_longlong(int ncid, int varid, const char *name,
* @ingroup attributes
* Write an attribute of type unsigned long long.
*
* Also see @ref writing_attributes "Writing Attributes"
*
* @param ncid NetCDF file or group ID.
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
* @param name Attribute @ref object_name.
@ -594,3 +638,5 @@ nc_put_att_ulonglong(int ncid, int varid, const char *name,
return ncp->dispatch->put_att(ncid, varid, name, xtype, len,
(void *)value, NC_UINT64);
}
/**@}*/ /* End doxygen member group. */