関数 nc_get_varm_ type の一族は開かれたNetCDFファイルのNetCDF変数からマップされた配列断面を読みます。 マップされた配列断面は隅・縁の長さ・ ストライドベクトル・インデックスマッピングベクトル を与えることによって指定されます。 インデックスマッピングベクトルとはNetCDF変数と内部データ配列のメモリ内構造との間のマッピングを指定する整数ベクトルです。データ配列に関しては順番や長さなどについていかなる仮定もされません。
int nc_get_varm_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], char *tp);
int nc_get_varm_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], unsigned char *up);
int nc_get_varm_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], signed char *cp);
int nc_get_varm_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], short *sp);
int nc_get_varm_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], int *ip);
int nc_get_varm_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], long *lp);
int nc_get_varm_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], float *fp);
int nc_get_varm_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], double *dp);
|
先頭のデータ値が読み込まれる変数を指定する、サイズ_tの整数のベクトル。インデックスは零に相対的なので、変数の最初のデータ値のインデックスは（0,0､．．．､0）になります。 start の要素は指定された変数の次元と順番に対応しています。よって､記録変数の場合には、最初のインデックスはデータ値を読み取る開始記録番号に相当する。 |
|
|
各次元に沿って幾つのインデックスが選定されるかを指定するサイズ_t の整数ベクトル。 例えば単一の値を読み取る場合には、 count を (1, 1, ... , 1) と指定すればよい。 count の要素は変数の次元に順番に対応する。よって、記録変数の場合には count の最初の要素が読み取る記録数の総計に対応する。 |
|
|
各次元ごとに選定されたインデックスの間隔を指定するサイズptrdiff_t の整数ベクトル 。 ストライドベクトルの要素は変数の次元に順番に対応する。値が１ならば、対応する次元のNetCDF変数で隣接する値をアクセスする。値が２の場合には対応するNetCDF変数の値を一つおきにアクセスする。 NULL ストライド引数は (1, 1, ... , 1) として扱われる。 |
|
|
NetCDF変数の次元と内部データ配列とのメモリ内構造間のマッピングを指定する整数ベクトル。 imap[0] は最も遅く変化するNetCDF変数の次元に対応する内部配列の要素と要素間の距離を示します。 imap[n-1] （n はNetCDF変数のランク ）最も早く変化するNetCDF変数の次元に対応する内部配列の要素と要素の間の距離を示します。この二つの要素の間にある他の要素が他のNetCDF変数の次元に対応することは自明です。要素間の距離は要素の型独立の単位で指定されます。（隣接する位置にある内部メモリ間の距離は１であり、NetCDF2のように要素のバイト長ではありません。） |
|
|
データ値が読み込まれる位置へのポインタ。データ型は呼び出された関数に適した型でなければなりません。データ型がNetCDF変数型と異なる場合にはタイプ変換が行なわれます。 詳細はタイプ変換を参照のこと。 |
次の imap ベクトルは 4x3x2 のNetCDF変数と同じ形の内部配列を自明な形でマップします。
float a[4][3][2]; /* NetCDF変数と同じ形 */
size_t imap[3] = {6, 2, 1};
/* NetCDF次元 要素間距離 */
/* ---------------- ---------------------- */
/* 最も早く変化する 1 */
/* 中間 2 (=imap[2]*2) */
/* 最も遅く変化する 6 (=imap[1]*3) */
上記の imap ベクトルと nc_get_varm_float とを使用た場合と、単に nc_get_var_float を使用した場合とでは同じ結果が得られます。
この例では nc_get_varm_float を使用してC 宣言文 float rh[6][4] （次元のサイズと順番に注目）で表わされたNetCDF変数 rh を移項します。
#include <netcdf.h>
...
#define NDIM 2 /* rank of NetCDF変数のランク */
int ncid; /* NetCDF ID */
int status; /* エラーステータス */
int rhid; /* 変数ID */
static size_t start[NDIM] /* NetCDF変数のスタート地点 : */
= {0, 0}; /* 最初の要素 */
static size_t count[NDIM] /* 内部配列のサイズ: NetCDF変数全体；*/
= {6, 4}; /* 順番はNetCDF変数の順番に対応 */
/* -- 内部配列の順番ではない */
static ptrdiff_t stride[NDIM] /* 変数の部分サンプ間隔: */
= {1, 1}; /* NetCDF要素を一つおきにサンプル */
static ptrdiff_t imap[NDIM] /* 内部配列の要素間距離; */
= {1, 6}; /* 置換しなければ {4, 1} */
float rh[4][6]; /* NetCDF変数の次元が */
/* 置換されている点に注意 */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
関数 nc_get_varm_float を使用したこの別の例では、NetCDF変数の点を一つ置きにアクセスして同じNetCDF変数を移項すると同時に部分サンプルします。
#include <netcdf.h>
...
#define NDIM 2 /* NetCDF変数のランク */
int ncid; /* NetCDF ID */
int status; /* エラーステータス */
int rhid; /* 変数ID */
static size_t start[NDIM] /* NetCDF変数のスタート地点: */
= {0, 0}; /* 最初の要素 */
static size_t count[NDIM] /* 内部配列のサイズ: 全ての */
= {3, 2}; /* （部分サンプルされた） NetCDF変数；次元の */
/* 順番はNetCDF変数に対応 */
/* -- 内部配列にではない*/
static ptrdiff_t stride[NDIM]/* 変数の部分サンプル間隔: */
= {2, 2}; /* NetCDF要素を一つおきにサンプル */
static ptrdiff_t imap[NDIM] /* 内部配列の要素間距離; */
= {1, 3}; /* 置換しなければ {2, 1} */
float rh[2][3]; /* （部分サンプルされた）NetCDF変数次元が */
/* 置換されていることに注意 */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);