/src/gdal/netcdf-c-4.7.4/libdispatch/datt.c

Source (jump to first uncovered line)
/*Copyright 2018 University Corporation for Atmospheric
  Research/Unidata. See copyright file for more info. */
/**
 * @file
 *
 * These functions in this file rename and delete attributes.
*/
#include "ncdispatch.h"

/**
 * @defgroup attributes Attributes
 *
 * Attributes hold metadata about data and files.
 *
 * @image html ncatts.png "Attributes store metadata."
 *
 * Attributes may be associated with a netCDF variable to specify such
 * properties as units, special values, maximum and minimum valid
 * values, scaling factors, and offsets.
 *
 * 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().
 *
 * Operations supported on attributes are:
 * - Create an attribute, given its variable ID, name, data type,
 *   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.
 * - Copy attribute from one netCDF variable to another.
 * - Get name of attribute from its number.
 * - Rename an attribute.
 * - Delete an attribute.
*/

/** @{*/

/**
 * @name Deleting and Renaming Attributes
 *
 * Functions to delete or rename an attribute. */
/**@{*/  /* Start doxygen member group. */

/**
 * Rename an attribute.
 *
 * The function nc_rename_att() changes the name of an attribute. In
 * classic formats, if the new name is longer than the original name,
 * the netCDF dataset must be in define mode. In netCDF-4/HDF5 files,
 * attributes may be renamed at any time. You cannot rename an
 * attribute to have the same name as another attribute of the same
 * variable.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global attribute.
 * @param name Attribute \ref object_name.
 * @param newname The new attribute \ref object_name.
 *
 * <h1>Example</h1>
 *
 * Here is an example using nc_rename_att() to rename the variable
 * attribute units to Units for a variable rh in an existing netCDF
 * dataset named foo.nc:
 *
 @code
     #include <netcdf.h>
        ...
     int  status;
     int  ncid;
     int  rh_id;
        ...
     status = nc_open("foo.nc", NC_NOWRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_rename_att(ncid, rh_id, "units", "Units");
     if (status != NC_NOERR) handle_error(status);
 @endcode

 * @return ::NC_NOERR No error.
 * @return ::NC_EBADID Bad ncid.
 * @return ::NC_ENOTVAR Bad varid.
 * @return ::NC_EBADNAME Bad name.
 * @return ::NC_EMAXNAME New name too long.
 * @return ::NC_EINVAL Name or new name not provided.
 * @return ::NC_ENAMEINUSE Name already in use.
 * @return ::NC_EPERM File was opened read only.
 * @return ::NC_ENOTINDEFINE File is not in define mode.
 * @return ::NC_ENOTATT Attribute not found.
 * @return ::NC_EHDFERR Failure at HDF5 layer.
 * @return ::NC_ENOMEM Out of memory.
 *
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
 */
int
nc_rename_att(int ncid, int varid, const char *name, const char *newname)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   TRACE(nc_rename_att);
   return ncp->dispatch->rename_att(ncid, varid, name, newname);
}

/**
 * Delete an attribute.
 *
 * The function nc_del_att() deletes a netCDF attribute from an open
 * netCDF dataset. For classic netCDF formats, the dataset must be in
 * define mode to delete an attribute. In netCDF-4/HDF5 files,
 * attributes may be deleted at any time.
 *
 * @param ncid NetCDF or group ID, from a previous call to nc_open(),
 * nc_create(), nc_def_grp(), or associated inquiry functions such as
 * nc_inq_ncid().
 * @param varid Variable ID of the attribute's variable, or
 * ::NC_GLOBAL for a global attribute.
 * @param name Attribute name.
 *
 * <h1>Example</h1>
 *
 * Here is an example using nc_del_att() to delete the variable
 * attribute Units for a variable rh in an existing netCDF dataset
 * named foo.nc:

@code
     #include <netcdf.h>
        ...
     int  status;
     int  ncid;
     int  rh_id;
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid (ncid, "rh", &rh_id);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_redef(ncid);
     if (status != NC_NOERR) handle_error(status);
     status = nc_del_att(ncid, rh_id, "Units");
     if (status != NC_NOERR) handle_error(status);
     status = nc_enddef(ncid);
     if (status != NC_NOERR) handle_error(status);
@endcode

 * @return ::NC_NOERR No error.
 * @return ::NC_EBADID Bad ncid.
 * @return ::NC_ENOTVAR Bad varid.
 * @return ::NC_EBADNAME Bad name.
 * @return ::NC_EINVAL Name not provided.
 * @return ::NC_EPERM File was opened read only.
 * @return ::NC_ENOTINDEFINE File is not in define mode.
 * @return ::NC_ENOTATT Attribute not found.
 * @return ::NC_EATTMETA Failure at HDF5 layer.
 *
 * @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
 */
int
nc_del_att(int ncid, int varid, const char *name)
{
   NC* ncp;
   int stat = NC_check_id(ncid, &ncp);
   if(stat != NC_NOERR) return stat;
   TRACE(nc_del_att);
   stat = ncp->dispatch->del_att(ncid, varid, name);
   return stat;
}
/**@}*/  /* End doxygen member group. */

/**@}*/

Line	Count	Source (jump to first uncovered line)
1		/*Copyright 2018 University Corporation for Atmospheric
2		Research/Unidata. See copyright file for more info. */
3		/**
4		* @file
5		*
6		* These functions in this file rename and delete attributes.
7		*/
8		#include "ncdispatch.h"
9
10		/**
11		* @defgroup attributes Attributes
12		*
13		* Attributes hold metadata about data and files.
14		*
15		* @image html ncatts.png "Attributes store metadata."
16		*
17		* Attributes may be associated with a netCDF variable to specify such
18		* properties as units, special values, maximum and minimum valid
19		* values, scaling factors, and offsets.
20		*
21		* It is also possible to have attributes that are not associated with
22		* any variable. These are called global attributes and are identified
23		* by using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
24		* related to the netCDF dataset as a whole and may be used for
25		* purposes such as providing a title or processing history for a
26		* netCDF dataset. In netCDF-4/HDF5 files, global attributes are
27		* associated with a hierarchical group.
28		*
29		* An attribute is designated by its variable ID and name. When an
30		* attribute name is not known, it may be designated by its variable
31		* ID and number in order to determine its name, using the function
32		* nc_inq_attname().
33		*
34		* Operations supported on attributes are:
35		* - Create an attribute, given its variable ID, name, data type,
36		* length, and value.
37		* - Get attribute's data type and length from its variable ID and
38		name.
39		* - Get attribute's value from its variable ID and name.
40		* - Copy attribute from one netCDF variable to another.
41		* - Get name of attribute from its number.
42		* - Rename an attribute.
43		* - Delete an attribute.
44		*/
45
46		/** @{*/
47
48		/**
49		* @name Deleting and Renaming Attributes
50		*
51		* Functions to delete or rename an attribute. */
52		/*@{/ /* Start doxygen member group. */
53
54		/**
55		* Rename an attribute.
56		*
57		* The function nc_rename_att() changes the name of an attribute. In
58		* classic formats, if the new name is longer than the original name,
59		* the netCDF dataset must be in define mode. In netCDF-4/HDF5 files,
60		* attributes may be renamed at any time. You cannot rename an
61		* attribute to have the same name as another attribute of the same
62		* variable.
63		*
64		* @param ncid NetCDF or group ID, from a previous call to nc_open(),
65		* nc_create(), nc_def_grp(), or associated inquiry functions such as
66		* nc_inq_ncid().
67		* @param varid Variable ID of the attribute's variable, or
68		* ::NC_GLOBAL for a global attribute.
69		* @param name Attribute \ref object_name.
70		* @param newname The new attribute \ref object_name.
71		*
72		* <h1>Example</h1>
73		*
74		* Here is an example using nc_rename_att() to rename the variable
75		* attribute units to Units for a variable rh in an existing netCDF
76		* dataset named foo.nc:
77		*
78		@code
79		#include <netcdf.h>
80		...
81		int status;
82		int ncid;
83		int rh_id;
84		...
85		status = nc_open("foo.nc", NC_NOWRITE, &ncid);
86		if (status != NC_NOERR) handle_error(status);
87		...
88		status = nc_inq_varid (ncid, "rh", &rh_id);
89		if (status != NC_NOERR) handle_error(status);
90		...
91		status = nc_rename_att(ncid, rh_id, "units", "Units");
92		if (status != NC_NOERR) handle_error(status);
93		@endcode
94
95		* @return ::NC_NOERR No error.
96		* @return ::NC_EBADID Bad ncid.
97		* @return ::NC_ENOTVAR Bad varid.
98		* @return ::NC_EBADNAME Bad name.
99		* @return ::NC_EMAXNAME New name too long.
100		* @return ::NC_EINVAL Name or new name not provided.
101		* @return ::NC_ENAMEINUSE Name already in use.
102		* @return ::NC_EPERM File was opened read only.
103		* @return ::NC_ENOTINDEFINE File is not in define mode.
104		* @return ::NC_ENOTATT Attribute not found.
105		* @return ::NC_EHDFERR Failure at HDF5 layer.
106		* @return ::NC_ENOMEM Out of memory.
107		*
108		* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
109		*/
110		int
111		nc_rename_att(int ncid, int varid, const char name, const char newname)
112	0	{
113	0	NC* ncp;
114	0	int stat = NC_check_id(ncid, &ncp);
115	0	if(stat != NC_NOERR) return stat;
116	0	TRACE(nc_rename_att);
117	0	return ncp->dispatch->rename_att(ncid, varid, name, newname);
118	0	}
119
120		/**
121		* Delete an attribute.
122		*
123		* The function nc_del_att() deletes a netCDF attribute from an open
124		* netCDF dataset. For classic netCDF formats, the dataset must be in
125		* define mode to delete an attribute. In netCDF-4/HDF5 files,
126		* attributes may be deleted at any time.
127		*
128		* @param ncid NetCDF or group ID, from a previous call to nc_open(),
129		* nc_create(), nc_def_grp(), or associated inquiry functions such as
130		* nc_inq_ncid().
131		* @param varid Variable ID of the attribute's variable, or
132		* ::NC_GLOBAL for a global attribute.
133		* @param name Attribute name.
134		*
135		* <h1>Example</h1>
136		*
137		* Here is an example using nc_del_att() to delete the variable
138		* attribute Units for a variable rh in an existing netCDF dataset
139		* named foo.nc:
140
141		@code
142		#include <netcdf.h>
143		...
144		int status;
145		int ncid;
146		int rh_id;
147		...
148		status = nc_open("foo.nc", NC_WRITE, &ncid);
149		if (status != NC_NOERR) handle_error(status);
150		...
151		status = nc_inq_varid (ncid, "rh", &rh_id);
152		if (status != NC_NOERR) handle_error(status);
153		...
154		status = nc_redef(ncid);
155		if (status != NC_NOERR) handle_error(status);
156		status = nc_del_att(ncid, rh_id, "Units");
157		if (status != NC_NOERR) handle_error(status);
158		status = nc_enddef(ncid);
159		if (status != NC_NOERR) handle_error(status);
160		@endcode
161
162		* @return ::NC_NOERR No error.
163		* @return ::NC_EBADID Bad ncid.
164		* @return ::NC_ENOTVAR Bad varid.
165		* @return ::NC_EBADNAME Bad name.
166		* @return ::NC_EINVAL Name not provided.
167		* @return ::NC_EPERM File was opened read only.
168		* @return ::NC_ENOTINDEFINE File is not in define mode.
169		* @return ::NC_ENOTATT Attribute not found.
170		* @return ::NC_EATTMETA Failure at HDF5 layer.
171		*
172		* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
173		*/
174		int
175		nc_del_att(int ncid, int varid, const char *name)
176	0	{
177	0	NC* ncp;
178	0	int stat = NC_check_id(ncid, &ncp);
179	0	if(stat != NC_NOERR) return stat;
180	0	TRACE(nc_del_att);
181	0	stat = ncp->dispatch->del_att(ncid, varid, name);
182	0	return stat;
183	0	}
184		/*@}/ /* End doxygen member group. */
185
186		/*@}/

Coverage Report

Created: 2025-06-09 07:42