/[escript]/trunk/escript/src/netcdfcpp.h
ViewVC logotype

Contents of /trunk/escript/src/netcdfcpp.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1130 - (show annotations)
Tue May 8 04:23:51 2007 UTC (13 years, 6 months ago) by gross
File MIME type: text/plain
File size: 18916 byte(s)


1 /*********************************************************************
2 * Copyright 1992, University Corporation for Atmospheric Research
3 * See netcdf/README file for copying and redistribution conditions.
4 *
5 * Purpose: C++ class interface for netCDF
6 *
7 * $Header: /upc/share/CVS/netcdf-3/cxx/netcdfcpp.h,v 1.14 2006/07/31 20:42:48 russ Exp $
8 *********************************************************************/
9
10 #ifndef NETCDF_HH
11 #define NETCDF_HH
12
13 #include "ncvalues.h" // arrays that know their element type
14
15 typedef const char* NcToken; // names for netCDF objects
16 typedef unsigned int NcBool; // many members return 0 on failure
17
18 class NcDim; // dimensions
19 class NcVar; // variables
20 class NcAtt; // attributes
21
22 /*
23 * ***********************************************************************
24 * A netCDF file.
25 * ***********************************************************************
26 */
27 class NcFile
28 {
29 public:
30
31 virtual ~NcFile( void );
32
33 enum FileMode {
34 ReadOnly, // file exists, open read-only
35 Write, // file exists, open for writing
36 Replace, // create new file, even if already exists
37 New // create new file, fail if already exists
38 };
39
40 enum FileFormat {
41 Classic, // netCDF classic format (i.e. version 1 format)
42 Offset64Bits, // netCDF 64-bit offset format
43 Netcdf4, // netCDF-4 using HDF5 format
44 Netcdf4Classic, // netCDF-4 using HDF5 format using only netCDF-3 calls
45 BadFormat
46 };
47
48 NcFile( const char * path, FileMode = ReadOnly ,
49 size_t *chunksizeptr = NULL, // optional tuning parameters
50 size_t initialsize = 0,
51 FileFormat = Classic );
52
53 NcBool is_valid( void ) const; // opened OK in ctr, still valid
54
55 int num_dims( void ) const; // number of dimensions
56 int num_vars( void ) const; // number of variables
57 int num_atts( void ) const; // number of (global) attributes
58
59 NcDim* get_dim( NcToken ) const; // dimension by name
60 NcVar* get_var( NcToken ) const; // variable by name
61 NcAtt* get_att( NcToken ) const; // global attribute by name
62
63 NcDim* get_dim( int ) const; // n-th dimension
64 NcVar* get_var( int ) const; // n-th variable
65 NcAtt* get_att( int ) const; // n-th global attribute
66 NcDim* rec_dim( void ) const; // unlimited dimension, if any
67
68 // Add new dimensions, variables, global attributes.
69 // These put the file in "define" mode, so could be expensive.
70 virtual NcDim* add_dim( NcToken dimname, long dimsize );
71 virtual NcDim* add_dim( NcToken dimname ); // unlimited
72
73 virtual NcVar* add_var( NcToken varname, NcType type, // scalar
74 const NcDim* dim0=0, // 1-dim
75 const NcDim* dim1=0, // 2-dim
76 const NcDim* dim2=0, // 3-dim
77 const NcDim* dim3=0, // 4-dim
78 const NcDim* dim4=0 ); // 5-dim
79 virtual NcVar* add_var( NcToken varname, NcType type, // n-dim
80 int ndims, const NcDim** dims );
81
82 NcBool add_att( NcToken attname, char ); // scalar attributes
83 NcBool add_att( NcToken attname, ncbyte );
84 NcBool add_att( NcToken attname, short );
85 NcBool add_att( NcToken attname, long );
86 NcBool add_att( NcToken attname, int );
87 NcBool add_att( NcToken attname, float );
88 NcBool add_att( NcToken attname, double );
89 NcBool add_att( NcToken attname, const char*); // string attribute
90 NcBool add_att( NcToken attname, int, const char* ); // vector attributes
91 NcBool add_att( NcToken attname, int, const ncbyte* );
92 NcBool add_att( NcToken attname, int, const short* );
93 NcBool add_att( NcToken attname, int, const long* );
94 NcBool add_att( NcToken attname, int, const int* );
95 NcBool add_att( NcToken attname, int, const float* );
96 NcBool add_att( NcToken attname, int, const double* );
97
98 enum FillMode {
99 Fill = NC_FILL, // prefill (default)
100 NoFill = NC_NOFILL, // don't prefill
101 Bad
102 };
103
104 NcBool set_fill( FillMode = Fill ); // set fill-mode
105 FillMode get_fill( void ) const; // get fill-mode
106 FileFormat get_format( void ) const; // get format version
107
108 NcBool sync( void ); // synchronize to disk
109 NcBool close( void ); // to close earlier than dtr
110 NcBool abort( void ); // back out of bad defines
111
112 // Needed by other Nc classes, but users will not need them
113 NcBool define_mode( void ); // leaves in define mode, if possible
114 NcBool data_mode( void ); // leaves in data mode, if possible
115 int id( void ) const; // id used by C interface
116
117 protected:
118 int the_id;
119 int in_define_mode;
120 FillMode the_fill_mode;
121 NcDim** dimensions;
122 NcVar** variables;
123 NcVar* globalv; // "variable" for global attributes
124 };
125
126 /*
127 * For backward compatibility. We used to derive NcOldFile and NcNewFile
128 * from NcFile, but that was over-zealous inheritance.
129 */
130 #define NcOldFile NcFile
131 #define NcNewFile NcFile
132 #define Clobber Replace
133 #define NoClobber New
134
135 /*
136 * **********************************************************************
137 * A netCDF dimension, with a name and a size. These are only created
138 * by NcFile member functions, because they cannot exist independently
139 * of an open netCDF file.
140 * **********************************************************************
141 */
142 class NcDim
143 {
144 public:
145 NcToken name( void ) const;
146 long size( void ) const;
147 NcBool is_valid( void ) const;
148 NcBool is_unlimited( void ) const;
149 NcBool rename( NcToken newname );
150 int id( void ) const;
151 NcBool sync( void );
152
153 private:
154 NcFile *the_file; // not const because of rename
155 int the_id;
156 char *the_name;
157
158 NcDim(NcFile*, int num); // existing dimension
159 NcDim(NcFile*, NcToken name, long sz); // defines a new dim
160 virtual ~NcDim( void );
161
162 // to construct dimensions, since constructor is private
163 friend class NcFile;
164 };
165
166
167 /*
168 * **********************************************************************
169 * Abstract base class for a netCDF variable or attribute, both of which
170 * have a name, a type, and associated values. These only exist as
171 * components of an open netCDF file.
172 * **********************************************************************
173 */
174 class NcTypedComponent
175 {
176 public:
177 virtual ~NcTypedComponent( void ) {}
178 virtual NcToken name( void ) const = 0;
179 virtual NcType type( void ) const = 0;
180 virtual NcBool is_valid( void ) const = 0;
181 virtual long num_vals( void ) const = 0;
182 virtual NcBool rename( NcToken newname ) = 0;
183 virtual NcValues* values( void ) const = 0; // block of all values
184
185 // The following member functions provide conversions from the value
186 // type to a desired basic type. If the value is out of range,
187 // the default "fill-value" for the appropriate type is returned.
188
189 virtual ncbyte as_ncbyte( long n ) const; // nth value as an unsgnd char
190 virtual char as_char( long n ) const; // nth value as char
191 virtual short as_short( long n ) const; // nth value as short
192 virtual int as_int( long n ) const; // nth value as int
193 virtual int as_nclong( long n ) const; // nth value as nclong (deprecated)
194 virtual long as_long( long n ) const; // nth value as long
195 virtual float as_float( long n ) const; // nth value as floating-point
196 virtual double as_double( long n ) const; // nth value as double
197 virtual char* as_string( long n ) const; // nth value as string
198
199 protected:
200 NcFile *the_file;
201 NcTypedComponent( NcFile* );
202 virtual NcValues* get_space( long numVals = 0 ) const; // to hold values
203 };
204
205
206 /*
207 * **********************************************************************
208 * netCDF variables. In addition to a name and a type, these also have
209 * a shape, given by a list of dimensions
210 * **********************************************************************
211 */
212 class NcVar : public NcTypedComponent
213 {
214 public:
215 virtual ~NcVar( void );
216 NcToken name( void ) const;
217 NcType type( void ) const;
218 NcBool is_valid( void ) const;
219 int num_dims( void ) const; // dimensionality of variable
220 NcDim* get_dim( int ) const; // n-th dimension
221 long* edges( void ) const; // dimension sizes
222 int num_atts( void ) const; // number of attributes
223 NcAtt* get_att( NcToken ) const; // attribute by name
224 NcAtt* get_att( int ) const; // n-th attribute
225 long num_vals( void ) const; // product of dimension sizes
226 NcValues* values( void ) const; // all values
227
228 // Put scalar or 1, ..., 5 dimensional arrays by providing enough
229 // arguments. Arguments are edge lengths, and their number must not
230 // exceed variable's dimensionality. Start corner is [0,0,..., 0] by
231 // default, but may be reset using the set_cur() member. FALSE is
232 // returned if type of values does not match type for variable.
233 NcBool put( const ncbyte* vals,
234 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
235 NcBool put( const char* vals,
236 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
237 NcBool put( const short* vals,
238 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
239 NcBool put( const int* vals,
240 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
241 NcBool put( const long* vals,
242 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
243 NcBool put( const float* vals,
244 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
245 NcBool put( const double* vals,
246 long c0=0, long c1=0, long c2=0, long c3=0, long c4=0 );
247
248 // Put n-dimensional arrays, starting at [0, 0, ..., 0] by default,
249 // may be reset with set_cur().
250 NcBool put( const ncbyte* vals, const long* counts );
251 NcBool put( const char* vals, const long* counts );
252 NcBool put( const short* vals, const long* counts );
253 NcBool put( const int* vals, const long* counts );
254 NcBool put( const long* vals, const long* counts );
255 NcBool put( const float* vals, const long* counts );
256 NcBool put( const double* vals, const long* counts );
257
258 // Get scalar or 1, ..., 5 dimensional arrays by providing enough
259 // arguments. Arguments are edge lengths, and their number must not
260 // exceed variable's dimensionality. Start corner is [0,0,..., 0] by
261 // default, but may be reset using the set_cur() member.
262 NcBool get( ncbyte* vals, long c0=0, long c1=0,
263 long c2=0, long c3=0, long c4=0 ) const;
264 NcBool get( char* vals, long c0=0, long c1=0,
265 long c2=0, long c3=0, long c4=0 ) const;
266 NcBool get( short* vals, long c0=0, long c1=0,
267 long c2=0, long c3=0, long c4=0 ) const;
268 NcBool get( int* vals, long c0=0, long c1=0,
269 long c2=0, long c3=0, long c4=0 ) const;
270 NcBool get( long* vals, long c0=0, long c1=0,
271 long c2=0, long c3=0, long c4=0 ) const;
272 NcBool get( float* vals, long c0=0, long c1=0,
273 long c2=0, long c3=0, long c4=0 ) const;
274 NcBool get( double* vals, long c0=0, long c1=0,
275 long c2=0, long c3=0, long c4=0 ) const;
276
277 // Get n-dimensional arrays, starting at [0, 0, ..., 0] by default,
278 // may be reset with set_cur().
279 NcBool get( ncbyte* vals, const long* counts ) const;
280 NcBool get( char* vals, const long* counts ) const;
281 NcBool get( short* vals, const long* counts ) const;
282 NcBool get( int* vals, const long* counts ) const;
283 NcBool get( long* vals, const long* counts ) const;
284 NcBool get( float* vals, const long* counts ) const;
285 NcBool get( double* vals, const long* counts ) const;
286
287 NcBool set_cur(long c0=-1, long c1=-1, long c2=-1,
288 long c3=-1, long c4=-1);
289 NcBool set_cur(long* cur);
290
291 // these put file in define mode, so could be expensive
292 NcBool add_att( NcToken, char ); // add scalar attributes
293 NcBool add_att( NcToken, ncbyte );
294 NcBool add_att( NcToken, short );
295 NcBool add_att( NcToken, int );
296 NcBool add_att( NcToken, long );
297 NcBool add_att( NcToken, float );
298 NcBool add_att( NcToken, double );
299 NcBool add_att( NcToken, const char* ); // string attribute
300 NcBool add_att( NcToken, int, const char* ); // vector attributes
301 NcBool add_att( NcToken, int, const ncbyte* );
302 NcBool add_att( NcToken, int, const short* );
303 NcBool add_att( NcToken, int, const int* );
304 NcBool add_att( NcToken, int, const long* );
305 NcBool add_att( NcToken, int, const float* );
306 NcBool add_att( NcToken, int, const double* );
307
308 NcBool rename( NcToken newname );
309
310 long rec_size ( void ); // number of values per record
311 long rec_size ( NcDim* ); // number of values per dimension slice
312
313 // Though following are intended for record variables, they also work
314 // for other variables, using first dimension as record dimension.
315
316 // Get a record's worth of data
317 NcValues *get_rec(void); // get current record
318 NcValues *get_rec(long rec); // get specified record
319 NcValues *get_rec(NcDim* d); // get current dimension slice
320 NcValues *get_rec(NcDim* d, long slice); // get specified dimension slice
321
322 // Put a record's worth of data in current record
323 NcBool put_rec( const ncbyte* vals );
324 NcBool put_rec( const char* vals );
325 NcBool put_rec( const short* vals );
326 NcBool put_rec( const int* vals );
327 NcBool put_rec( const long* vals );
328 NcBool put_rec( const float* vals );
329 NcBool put_rec( const double* vals );
330
331 // Put a dimension slice worth of data in current dimension slice
332 NcBool put_rec( NcDim* d, const ncbyte* vals );
333 NcBool put_rec( NcDim* d, const char* vals );
334 NcBool put_rec( NcDim* d, const short* vals );
335 NcBool put_rec( NcDim* d, const int* vals );
336 NcBool put_rec( NcDim* d, const long* vals );
337 NcBool put_rec( NcDim* d, const float* vals );
338 NcBool put_rec( NcDim* d, const double* vals );
339
340 // Put a record's worth of data in specified record
341 NcBool put_rec( const ncbyte* vals, long rec );
342 NcBool put_rec( const char* vals, long rec );
343 NcBool put_rec( const short* vals, long rec );
344 NcBool put_rec( const int* vals, long rec );
345 NcBool put_rec( const long* vals, long rec );
346 NcBool put_rec( const float* vals, long rec );
347 NcBool put_rec( const double* vals, long rec );
348
349 // Put a dimension slice worth of data in specified dimension slice
350 NcBool put_rec( NcDim* d, const ncbyte* vals, long slice );
351 NcBool put_rec( NcDim* d, const char* vals, long slice );
352 NcBool put_rec( NcDim* d, const short* vals, long slice );
353 NcBool put_rec( NcDim* d, const int* vals, long slice );
354 NcBool put_rec( NcDim* d, const long* vals, long slice );
355 NcBool put_rec( NcDim* d, const float* vals, long slice );
356 NcBool put_rec( NcDim* d, const double* vals, long slice );
357
358 // Get first record index corresponding to specified key value(s)
359 long get_index( const ncbyte* vals );
360 long get_index( const char* vals );
361 long get_index( const short* vals );
362 long get_index( const int* vals );
363 long get_index( const long* vals );
364 long get_index( const float* vals );
365 long get_index( const double* vals );
366
367 // Get first index of specified dimension corresponding to key values
368 long get_index( NcDim* d, const ncbyte* vals );
369 long get_index( NcDim* d, const char* vals );
370 long get_index( NcDim* d, const short* vals );
371 long get_index( NcDim* d, const int* vals );
372 long get_index( NcDim* d, const long* vals );
373 long get_index( NcDim* d, const float* vals );
374 long get_index( NcDim* d, const double* vals );
375
376 // Set current record
377 void set_rec ( long rec );
378 // Set current dimension slice
379 void set_rec ( NcDim* d, long slice );
380
381 int id( void ) const; // rarely needed, C interface id
382 NcBool sync( void );
383
384 private:
385 int dim_to_index(NcDim* rdim);
386 int the_id;
387 long* the_cur;
388 char* the_name;
389 long* cur_rec;
390
391 // private constructors because only an NcFile creates these
392 NcVar( void );
393 NcVar(NcFile*, int);
394
395 int attnum( NcToken attname ) const;
396 NcToken attname( int attnum ) const;
397 void init_cur( void );
398
399 // to make variables, since constructor is private
400 friend class NcFile;
401 };
402
403
404 /*
405 * **********************************************************************
406 * netCDF attributes. In addition to a name and a type, these are each
407 * associated with a specific variable, or are global to the file.
408 * **********************************************************************
409 */
410 class NcAtt : public NcTypedComponent
411 {
412 public:
413 virtual ~NcAtt( void );
414 NcToken name( void ) const;
415 NcType type( void ) const;
416 NcBool is_valid( void ) const;
417 long num_vals( void ) const;
418 NcValues* values( void ) const;
419 NcBool rename( NcToken newname );
420 NcBool remove( void );
421
422 private:
423 const NcVar* the_variable;
424 char* the_name;
425 // protected constructors because only NcVars and NcFiles create
426 // attributes
427 NcAtt( NcFile*, const NcVar*, NcToken);
428 NcAtt( NcFile*, NcToken); // global attribute
429
430 // To make attributes, since constructor is private
431 friend class NcFile;
432 friend NcAtt* NcVar::get_att( NcToken ) const;
433 };
434
435
436 /*
437 * **********************************************************************
438 * To control error handling. Declaring an NcError object temporarily
439 * changes the error-handling behavior until the object is destroyed, at
440 * which time the previous error-handling behavior is restored.
441 * **********************************************************************
442 */
443 class NcError {
444 public:
445 enum Behavior {
446 silent_nonfatal = 0,
447 silent_fatal = 1,
448 verbose_nonfatal = 2,
449 verbose_fatal = 3
450 };
451
452 // constructor saves previous error state, sets new state
453 NcError( Behavior b = verbose_fatal );
454
455 // destructor restores previous error state
456 virtual ~NcError( void );
457
458 int get_err( void ); // returns most recent error number
459 const char* get_errmsg( void ) {return nc_strerror(get_err());}
460 static int set_err( int err );
461
462 private:
463 int the_old_state;
464 int the_old_err;
465 static int ncopts;
466 static int ncerr;
467 };
468
469 #endif /* NETCDF_HH */

  ViewVC Help
Powered by ViewVC 1.1.26