ruby-netcdf 0.6.5

data/doc/Ref_man.rd

@@ -0,0 +1,1312 @@
+=begin
+=RubyNetCDF Reference Manual
+
+* ((<Method Index>))
+
+---------------------------------------------
+
+==Overview
+
+RubyNetCDF is the Ruby interface of the NetCDF library. Ruby is a free 
+object-oriented scripting language and is freely available from
+((<the Ruby homepage|URL:http://www.ruby-lang.org/>)). 
+To handle numeric data, RubyNetCDF uses
+((<NArray|URL:http://www.ruby-lang.org/en/raa-list.rhtml?name=NArray>)), which is the standard numeric multi-dimensional array class
+for Ruby. Thus, you have to have installed it before installing this library.
+An NArray object holds numeric data in a consecutive memory area
+pointed by a C pointer. Thus, it is computationally efficient.
+NArray is similar to NumPy for Python, but results of some benchmark
+tests suggests that NArray is more efficient than NumPy.
+Optionally, RubyNetCDF offers methods to handle data missing 
+automatically. To use it, you will also
+need ((<NArrayMiss|URL:http://ruby.gfd-dennou.org/products/narray_miss/>)). 
+See ((<Usage>)) for details.
+
+===Structure
+
+RubyNetCDF consists of the four classes in the following.
+
+* ((<class NetCDF>)) -- the file class
+
+  An NetCDF object represents a NetCDF file
+
+* ((<class NetCDFDim>)) -- the dimension class
+
+  Although in its C version a NetCDF dimension is represented by a
+  combination of a file ID and a dimension ID, it is represented by
+  only one NetCDFDim object in RubyNetCDF.
+
+* ((<class NetCDFVar>)) -- the variable class
+
+  Although in its C version a NetCDF variable is represented by a
+  combination of a file ID and a variable ID, it is represented by
+  only one NetCDFVar object in RubyNetCDF.
+
+* ((<class NetCDFAtt>)) -- the attribute class
+
+  Although in its C version a NetCDF attribute is represented by a
+  combination of file ID, variable ID, and its name, it is represented
+  by only one NetCDFAtt object in RubyNetCDF.
+
+===Data type
+
+All the NetCDF variable types char, byte, short, int, float, and
+double are supported in this Ruby interface. These types are called,
+however, differently in it to adhere to the convention of Ruby, or,
+more specifically, of NArray. These types are named to as "char",
+"byte", "sint", "int", "sfloat", and "float", respectively. Therefore,
+the vartype (=ntype) method of the NetCDFVar class returns one of these
+strings.  The def_var method of the NetCDF class also accepts one of
+them to define a variable.  It should be noted especially that "float"
+in this library means the double in the NetCDF terminology. This is
+due to the convention of Ruby -- the predefined Float class
+corresponds to the double in C, not the float.
+
+The "get" method of NetCDFVar class reads a variable in a NArray of
+the same type as in the file, except for the "char" type which is read
+into a "byte".  This is because NArray does not have a "char" type.
+However, it not is not supposed to be a problem, since a byte NArray
+can easily handle string data.
+
+
+===Error handling
+
+Errors are basically handled by raising exceptions. However, light
+errors in value-returning methods are handled by returning nil (e.g.,
+if a non-existent attribute name is specified in attribute reading).
+Those methods that return nil on error are explicitly written as such 
+in the following.
+
+===Security features
+
+Security handling is done just as in the pre-defined File class.
+
+===Usage
+
+To use the RubyNetCDF library, load the library first by placing the
+following line in your Ruby program to load the library:
+
+   require 'numru/netcdf'
+
+If you want to use automatic data-missing-handling methods
+(of NetCDFVar class), use the following:
+
+   require 'numru/netcdf_miss'
+
+This will call (({require 'numru/netcdf'})) inside at the beginning, so 
+you do not have to call the both. The missing-data handling is done 
+with ((<NArrayMiss|URL:http://ruby.gfd-dennou.org/products/narray_miss/>)),
+so you have have installed it. This is, however, not needed if you only
+call (({require 'numru/netcdf'})).
+
+Here, 'numru', which stands for "Numerical Ruby", is the name of
+the subdirectory in the user's load path where the RubyNetCDF library
+is placed. Then, it can be used as in the following:
+
+   file = NumRu::NetCDF.create('tmp.nc')
+   x = file.def_dim('x',10)
+   y = file.def_dim('y',10)
+   v = file.def_var('v','float',[x,y])
+   file.close
+
+Here, NumRu is the module that has the library in it. The
+reason why NetCDF library is wrapped in such a module is to avoid
+conflicts in the name space. Without this kind of treatment,
+problems happen if the user wants to use a library that happens to
+have a class or module with the same name as even one of the classes
+in this library.
+
+If such a problem is not expected to happen, the prefix "NumRu::" can
+be eliminated by "including" the NumRu module as in the following, so
+that to place "NumRu::" is not needed anymore in the current scope:
+
+   include NumRu
+   file = NetCDF.create('tmp.nc')
+   ...
+
+For more examples, see demo and test programs included in the
+distribution package.
+
+---------------------------------------------
+
+==How to read this manual
+
+--- method_name(argument1, argument2, ...) -- arguments that can be omitted are expressed as Argument_name=Default_value
+
+     Explanation of its function
+
+     Arguments
+     * name of argument1 (its class or possible values): explanation
+     * name of argument2 (its class or possible values): explanation
+     * ...
+
+     Return value
+     * Explanation of the return value
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * Name(s) in NetCDF ver 3. The function equivalent to the current
+       method, if not in parenthesis. If no direct correspondence,
+       dependent functions are listed in parentheses.
+
+---------------------------------------------
+
+==Method Index
+* ((<class NetCDF>))
+
+  Class Methods
+    * ((<NetCDF.open>))     Opens a file (class method). If mode="w" and non-existent, a new
+    * ((<NetCDF.new>))     Aliased to NetCDF.open
+    * ((<NetCDF.create>))     Creates a NetCDF file (class method)
+    * ((<NetCDF.create_tmp>))     Creates a temporary NetCDF file (class method)
+
+  Instance Methods
+    * ((<close>))     Closes the file.
+    * ((<ndims>))     Returns the number of dimensions in the file
+    * ((<nvars>))     Returns the number of variables in the file
+    * ((<natts>))     Returns the number of global attributes in the file
+    * ((<unlimited>))     Returns the unlimited dimension in the file
+    * ((<path>))     Returns the path of the file (contents of the filename specified when opened/created)
+    * ((<redef>))     Switches to the define mode. Does nothing if already in it (nil returned).
+    * ((<enddef>))     Switches to the data mode. Does nothing if already in it (nil returned).
+    * ((<define_mode?>))     Inquire whether the file is in the define mode.
+    * ((<sync>))     Synchronizes the disk copy of a netCDF dataset with in-memory buffer
+    * ((<def_dim>))     Define a dimension
+    * ((<put_att>))     Sets a global attribute
+    * ((<def_var>))     Defines a variable
+    * ((<def_var_with_dim>))     Same as def_var but defines dimensions first if needed
+    * ((<var>))     Opens an existing variable in the file
+    * ((<vars>))    Opens existing variables in the file
+    * ((<dim>))     Opens an existing dimension in the file
+    * ((<dims>))     Opens existing dimensions in the file
+    * ((<att>))     Opens an existing global attribute in the file
+    * ((<fill=>))     Sets a fill mode. (Default behavior of NetCDF is FILL.)
+    * ((<each_dim>))     Iterator regarding the dimensions in the file.
+    * ((<each_var>))     Iterator regarding the variables in the file.
+    * ((<each_att>))     Iterator regarding the global attributes of the file.
+    * ((<dim_names>))     Returns the names of all dimensions in the file
+    * ((<var_names>))     Returns the names of all variables in the file
+    * ((<att_names>))     Returns the names of all the global attributes of the file
+
+* ((<class NetCDFDim>))
+
+  Class Methods
+
+  Instance Methods
+    * ((<length>))     Returns the length of the dimension
+    * ((<length_ul0>))     Same as length but returns 0 for the unlimited dimension
+    * ((<name=>))     Rename the dimension
+    * ((<name>))     Returns the name of the  dimension
+    * ((<unlimited?>))     Inquires whether the dimension is unlimited or not
+
+* ((<class NetCDFVar>))
+
+  Class Methods
+    * ((<NetCDFVar.new>))     Combines NetCDF.open and NetCDF#Var to open a variable with one line (no need to use this).
+    * ((<NetCDFVar.unpack_type=>))    Fix the NArray type to be used
+      in ((<unpack>))
+    * ((<NetCDFVar.unpack_type>))     Returns the NArray type set by ((<NetCDFVar.unpack_type=>)).
+
+  Instance Methods
+    * ((<dim>))     Inquires the dim_num-th dimension of the variable (dim_num=0,1,2,..)
+    * ((<dims>))     Returns an array of all the dimensions of the variable
+    * ((<shape_ul0>))     Returns the shape of the variable, but the length of the unlimited dimension is set to zero.
+    * ((<shape_current>))     Returns the current shape of the variable.
+##    * ((<url>))     Returns a combination of filename (path) and variable name as path+'?var='+varname
+    * ((<each_att>))     Iterator regarding the global attributes of the variables.
+    * ((<dim_names>))     Returns the names of all the dimensions of the variable
+    * ((<att_names>))     Returns the names of all the attributes of the variable
+    * ((<name>))     Returns the name of the variable
+    * ((<name=>))     Rename the variable
+    * ((<ndims>))     Number of dimensions of the variable (which is rank of the variable).
+    * ((<rank>))     aliased to ndims
+    * ((<ntype>))      Aliased to vartype
+    * ((<vartype>))     Inquires the data value type of the variable
+    * ((<typecode>))     Inquires the data type of the variable (returns a typecode of NArray)
+    * ((<natts>))     Returns the number of the attributes of the variable
+    * ((<file>))     Inquires the file that the variable is in
+    * ((<att>))     Returns the attribute specified by its name
+    * ((<put_att>))     Sets an attribute
+    * ((<put>))     Aliased to ((<simple_put>))
+    * ((<simple_put>))     Set the values of the variable
+    * ((<pack>)) Pack a NArray (etc) using the attributes scale_factor and/or add_offset of self.
+    * ((<scaled_put>))     Same as ((<simple_put>)) but interprets the attributes scale_factor and/or add_offset using ((<pack>)).
+    * ((<get>))     Aliased to ((<simple_get>))
+    * ((<simple_get>))     Returns values of the variable
+    * ((<unpack>)) Unpack a NArray (etc) using the attributes scale_factor and/or add_offset of self.
+    * ((<scaled_get>))     Same as ((<simple_get>)) but interprets the attributes scale_factor and/or add_offset using ((<unpack>)).
+    * ((<[]>))     Same as NetCDFVar#get but a subset is specified as in the method [] of NArray. 
+    * ((<[]=>))     Same as NetCDFVar#put but a subset is specified as in the method []= of NArray. 
+
+
+  Instance Methods added by requiring "numru/netcdf_miss"
+
+    * ((<get_with_miss>))     Same as ((<get>)) but interprets data missing.
+    * ((<get_with_miss_and_scaling>))     Same as ((<get_with_miss>)) but handles data scaling too.
+    * ((<put_with_miss>))     Same as ((<put>)) but interprets data missing.
+    * ((<put_with_miss_and_scaling>))     Same as ((<put_with_miss>)) but handles data scaling too.
+
+
+* ((<class NetCDFAtt>))
+
+  Class Methods
+
+  Instance Methods
+    * ((<name>))     Returns the name of the attribute
+    * ((<name=>))     Rename the attribute
+    * ((<copy>))     Copies an attribute to a variable or a file. If file, becomes an global attribute
+    * ((<delete>))     Delete an attribute
+    * ((<put>))     Sets the value of the attribute
+    * ((<get>))     Returns the values of the attribute
+    * ((<atttype>))     Inquires the type of attribute values
+    * ((<typecode>))    Inquires the type of attribute values (returns a NArray typecode)
+
+---------------------------------------------
+
+=class NetCDF
+===Class Methods
+---NetCDF.open(filename, mode="r", share=false)
+     Opens a file (class method). If mode="w" and the file does not
+     exist, a new file is created.
+
+     Arguments
+     * filename (String): file name (path)
+     * mode (String) : IO mode "r" (read only); "w","w+" (write --
+       current contents are overwritten (eliminated!)); "r+","a","a+"
+       (append -- writable while current contents are preserved).
+       All the options permit reading, unlike the predefined File class.
+       Note that to "append" will require extra time and disk
+       space due to the limitations of the original NetCDF library,
+       which is used in this library.
+     * share (true or false) : Whether to use the "shared" mode or not 
+       (set true if a file being written may be read from other
+       processes. See nc_open in Ch.5 of users' guide of the C version)
+
+     Return value
+     * a NetCDF object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF 
+     * nc_open, nc_create
+
+---NetCDF.new
+     Aliased to NetCDF.open
+
+---NetCDF.create(filename, noclobber=false, share=false)
+     Creates a NetCDF file (class method)
+     
+     Arguments
+     * filename (String) : file name (path)
+     * noclobber (true or false) : overwrite or not if the file exists
+     * share (true or false) : Whether to use the shared mode or not
+       (set true if a file being written may be read from other
+       processes. See nc_open in Ch.5 of users' guide of the C version)
+
+     Return value
+     *  a NetCDF object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_create
+
+---NetCDF.create_tmp(tmpdir=ENV['TMPDIR']||ENV['TMP']||ENV['TEMP']||'.', share=false)
+     Creates a temporary NetCDF file (class method).
+     Its name is automatically generated, and it is deleted when closed.
+     
+     Arguments
+     * tmpdir (String) : directory to place the temporary file.
+       By default, "." or a directory specified by an environmental
+       variable (TMPDIR or TMP or TEMP) is used. In a secure mode,
+       theses environmental variable is NOT used, and the default
+       value is '.'.
+     * share (true or false) : Whether to use the shared mode or not
+
+     Return value
+     *  a NetCDF object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_create
+
+===Instance Methods
+---close
+     Closes the file.
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_close
+
+---ndims
+     Returns the number of dimensions in the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_ndims
+
+---nvars
+     Returns the number of variables in the file
+   
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_nvars
+
+---natts
+     Returns the number of global attributes in the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_natts
+
+---unlimited
+     Returns the unlimited dimension in the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  a NetCDFDim if it exists; nil if not
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_unlimdim
+
+---path
+     Returns the path of the file (contents of the filename specified when opened/created)
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (none)
+
+---redef
+     Switches to the define mode. Does nothing if already in it (nil returned).
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  true if successfully switched to the define mode;
+	nil if the file is already in the define mode.
+	Exception is raised if unsuccessful for other reasons.
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_redef
+
+---enddef
+     Switches to the data mode. Does nothing if already in it (nil returned).
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  true if successfully switched to the data mode;
+	nil if the file is already in the data mode.
+	Exception is raised if unsuccessful for other reasons.
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_enddef
+
+---define_mode?
+     Inquire whether the file is in the define mode.
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  true if the data is in the define mode;
+	false if the file is in the data mode;
+	nil otherwise (possibly the file is read-only).
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  combination of nc_redef and nc_enddef
+
+---sync
+     Synchronizes the disk copy of a netCDF dataset with in-memory buffer
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_sync
+
+---def_dim(dimension_name, length)
+     Define a dimension
+
+     Arguments
+     * dimension_name (String) : Name of the dimension to be defined
+     * length (Integer) : length of the dimension. 0 for unlimited.
+
+     Return value
+     *  defined dimension (NetCDFDim object)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_def_dim
+
+---put_att(attribute_name, value, atttype=nil)
+     Sets a global attribute
+
+     Arguments
+     * attribute_name (String) : name of the global attribute
+     * value (Numeric, String, Array of Numeric, or NArray) : value of the attribute
+     * atttype (nil or String) : data type of the attribute value.
+       nil lets it automatically determined from the value.
+       "char" (or "string"), "byte", "sint", "int", "sfloat", or "float"
+       specifies the type explicitly (1,1,2,4,4,8 bytes, respectively)
+
+     Return value
+     *  created attribute (NetCDFAtt object)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_put_att_<type>
+
+---def_var(name, vartype, dimensions)
+     Defines a variable
+
+     Arguments
+     * name (String) : Name of the variable to define
+     * vartype (String or Fixnum) : data type of the variable ("char", "byte", "sint",
+       "sint", "int", "sfloat", or "float"), or a NArray typecodes(Fixnum)
+     * dimensions (Array) : Dimensions of the variable. An Array of
+       NetCDFDim, in the order from the fastest varying dimension to
+       the slowest varying one; its length becomes the rank of the
+       variable.
+
+     Return value
+     *  defined variable (NetCDFVar object)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_def_var
+
+---def_var_with_dim(name, vartype, shape_ul0, dimnames)
+     Same as def_var but defines dimensions first if needed.
+     Raise exception if it conflicts with the lengths of existing dimensions.
+
+     Arguments
+     * name (String) : Name of the variable to define
+     * vartype (String) : data type of the variable ("char", "byte", "sint",
+       "sint", "int", "sfloat", or "float")
+     * shape_ul0 (Array of Integer) : Shape of the variable, i.e.,
+       lengths of dimensions. The unlimited dimension is specified by zero.
+       The length of shape_ul0 determines the rank of the variable.
+     * dimnames (Array of String) : Names of the dimensions. Its length
+       (=>rank) must be equal to that of shape_ul0
+
+     Return value
+     *  defined variable (NetCDFVar object)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (nc_def_var)
+
+---var(var_name)
+     Opens an existing variable in the file
+
+     Arguments
+     * var_name (String) : Name of the variable to open
+
+     Return value
+     * a NetCDFVar object; nil if the variable does not exist
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * nc_inq_varid
+
+---vars(names)
+     Opens existing variables in the file
+
+     Arguments
+     * names (nil or Array of String): Names of the variables to open; 
+       all variables are returned if nil (default).
+
+     Return value
+     * Array of NetCDFVar objects; exception is raised if names has a 
+       non-existent name
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * nc_inq_varid
+
+---dim(dimension_name)
+     Opens an existing dimension in the file
+
+     Arguments
+     * dimension_name (String) : Name of the dimension to open
+
+     Return value
+     * a NetCDFDim object; nil if the dimension does not exist
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * nc_inq_dimid
+
+---dims(names)
+     Opens existing dimensions in the file
+
+     Arguments
+     * names (nil or Array of String): Names of the dimensions to open; 
+       all dimensions are returned if nil (default).
+
+     Return value
+     * Array of NetCDFDim objects; exception is raised if names has a 
+       non-existent name
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * nc_inq_dimid
+
+---att(attribute_name)
+     Opens an existing global attribute in the file
+
+     Arguments
+     * attribute_name (String) : Name of the global attribute to open
+
+     Return value
+     *  a NetCDFAtt object if the attribute exists; nil if not
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (nc_inq_attid used for inquiry)
+
+---fill=(filemode)
+     Sets a fill mode. (Default behavior of NetCDF is FILL.)
+
+     Arguments
+     * fillmode (true or false)
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_set_fill
+
+---each_dim{ ... }
+     Iterator regarding the dimensions in the file.
+     Ex.: {|i| print i.name,"\n"} prints names of all dimensions
+
+     Arguments
+     * { ... } : Block for the iterator. A "do end" block is the alternative.
+
+     Return value
+     *  self
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_ndims)
+
+---each_var{ ... }
+     Iterator regarding the variables in the file.
+     Ex.: {|i| print i.name,"\n"} prints names of all variables
+
+     Arguments
+     * { ... } :  Block for the iterator. A "do end" block is the alternative.
+
+     Return value
+     *  self
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_nvars)
+
+---each_att{ ... }
+     Iterator regarding the global attributes of the file.
+     Ex.: {|i| print i.name,"\n"} prints names of all of them.
+
+     Arguments
+     * { ... } : Block for the iterator. A "do end" block is the alternative.
+
+     Return value
+     *  self
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_natts, nc_inq_attname)
+
+---dim_names
+     Returns the names of all dimensions in the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of NetCDFDim
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (nc_inq_ndims, nc_inq_dimname)
+
+---var_names
+     Returns the names of all variables in the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_nvars, nc_inq_varname)
+
+---att_names
+     Returns the names of all the global attributes of the file
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of NetCDFAtt
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_natts, nc_inq_attname)
+
+---------------------------------------------
+
+=class NetCDFDim
+===Class Methods
+
+===Instance Methods
+---length
+     Returns the length of the dimension
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_dimlen
+
+---length_ul0
+     Same as length but returns 0 for the unlimited dimension
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_dimlen
+
+---name=(dimension_newname)
+     Rename the dimension
+
+     Arguments
+     * dimension_newname (String) : new name
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_rename_dim
+
+---name
+     Returns the name of the  dimension
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_dimname
+
+---unlimited?
+     Inquires whether the dimension is unlimited or not
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  true or false
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_unlimdim)
+
+---------------------------------------------
+
+=class NetCDFVar
+===Class Methods
+---NetCDFVar.new(file,varname,mode="r",share=false)
+     open a NetCDF variable. This can also be done with NetCDF#var
+     (instance method of NetCDF class),  which is recommended over
+     this method.
+
+     Arguments
+     * file (NetCDF or String) : a NetCDF file object (NetCDF)
+       or the path of a NetCDF file (String).
+     * varname (String) : name of the variable in the file
+     * mode (String) : IO mode -- used if file is a String (see NetCDF.open)
+     * share (true or false) : Whether to use the "shared" mode or 
+       not  -- used if file is a String (see NetCDF.open)
+
+     Return value
+     * a NetCDFVar object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF 
+     * (dependent on nc_open, nc_create, nc_inq_varid etc.)
+
+---NetCDFVar.unpack_type=(na_type)
+     Fix the NArray type to be used in ((<unpack>)).
+
+     Arguments
+     * na_type (Integer) : NArray::BYTE, NArray::SINT, NArray::INT, 
+       NArray::SFLOAT, or NArray::FLOAT
+
+     Return value
+     * na_type (the argument)
+
+---NetCDFVar.unpack_type
+     Returns the NArray type set by ((<NetCDFVar.unpack_type=>)).
+
+     Return value
+     * nil, NArray::BYTE, NArray::SINT, NArray::INT, 
+       NArray::SFLOAT, or NArray::FLOAT
+
+===Instance Methods
+---dim(dim_num)
+     Inquires the dim_num-th dimension of the variable (dim_num=0,1,2,..)
+
+     Arguments
+     * dim_num (Fixnum) : 0,1,...  0 is the fastest varying dimension.
+
+     Return value
+     *  a NetCDFDim object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_vardimid)
+
+---dims
+     Returns an array of all the dimensions of the variable
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of NetCDFDim objects.
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_vardimid
+
+---shape_ul0
+     Returns the shape of the variable, but the length of the unlimited dimension is set to zero.
+     Good to define another variable.
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array. [length of 0th dim, length of 1st dim,.. ]
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_vardimid, nc_inq_unlimdim etc)
+
+---shape_current
+     Returns the current shape of the variable.
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array. [length of 0th dim, length of 1st dim,.. ]
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_vardimid etc)
+
+---each_att{ ... }
+     Iterator regarding the global attributes of the variables.
+     Ex.: {|i| print i.name,"\n"} prints names of all of them.
+
+     Arguments
+     * { ... }  : Block for the iterator. A "do end" block is the alternative.
+
+     Return value
+     *  self
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_natts, nc_inq_attname)
+
+---dim_names
+     Returns the names of all the dimensions of the variable
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_varndims, nc_inq_vardimid, nc_inq_dimname)
+
+---att_names
+     Returns the names of all the attributes of the variable
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Array of String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (dependent on nc_inq_natts, nc_inq_attname)
+
+---name
+     Returns the name of the variable
+ 
+     Arguments
+     *  (none)
+
+     Return value
+     *  String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_varname
+
+---name=(variable_newname)
+     Rename the variable
+
+     Arguments
+      * variable_newname (String) : new name
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_rename_var
+
+---ndims
+     Number of dimensions of the variable (which is rank of the variable).
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_varndims
+
+---rank
+     Aliased to ndims
+
+---ntype
+     Aliased to vartype
+
+---vartype
+     Inquires the data value type of the variable
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  String ("char","byte","sint","int","sfloat", or "float")
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_vartype
+
+---typecode
+     Inquires the data type of the variable (returns a typecode of NArray)
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  a Fixnum (NArray:BYTE, NArray:SINT, NArray:LINT, NArray:SFLOAT, NArray:SFLOAT, NArray:DFLOAT)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_vartype
+
+---natts
+     Returns the number of the attributes of the variable
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  Integer
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_varnatts
+
+---file
+     Inquires the file that the variable is in
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  a NetCDF object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (none)
+
+---att(attribute_name)
+     Returns the attribute specified by its name
+
+     Arguments
+     * attribute_name (String) : Name of the attribute
+
+     Return value
+     *  a NetCDFAtt object if the attribute exists; nil if not
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (nc_inq_attid is used for inquiry)
+
+---put_att(attribute_name, value, atttype=nil)
+     Sets an attribute
+
+     Arguments
+     * attribute_name (String) : name of the attribute
+     * value (Numeric, String, Array of Numeric, or NArray) : value of the attribute
+     * atttype (nil or String) : data type of the attribute value.
+       nil lets it automatically determined from the value.
+       "char" (="string"), "byte", "sint", "int", "sfloat", or "float"
+       specifies the type explicitly (1,1,2,4,4,8 bytes, respectively)
+
+     Return value
+     *  a NetCDFAtt object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_put_att_<type>
+
+---put(value, option=nil)
+     Aliased to ((<simple_put>))
+
+---simple_put(value, option=nil)
+     Set the values of the variable
+
+     Arguments
+     * value : value to set (Numeric, Array of Numeric (1D only), or 
+       NArray (possibly multi-D)). If it is a Numeric or length==1, the value
+       is set uniformly.
+     * option (Hash) : Optional argument to limit the portion of the
+       variable to output values. If omitted, the whole variable is
+       subject to the output. This argument accepts a Hash whose keys
+       contain either "index" or a combination of "start","end", and
+       "stride". The value of "index" points the index of a scalar
+       portion of the variable. The other case is used to designate a
+       regularly ordered subset, where "start" and "end" specifies
+       bounds in each dimension and "stride" specifies intervals in
+       it. As in Array "start", "end", and "index" can take negative
+       values to specify index backward from the end. However,
+       "stride" has to be positive, so reversing the array must be
+       done afterwards if you like.
+
+       Example: If the variable is 2D:
+
+       {"start"=>[2,5],"end"=>[6,-1],"stride"=>[2,4]} -- Specifies a 
+       subset made as follows: the 1st dimension from the element 2
+       to the element 6 (note that the count starts with 0, so that
+       the element 2 is the 3rd one) with an interval of 2; 
+       the 2nd dimension from the element 6 to the last element
+       (designated by -1) with an interval of 5.
+
+       {"index"=>[0,0]}: Scalar of the fist element
+
+       {"index"=>[0,-2]}: Scalar from the 1st element of with
+       respect to the 1st dimension and the 2nd element from the last
+       with respect to the 2nd dimension
+
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_put_var_<type>, nc_put_vars_<type>, nc_put_var1_<type>
+
+---pack(na)
+     Pack a NArray (etc) using the attributes scale_factor and/or add_offset of self.
+
+     If scale_factor and/or add_offset is defined, returns
+     (na-add_offset)/scale_factor. Returns na if not.
+
+     Arguments
+     * na : a numeric array to pack (NArray, NArrayMiss, or Array)
+
+     Return value
+     *  a NArray or NArrayMiss
+
+---scaled_put(value, option=nil)
+     Same as ((<simple_put>)) but interprets the attributes scale_factor and/or add_offset using ((<pack>)).
+
+     See the document for ((<simple_put>)) for arguments etc.
+
+---get(option=nil)
+     Aliased to ((<simple_get>)).
+
+---simple_get(option=nil)
+     Returns values of the variable
+
+     Arguments
+     * option (Hash) : Optional argument to limit the portion of the
+       variable to get values. Its usage is the same as in the method
+       put.
+
+     Return value
+     *  an NArray object
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_get_var_<type>, nc_get_vars_<type>, nc_get_var1_<type>
+
+---unpack(na)
+     Unpack a NArray (etc) using the attributes scale_factor and/or add_offset of self.
+
+     If scale_factor and/or add_offset is defined, returns
+     na * scale_factor + add_offset. Returns na if not.
+     Type conversion is made by the coercing -- for example
+     if na is sint and scale_factor and add_offset is sfloat,
+     return value is sfloat. The type of the return value can be specified
+     explicitly with ((<NetCDFVar.unpack_type=>)).
+
+     Arguments
+     * na : a numeric array to unpack (NArray, or NArrayMiss)
+
+     Return value
+     *  a NArray or NArrayMiss
+
+---scaled_get(option=nil)
+     Same as ((<simple_get>)) but interprets the attributes scale_factor and/or add_offset using ((<unpack>)).
+
+     See the document for ((<simple_get>)) for arguments etc.
+
+---[]
+     Same as NetCDFVar#get but a subset is specified as in the method [] of NArray. 
+
+     In addition to the subset specifications supported by NArray, 
+     ranges with steps are supported, which is specified
+     like {0..-1, 3}, i.e., a 1-element Hash with the key and value 
+     representing the range (Range) and the step (Integer), respectively.
+     Unlike NArray, 1-dimensional indexing of multi-dimensional
+     variables is not support.
+
+---[]=
+     Same as NetCDFVar#put but a subset is specified as in the method []= of NArray. 
+
+     In addition to the subset specifications supported by NArray, 
+     ranges with steps are supported, which is specified
+     like {0..-1, 3}, i.e., a 1-element Hash with the key and value 
+     representing the range (Range) and the step (Integer), respectively.
+     Unlike NArray, 1-dimensional indexing of multi-dimensional
+     variables is not support.
+
+===Instance Methods added by requiring "numru/netcdf_miss"
+
+---get_with_miss(option=nil)
+     Same as ((<get>)) but interprets data missing.
+
+     Data missing is specified by the standard attributes valid_range,
+     (valid_min and/or valid_max), or missing_value, with the precedence being 
+     this order. Unlike the
+     recommendation in the NetCDF User's guide, missing_value is
+     interpreted if present. If missing_value and valid_* present
+     simultaneously, missing_value must be outside the valid range.
+     Otherwise, exception is raised.
+
+     If data missing is specified as stated above, this method returns a NArrayMiss.
+     If not, it returns a NArray. Thus, you can use this whether
+     data missing is defined or not.     
+
+     Arguments
+     * See ((<get>)).
+
+     Return value
+     * an NArrayMiss (if data missing is specified) or an NArray
+       (if data missing is NOT specified)
+
+     Possible exception in addition to NetcdfError.
+     * missing_value is in the valid range (see above).
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * See ((<get>)). This method is written in Ruby.
+
+     EXAMPLE
+     * The following is an example to replace ((<get>)) with ((<get_with_miss>)).
+       It will also make ((<[]>)) interpret data missing, 
+       since it calls (({get})) internally.
+
+         file = NetCDF.open('hogehoge.nc')
+         var = file.var('var')
+         def var.get(*args); get_with_miss(*args); end
+         p var.get       # --> interprets data missing if defined
+         p var[0..-1,0]  # --> interprets data missing if defined (assumed 2D)
+
+---get_with_miss_and_scaling(option=nil)
+     Same as ((<get_with_miss>)) but handles data scaling too using ((<unpack>)).
+
+     Missing data handling using valid_* / missing_value is applied 
+     basically to packed data, which is consistent with most
+     conventions. However, it is applied to unpacked data 
+     if and only if the type of valid_* / missing_value is not the same as
+     the packed data and is the samed as the unpacked data.
+     This treatment can handle all conventions.
+
+     EXAMPLE
+     * See above. The same thing applies.
+
+---put_with_miss(value, option=nil)
+     Same as ((<put>)) but interprets data missing.
+
+     If (({value})) is an NArray, the methods behaves as ((<put>)).
+     Data missing in (({value})) is interpreted if it is an NArrayMiss
+     and data missing is specified by attributes in (({self})) 
+     (see ((<get_with_miss>)) ).
+     Namely, the data which are "invalid" in the (({value})) is replaced
+     with a missing value when written in the file.
+     (missing_value or _FillValue or a value outside
+     the valid range). No check is made whether "valid" values in the 
+     NArrayMiss is within the valid range of (({self})).
+
+     Arguments
+     * value : NArrayMiss or what is allowed in ((<put>)).
+     * option (Hash) : See ((<put>)).
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     * See ((<put>)). This method is written in Ruby.
+
+     EXAMPLE
+     * The following is an example to replace ((<put>)) with ((<put_with_miss>)).
+       It will also make ((<[]=>)) interpret data missing, 
+       since it calls (({put})) internally.
+
+         file = NetCDF.open('hogehoge.nc')
+         var = file.var('var')
+         def var.put(*args); put_with_miss(*args); end
+         var.put = narray_miss      # --> interprets data missing if defined
+         var[0..-1,0] = narray_miss # --> interprets data missing if defined (assumed 2D)
+
+---put_with_miss_and_scaling(value, option=nil)
+     Same as ((<put_with_miss>)) but handles data scaling too using ((<pack>)).
+
+     Missing data handling using valid_* / missing_value is applied 
+     basically to packed data, which is consistent with most
+     conventions. However, it is applied to unpacked data 
+     if and only if the type of valid_* / missing_value is not the same as
+     the packed data and is the samed as the unpacked data.
+     This treatment can handle all conventions.
+
+     EXAMPLE
+     * See above. The same thing applies.
+
+---------------------------------------------
+
+=class NetCDFAtt
+===Class Methods
+
+===Instance Methods
+---name
+     Returns the name of the attribute
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  String
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  (none)
+
+---name=(attribute_newname)
+     Rename the attribute
+
+     Arguments
+     * attribute_newname (String) : New name
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_rename_att
+
+---copy(var_or_file)
+     Copies an attribute to a variable or a file. If file, becomes an global attribute
+
+     Arguments
+     * var_or_file (NetCDFVar or NetCDF)
+
+     Return value
+     *  Resultant new attribute (NetCDFAtt)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_copy_att
+
+---delete
+     Delete an attribute
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_del_att
+
+---put(value, atttype=nil)
+     Sets the value of the attribute
+
+     Arguments
+     * value (Numeric, String, Array of Numeric, or NArray) : value of the attribute
+     * atttype (nil or String) : data type of the attribute value.
+       nil lets it automatically determined from the value.
+       "char" (="string"), "byte", "sint", "int", "sfloat", or "float"
+       specifies the type explicitly (1,1,2,4,4,8 bytes, respectively)
+
+     Return value
+     *  nil
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_put_att_<type>
+
+---get
+     Returns the values of the attribute
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  String or an NArray object (NOTE: even a scalar is returned as
+        an NArray of length 1)
+     
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_get_att_<type>
+
+---atttype
+     Inquires the type of attribute values
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  "char","byte","sint","int","sfloat","float"
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_atttype
+
+---atttype
+     Inquires the type of attribute values (returns a NArray typecode)
+
+     Arguments
+     *  (none)
+
+     Return value
+     *  a Fixnum (NArray:BYTE, NArray:SINT, NArray:LINT, NArray:SFLOAT, NArray:SFLOAT, NArray:DFLOAT)
+
+     Corresponding (dependent) function(s) in the C library of NetCDF
+     *  nc_inq_atttype
+
+=end