bes  Updated for version 3.20.6
ndarray.h
1 /*
2  * FILENAME: ndarray.h
3  *
4  * Structure and function declarations for ndarray.c
5  *
6  * MACROS:
7  *
8  * NDARR_RESET_INDICES(ARRAY_INDEX_PTR)
9  * resets the indices to the origion.
10  * NDARR_SET_PADDING(NDARR_SOURCE, char)
11  * sets the padding character.
12  * NDARR_GET_SEPARATION(ARRAY_INDEX_PTR, long)
13  * determines what length of separation is necessary after the indexed element.
14  * NDARR_GET_MAP_SEPARATION(ARRAY_MAPPING_PTR, long)
15  * determines what length of separation is necessary after the mapping increment
16  * block.
17  *
18  * CAVEAT:
19  * No claims are made as to the suitability of the accompanying
20  * source code for any purpose. Although this source code has been
21  * used by the NOAA, no warranty, expressed or implied, is made by
22  * NOAA or the United States Government as to the accuracy and
23  * functioning of this source code, nor shall the fact of distribution
24  * constitute any such endorsement, and no responsibility is assumed
25  * by NOAA in connection therewith. The source code contained
26  * within was developed by an agency of the U.S. Government.
27  * NOAA's National Geophysical Data Center has no objection to the
28  * use of this source code for any purpose since it is not subject to
29  * copyright protection in the U.S. If this source code is incorporated
30  * into other software, a statement identifying this source code may be
31  * required under 17 U.S.C. 403 to appear with any copyright notice.
32  *
33  */
34 
35 #ifndef NDARRAY_H__
36 #define NDARRAY_H__
37 
38 typedef unsigned short NDARR_SOURCE;
39 
40 /***************************
41  * Structure declarations: *
42  ***************************/
43 typedef struct array_descriptor_struct{
44  char **dim_name; /* names of each dimension */
45  long *start_index; /* array of dimension starting indices */
46  long *end_index; /* array of dimension ending indices */
47  long *granularity; /* array of dimension granularity */
48  long *grouping; /* array of dimension grouping */
49  long *separation; /* array of dimension speration (by bytes) */
50  char *index_dir; /* array of index directions (down or up) */
51  long *dim_size; /* An array of the size of each dimension */
52  long *coeffecient; /* A number necessary for calculating offsets */
53  void *extra_info; /* An extra pointer *RESERVED!* */
54  void *extra_index; /* A pointer to the groupmap index *RESERVED!* */
55  long total_elements; /* the number of elements in the array */
56  long num_groups; /* The number of groups in the array */
57  long group_size; /* The size of an individual group */
58  long contig_size; /* The size, in bytes, of the array contiguous (no separation) */
59  long total_size; /* The size, in bytes, of the whole array */
60  long element_size; /* The size of an individual element */
61  int num_dim; /* number of dimensions */
62  char type; /* The type of the array *RESERVED!* */
63 
64 #ifdef ND_FP
65  FILE *fp;
66 #endif
68 
69 typedef struct array_index_struct{
70  ARRAY_DESCRIPTOR_PTR descriptor; /* ptr to array descriptor */
71  long *index; /* The indices of the array */
73 
74 typedef struct array_mapping_struct{
75  ARRAY_DESCRIPTOR_PTR super_array; /* superset of the sub-array */
76  ARRAY_DESCRIPTOR_PTR sub_array; /* subset of the super-array */
77  int *dim_mapping; /* dimension mapping from sub-array to super-array */
78  long *index_mapping; /* index mapping from sub-array to super-array */
79  long *gran_mapping; /* Granularity mapping from sub to super array */
80  long *gran_div_mapping; /* Granularity mapping from super to sub array */
81  long *cacheing; /* For use with ndarr_reorient_to_cache */
82  char *index_dir; /* Direction of mapping from sub-array to super-array */
83  ARRAY_INDEX_PTR aindex; /* Extra index pointer (for use in calculations)*/
84  ARRAY_INDEX_PTR subaindex; /* The current sub-array indices */
85  long increment_block; /* size of elements readable at one time */
86  long superastart; /* The first offset in superarray for subarray */
87  long superaend; /* The last offset in superarray for subarray */
88  long subsep; /* the maximum padding length in the sub array */
89  int necessary; /* 0 if mapping is not necessary, !=0 if mapping necessary */
90  int dimincrement; /* The lowest unreoriented dimension */
91  char fcreated; /* Reserved for use in ndarr_reorient */
93 
94 /**************************
95  * Function declarations: *
96  **************************/
97 ARRAY_DESCRIPTOR_PTR ndarr_create(int numdim);
98 ARRAY_MAPPING_PTR ndarr_create_mapping(ARRAY_DESCRIPTOR_PTR subarray,
99  ARRAY_DESCRIPTOR_PTR superarray);
100 ARRAY_INDEX_PTR ndarr_create_indices(ARRAY_DESCRIPTOR_PTR arrdesc);
101 ARRAY_INDEX_PTR ndarr_increment_indices(ARRAY_INDEX_PTR aindex);
102 ARRAY_INDEX_PTR ndarr_increment_mapping(ARRAY_MAPPING_PTR amap);
103 ARRAY_INDEX_PTR ndarr_convert_indices(ARRAY_INDEX_PTR aindex,
104  unsigned char direction);
105 unsigned long ndarr_get_offset(ARRAY_INDEX_PTR aindex);
106 unsigned long ndarr_get_mapped_offset(ARRAY_MAPPING_PTR amap);
107 void ndarr_free_descriptor(ARRAY_DESCRIPTOR_PTR arrdesc);
108 void ndarr_free_indices(ARRAY_INDEX_PTR aindex);
109 void ndarr_free_mapping(ARRAY_MAPPING_PTR amap);
110 void *ndarr_get_group(ARRAY_INDEX_PTR aindex);
111 void *ndarr_get_next_group(ARRAY_DESCRIPTOR_PTR arrdesc, char mode);
112 int ndarr_do_calculations(ARRAY_DESCRIPTOR_PTR arrd);
113 int ndarr_create_brkn_desc(ARRAY_DESCRIPTOR_PTR adesc, int map_type, void *mapping);
114 int ndarr_set(ARRAY_DESCRIPTOR_PTR arrd, ...);
115 long ndarr_reorient(ARRAY_MAPPING_PTR amap,
116  NDARR_SOURCE sourceid, void *source, long source_size,
117  NDARR_SOURCE destid, void *dest, long dest_size,
118  int *array_complete);
119 
120 /*************************
121  * Preprocessor defines: *
122  *************************/
123 
124 /* ndarr_set arguments: */
125 #define NDARR_DIM_NUMBER (int)1
126 #define NDARR_DIM_NAME (int)2
127 #define NDARR_DIM_START_INDEX (int)3
128 #define NDARR_DIM_END_INDEX (int)4
129 #define NDARR_DIM_GRANULARITY (int)5
130 #define NDARR_DIM_GROUPING (int)6
131 #define NDARR_DIM_SEPARATION (int)7
132 #define NDARR_ELEMENT_SIZE (int)10
133 #define NDARR_FILE_GROUPING (int)20
134 #define NDARR_BUFFER_GROUPING (int)21
135 #define NDARR_MAP_IN_BUFFER (int)22
136 #define NDARR_MAP_IN_FILE (int)23
137 #define NDARR_END_ARGS (int)0
138 
139 /* ndarr_create_from_str tokens: */
140 #define NDARR_SB_KEY0 "sb"
141 #define NDARR_SB_KEY1 "separation"
142 #define NDARR_GB_KEY0 "gb"
143 #define NDARR_GB_KEY1 "grouping"
144 
145 /* ndarr_convert_indices arguments */
146 #define NDARR_USER_TO_REAL 'r'
147 #define NDARR_REAL_TO_USER 'u'
148 
149 /* Array types */
150 #define NDARRT_CONTIGUOUS 0
151 #define NDARRT_BROKEN 1
152 #define NDARRT_GROUPMAP_FILE 2
153 #define NDARRT_GROUPMAP_BUFF 3
154 
155 /* ndarr_get_next_group arguments */
156 #define NDARR_GINITIAL 0
157 #define NDARR_GNEXT 1
158 
159 /* Define array storage bitfields */
160 #define NDARRS_FILE (NDARR_SOURCE)0x8000
161 #define NDARRS_APPEND (NDARR_SOURCE)0x4000
162 #define NDARRS_UPDATE (NDARR_SOURCE)0x2000
163 #define NDARRS_CREATE (NDARR_SOURCE)0x1000
164 #define NDARRS_BUFFER (NDARR_SOURCE)0x0800
165 #define NDARRS_PADDING (NDARR_SOURCE)0x00FF
166 
167 /* If we are under freeform, use freeform's err functions */
168 /******************
169  * Define macros: *
170  ******************/
171 
172 /*
173  * NAME: NDARR_RESET_INDICES
174  *
175  * PURPOSE: To reset an ARRAY_INDEX struct so that its indices are all 0 (the origion)
176  *
177  * USAGE: void NDARR_RESET_INDICES(ARRAY_INDEX_PTR aindex)
178  *
179  * RETURNS: void
180  *
181  * DESCRIPTION: This is implmented as a macro, due to its extremely small size.
182  *
183  * SYSTEM DEPENDENT FUNCTIONS: none
184  *
185  * AUTHOR: Kevin Frender (kbf@ngdc.noaa.gov)
186  *
187  * COMMENTS: Implemented as a macro
188  *
189  * KEYWORDS: array macro
190  */
191 #define NDARR_RESET_INDICES(nda_i_p) { \
192  int nda_d_s; \
193  for(nda_d_s = 0; nda_d_s < nda_i_p->descriptor->num_dim; nda_d_s++) \
194  nda_i_p->index[nda_d_s] = 0;} \
195 
196 /*
197  * NAME: NDARR_SET_PADDING
198  *
199  * PURPOSE: To set the padding portion of an NDARR_SOURCE type variable.
200  *
201  * USAGE: void NDARR_SET_PADDING(NDARR_SOURCE svar, char paddingchar)
202  *
203  * RETURNS: void
204  *
205  * DESCRIPTION: This is implmented as a macro, due to its extremely small size.
206  * Sets the padding portion of the NDARR_SOURCE variable to paddingchar.
207  *
208  * SYSTEM DEPENDENT FUNCTIONS: none
209  *
210  * AUTHOR: Kevin Frender (kbf@ngdc.noaa.gov)
211  *
212  * COMMENTS: Implemented as a macro
213  *
214  * KEYWORDS: array macro
215  */
216 #define NDARR_SET_PADDING(nda_s_v, pad_c_v) { \
217  nda_s_v &= ~NDARRS_PADDING; \
218  nda_s_v |= (NDARRS_PADDING & (pad_c_v * 257));} \
219 
220 /*
221  * NAME: NDARR_GET_SEPARATION
222  *
223  * PURPOSE: To determine the length (in bytes) of the separation to follow the
224  * element with the given index.
225  *
226  * USAGE: void NDARR_GET_SEPARATION(ARRAY_INDEX_PTR aindex, long separation)
227  *
228  * RETURNS: void, but the separation length (in bytes) is stored in the long
229  * variable argument.
230  *
231  * DESCRIPTION: This is implmented as a macro, due to its relatively small size,
232  * and possible speed gains from inline code (this macro gets called
233  * frequently inside of big loops)
234  *
235  * Determines the number of bytes to come after the element named
236  * in the ARRAY_INDEX_PTR as separation.
237  *
238  * SYSTEM DEPENDENT FUNCTIONS: none
239  *
240  * AUTHOR: Kevin Frender (kbf@ngdc.noaa.gov)
241  *
242  * COMMENTS: Implemented as a macro
243  *
244  * KEYWORDS: array macro
245  */
246 #define NDARR_GET_SEPARATION(nda_i_p, nda_l_v) { \
247  int nda_t_i; \
248  nda_l_v = nda_i_p->descriptor->separation[nda_i_p->descriptor->num_dim - 1]; \
249  for(nda_t_i = nda_i_p->descriptor->num_dim - 2; nda_t_i >= 0; nda_t_i--) { \
250  if(nda_i_p->descriptor->grouping[nda_t_i + 1]) { \
251  if(!((nda_i_p->index[nda_t_i + 1] + 1) % \
252  nda_i_p->descriptor->grouping[nda_t_i + 1])) { \
253  nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
254  } \
255  else { \
256  break; \
257  } \
258  } \
259  else { \
260  if(((nda_i_p->index[nda_t_i + 1] + 1) == \
261  nda_i_p->descriptor->dim_size[nda_t_i + 1])) { \
262  nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
263  } \
264  else { \
265  break; \
266  } \
267  } \
268  }\
269 } \
270 
271 
272 /*
273  * NAME: NDARR_GET_MAP_SEPARATION
274  *
275  * PURPOSE: To determine the length (in bytes) of the separation to follow the
276  * array mapping increment starting with amap->subaindex.
277  *
278  * USAGE: void NDARR_GET_MAP_SEPARATION(ARRAY_MAPPING_PTR amap, long separation)
279  *
280  * RETURNS: void, but the separation length (in bytes) is stored in the long
281  * variable argument.
282  *
283  * DESCRIPTION: This is implmented as a macro, due to its relatively small size,
284  * and possible speed gains from inline code (this macro gets called
285  * frequently inside of big loops)
286  *
287  * Determines the number of bytes to come after the amap->increment_block
288  * whose starting index is specified by amap->subaindex.
289  *
290  * SYSTEM DEPENDENT FUNCTIONS: none
291  *
292  * AUTHOR: Kevin Frender (kbf@ngdc.noaa.gov)
293  *
294  * COMMENTS: Implemented as a macro
295  *
296  * KEYWORDS: array macro
297  */
298 #define NDARR_GET_MAP_SEPARATION(nda_m_p, nda_l_v) { \
299  int nda_t_i; \
300  ARRAY_INDEX_PTR nda_i_p = nda_m_p->subaindex; \
301  nda_l_v = nda_i_p->descriptor->separation[nda_m_p->dimincrement]; \
302  for(nda_t_i = nda_m_p->dimincrement - 1; nda_t_i >= 0; nda_t_i--) \
303  { \
304  if(nda_i_p->descriptor->grouping[nda_t_i + 1]) \
305  { \
306  if(!((nda_i_p->index[nda_t_i + 1] + 1) % \
307  nda_i_p->descriptor->grouping[nda_t_i + 1])) \
308  nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
309  else \
310  break; \
311  } \
312  else \
313  { \
314  if(((nda_i_p->index[nda_t_i + 1] + 1) == \
315  nda_i_p->descriptor->dim_size[nda_t_i + 1])) \
316  nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
317  else \
318  break; \
319  } \
320  } \
321 }
322 
323 /* End of ndarray.h */
324 
325 #include "freeform.h"
326 
327 
328 #endif
array_index_struct
Definition: ndarray.h:69
array_descriptor_struct
Definition: ndarray.h:43
array_mapping_struct
Definition: ndarray.h:74