Debian Codegraph @

src/nco_c++/README

raw
1 $Header$
2
3 Purpose: Document libnco_c++
4
5 libnco_c++ is a C++ interface to the netCDF 3.x library.
6 It is in its own directory in the NCO repository on Sourceforge.
7 The software is completely independent of NCO, however, and only
8 requires the current netCDF C library to build.
9 libnco_c++ is mostly complete and it needs alpha testers,
10 comments, and contributions by developers (not end users yet).
11 I'm very interested in comments, critcisms, and contributions to
12 the basic design and API. You can download the latest version from
13 the NCO CVS repository on Sourceforge
14
15 cvs -d:pserver:[email protected]:/cvsroot/nco login
16 cvs -z3 -d:pserver:[email protected]:/cvsroot/nco co -kk nco
17
18 All code is in the nco/src/nco_c++ directory, including the
19 all important TODO and ChangeLog files. If you want to contribute
20 patches or comments the appropriate venue is the developer's forum
21
22 http://sf.net/forum/forum.php?forum_id=9831
23
24 Those with good patches to contribute will get CVS write access.
25 What follows is a description of the software design and status.
26 I hope you like it!
27
28 Charlie Zender
29
30 Short description:
31 libnco_c++ does NOT use an object-based approach, like libnetcdf_c++.a.
32 We use a pure overload-based approach.
33 The design emulates the Fortran90 interface with some C++-specific extensions.
34 Explicit reference to intrinsic types is determined by the library.
35 External types take advantage of the netCDF 3.X built-in conversion rules.
36
37 Status of the library:
38 More than half of libnetcdf.a functionality is implemented.
39 I have not overloaded the [get/put]_vara_ or [get/put]_varm_
40 or [get/put]_vars_ functions yet.
41 This is because my C++ applications do not yet require them.
42 There are no hooks yet for native short, char, and byte types.
43 Most other calls are implemented (for float, double, long and int).
44 The subset that is implemented is completely self-contained.
45 It is highly portable and has been used for two years on production code.
46 This code references only nco_ calls, no references to nc_ calls.
47 The only requirement to build the nco_c++ library is a C++ compiler
48 and libnetcdf.a version 3.X.
49 I am currently interested in receiving feedback and testing
50 on the library design.
51 There is a short TODO list appended below.
52
53 Design:
54 I faced many design choices, and my decision was to emphasize,
55 in no particular order,
56 (0) Easy Migration from C interface
57 (1) Error Handling
58 (2) Flexibility
59 (3) Maintainability.
60 (4) Taking advantage of C++ constructs
61 (5) Testing
62
63 (0) Easy Migration from C interface
64 All calls have identical names to netCDF 3.X calls with but
65 with prefix nco_ instead of nc_. Type names are deleted
66 so nc_put_var_float() becomes nco_put_var(). Order of arguments
67 is maintained where possible, with optional arguments (e.g.,
68 start and count vectors) moved to end of function parameter list, and
69 some new optional arguments (allowed non-fatal return codes).
70
71 (1) Error Handling
72 Let
73 rcd = Return code from netCDF 3.X layer
74 rcd_opt = Optional, user-specified non-fatal return code
75 By default, all rcd != NC_NOERR errors are fatal for all
76 functions. Inquire functions, and some others, however, allow
77 specification of allowed, non-fatal, return codes.
78 rcd=nco_enddef(nc_out,NC_ENOTINDEFINE)
79
80 (2) Flexibility
81 Functions that return information may be called with returned
82 values in parameter list, or values returned as function return
83 values. This allows returned information to be used to initialize
84 variables that are const, i.e.,
85
86 rcd=nco_inq_foo(nc_id,foo); -> or
87 foo=nco_inq_foo(nc_id); -> which allows this construct
88 const int foo(nco_inq_foo(nc_id));
89
90 (3) Maintainability
91 There is only one nco_foo() function which calls the corresponding
92 nc_foo() function. All other overloads of nco_foo() do preprocessing
93 of the argument list and then call the primary nco_foo() function.
94 The primary nco_foo() function is the one whose arguments look most
95 like the corresponding nc_foo() function. In practice this means
96 that nco_put_var(nc_id,var_nm,var_val) calls
97 nco_put_var(nc_id,var_id,var_val) which calls
98 nc_put_var_[float,long,etc]() as appropriate.
99 Thus there are as few interfaces to the underlying libnetcdf.a as
100 possible.
101
102 (4) Taking advantage of C++ constructs
103 (4)(i) Everything is passed by reference so that the calling routines
104 never need to pass pointers, and the function overhead is as limited
105 as possible. All input variable are declared const.
106 C++ strings are allowed anywhere an variable/dimension/attribute ID
107 would normally be required.
108 Thus variables can always be passed by name rather than ID.
109 This means the calling program never has to keep track of IDs
110 (except the file ID, which, in my opinion, should have its
111 own ID->name call implemented in the netCDF library).
112
113 (4)(ii) There is no standard way in C++, unlike Fortran, for an array
114 to know its rank and dimensionality. However, the C++ STL
115 provides valarrays and vectors which do know this information.
116 A valarray interface to a couple of the functions
117 demonstrate how this could be supported more generally.
118
119 (4)(iii) Functions are templated where possible.
120
121 (5) Testing
122 There is a short, standalone sample program, tst.cc, which tests some
123 of the libnco_c++. In particular, it demonstrates reading and writing.
124 tst.cc should eventually contain tests for the entire API.
125
126 Description of files:
127 Only files matching *nco_* are part of the libnco_c++ library, other
128 files can be safely ignored (but may contain sample code which utilizes
129 libnco_c++). The full API of the libnco_c++.a library are completely
130 self-contained in the libnco_c++.hh header:
131
132 #include <nco_att.hh> // C++ interface to netCDF attribute routines
133 #include <nco_dmn.hh> // C++ interface to netCDF dimension routines
134 #include <nco_fl.hh> // C++ interface to netCDF file-level routines
135 #include <nco_hgh.hh> // High-level NCO utilities
136 #include <nco_utl.hh> // C++ interface utilities for netCDF routines
137 #include <nco_var.hh> // C++ interface to netCDF variable routines
138
139 Each .hh file contains the prototypes defined in a corresponding
140 .cc file. The contents of all the individual files should be
141 apparent from their names with the exception of nco_hgh.
142 nco_hgh contains a program-specific high-level interface which should
143 not be part of a generic netCDF C++ interface library.
144 It can be safely ignored. The file tst.cc uses the libnco_c++.a API.
145 tst.cc shows how libnco_c++ is intended to be used in a real
146 environment.
147
148 Build libnco_c++ with the Makefile generated by configure.
149 If this fails, try using the handwritten Makefile.old---type
150 'make -f Makefile.old' using GNU make.
151 Makefile.old requires GNU make and Perl to be in your executable path.