ndarray.h

/*
 * FILENAME: ndarray.h
 *
 *  Structure and function declarations for ndarray.c
 *
 * MACROS:
 *
 * NDARR_RESET_INDICES(ARRAY_INDEX_PTR) 
 *      resets the indices to the origion.
 * NDARR_SET_PADDING(NDARR_SOURCE, char)
 *      sets the padding character.
 * NDARR_GET_SEPARATION(ARRAY_INDEX_PTR, long)
 *      determines what length of separation is necessary after the indexed element.
 * NDARR_GET_MAP_SEPARATION(ARRAY_MAPPING_PTR, long)
 *      determines what length of separation is necessary after the mapping increment
 *      block.
 *
 * CAVEAT:
 * No claims are made as to the suitability of the accompanying
 * source code for any purpose.  Although this source code has been
 * used by the NOAA, no warranty, expressed or implied, is made by
 * NOAA or the United States Government as to the accuracy and
 * functioning of this source code, nor shall the fact of distribution
 * constitute any such endorsement, and no responsibility is assumed
 * by NOAA in connection therewith.  The source code contained
 * within was developed by an agency of the U.S. Government.
 * NOAA's National Geophysical Data Center has no objection to the
 * use of this source code for any purpose since it is not subject to
 * copyright protection in the U.S.  If this source code is incorporated
 * into other software, a statement identifying this source code may be
 * required under 17 U.S.C. 403 to appear with any copyright notice.
 *
 */
 
#ifndef NDARRAY_H__
#define NDARRAY_H__
 
typedef unsigned short NDARR_SOURCE;
 
/***************************
 * Structure declarations: *
 ***************************/
typedef struct array_descriptor_struct{
    char **dim_name;     /* names of each dimension */
    long *start_index;   /* array of dimension starting indices */
    long *end_index;     /* array of dimension ending indices */
    long *granularity;   /* array of dimension granularity */
    long *grouping;      /* array of dimension grouping */
    long *separation;    /* array of dimension speration (by bytes) */
    char *index_dir;     /* array of index directions (down or up) */
    long *dim_size;      /* An array of the size of each dimension */
    long *coeffecient;   /* A number necessary for calculating offsets */
    void *extra_info;    /* An extra pointer *RESERVED!* */
    void *extra_index;   /* A pointer to the groupmap index *RESERVED!* */
    long total_elements; /* the number of elements in the array */
    long num_groups;     /* The number of groups in the array */
    long group_size;   /* The size of an individual group */
    long contig_size;  /* The size, in bytes, of the array contiguous (no separation) */
    long total_size;   /* The size, in bytes, of the whole array */
    long element_size; /* The size of an individual element */
    int num_dim;         /* number of dimensions */
    char type;           /* The type of the array *RESERVED!* */
 
#ifdef ND_FP 
    FILE *fp;
#endif
} ARRAY_DESCRIPTOR, *ARRAY_DESCRIPTOR_PTR;
 
typedef struct array_index_struct{
    ARRAY_DESCRIPTOR_PTR descriptor; /* ptr to array descriptor */
    long *index; /* The indices of the array */
} ARRAY_INDEX, *ARRAY_INDEX_PTR;
 
typedef struct array_mapping_struct{
    ARRAY_DESCRIPTOR_PTR super_array; /* superset of the sub-array */
    ARRAY_DESCRIPTOR_PTR sub_array; /* subset of the super-array */
    int *dim_mapping; /* dimension mapping from sub-array to super-array */
    long *index_mapping; /* index mapping from sub-array to super-array */
    long *gran_mapping; /* Granularity mapping from sub to super array */
    long *gran_div_mapping; /* Granularity mapping from super to sub array */
    long *cacheing; /* For use with ndarr_reorient_to_cache */
    char *index_dir; /* Direction of mapping from sub-array to super-array */
    ARRAY_INDEX_PTR aindex; /* Extra index pointer (for use in calculations)*/
    ARRAY_INDEX_PTR subaindex; /* The current sub-array indices */
    long increment_block; /* size of elements readable at one time */
    long superastart; /* The first offset in superarray for subarray */
    long superaend; /* The last offset in superarray for subarray */
    long subsep; /* the maximum padding length in the sub array */
    int necessary;  /* 0 if mapping is not necessary, !=0 if mapping necessary */
    int dimincrement; /* The lowest unreoriented dimension */
    char fcreated; /* Reserved for use in ndarr_reorient */
} ARRAY_MAPPING, *ARRAY_MAPPING_PTR;
 
/**************************
 * Function declarations: *
 **************************/
ARRAY_DESCRIPTOR_PTR ndarr_create(int numdim);
ARRAY_MAPPING_PTR    ndarr_create_mapping(ARRAY_DESCRIPTOR_PTR subarray,
                            ARRAY_DESCRIPTOR_PTR superarray);
ARRAY_INDEX_PTR      ndarr_create_indices(ARRAY_DESCRIPTOR_PTR arrdesc);
ARRAY_INDEX_PTR      ndarr_increment_indices(ARRAY_INDEX_PTR aindex);
ARRAY_INDEX_PTR      ndarr_increment_mapping(ARRAY_MAPPING_PTR amap);
ARRAY_INDEX_PTR      ndarr_convert_indices(ARRAY_INDEX_PTR aindex,
                            unsigned char direction);
unsigned long        ndarr_get_offset(ARRAY_INDEX_PTR aindex);
unsigned long        ndarr_get_mapped_offset(ARRAY_MAPPING_PTR amap);
void                 ndarr_free_descriptor(ARRAY_DESCRIPTOR_PTR arrdesc);
void                 ndarr_free_indices(ARRAY_INDEX_PTR aindex);
void                 ndarr_free_mapping(ARRAY_MAPPING_PTR amap);
void                *ndarr_get_group(ARRAY_INDEX_PTR aindex);
void                *ndarr_get_next_group(ARRAY_DESCRIPTOR_PTR arrdesc, char mode);
int                  ndarr_do_calculations(ARRAY_DESCRIPTOR_PTR arrd);
int                  ndarr_create_brkn_desc(ARRAY_DESCRIPTOR_PTR adesc, int map_type, void *mapping);
int                  ndarr_set(ARRAY_DESCRIPTOR_PTR arrd, ...);
long                 ndarr_reorient(ARRAY_MAPPING_PTR amap,
                            NDARR_SOURCE sourceid,  void *source,  long source_size,
                            NDARR_SOURCE destid,    void *dest,    long dest_size,
                            int *array_complete);
 
/*************************
 * Preprocessor defines: *
 *************************/
 
/* ndarr_set arguments: */
#define NDARR_DIM_NUMBER      (int)1
#define NDARR_DIM_NAME        (int)2
#define NDARR_DIM_START_INDEX (int)3
#define NDARR_DIM_END_INDEX   (int)4
#define NDARR_DIM_GRANULARITY (int)5
#define NDARR_DIM_GROUPING    (int)6
#define NDARR_DIM_SEPARATION  (int)7
#define NDARR_ELEMENT_SIZE    (int)10
#define NDARR_FILE_GROUPING   (int)20
#define NDARR_BUFFER_GROUPING (int)21
#define NDARR_MAP_IN_BUFFER   (int)22
#define NDARR_MAP_IN_FILE     (int)23
#define NDARR_END_ARGS        (int)0
 
/* ndarr_create_from_str tokens: */
#define NDARR_SB_KEY0 "sb"
#define NDARR_SB_KEY1 "separation"
#define NDARR_GB_KEY0 "gb"
#define NDARR_GB_KEY1 "grouping"
 
/* ndarr_convert_indices arguments */
#define NDARR_USER_TO_REAL 'r'
#define NDARR_REAL_TO_USER 'u'
 
/* Array types */
#define NDARRT_CONTIGUOUS    0
#define NDARRT_BROKEN        1
#define NDARRT_GROUPMAP_FILE 2
#define NDARRT_GROUPMAP_BUFF 3
 
/* ndarr_get_next_group arguments */
#define NDARR_GINITIAL 0
#define NDARR_GNEXT    1
 
/* Define array storage bitfields */
#define NDARRS_FILE    (NDARR_SOURCE)0x8000
#define NDARRS_APPEND  (NDARR_SOURCE)0x4000
#define NDARRS_UPDATE  (NDARR_SOURCE)0x2000
#define NDARRS_CREATE  (NDARR_SOURCE)0x1000
#define NDARRS_BUFFER  (NDARR_SOURCE)0x0800
#define NDARRS_PADDING (NDARR_SOURCE)0x00FF
 
/* If we are under freeform, use freeform's err functions */
/******************
 * Define macros: *
 ******************/
 
/*
 * NAME:    NDARR_RESET_INDICES
 *
 * PURPOSE: To reset an ARRAY_INDEX struct so that its indices are all 0 (the origion)
 *
 * USAGE:   void NDARR_RESET_INDICES(ARRAY_INDEX_PTR aindex)
 *
 * RETURNS: void
 *
 * DESCRIPTION: This is implmented as a macro, due to its extremely small size.
 *
 * SYSTEM DEPENDENT FUNCTIONS: none
 *
 * AUTHOR:      Kevin Frender (kbf@ngdc.noaa.gov)
 *
 * COMMENTS: Implemented as a macro
 *
 * KEYWORDS: array macro
 */
#define NDARR_RESET_INDICES(nda_i_p) {                                           \
    int nda_d_s;                                                                 \
    for(nda_d_s = 0; nda_d_s < nda_i_p->descriptor->num_dim; nda_d_s++)          \
        nda_i_p->index[nda_d_s] = 0;}                                            \
 
/*
 * NAME:    NDARR_SET_PADDING
 *
 * PURPOSE: To set the padding portion of an NDARR_SOURCE type variable.
 *
 * USAGE:   void NDARR_SET_PADDING(NDARR_SOURCE svar, char paddingchar)
 *
 * RETURNS: void
 *
 * DESCRIPTION: This is implmented as a macro, due to its extremely small size.
 *          Sets the padding portion of the NDARR_SOURCE variable to paddingchar.
 *
 * SYSTEM DEPENDENT FUNCTIONS: none
 *
 * AUTHOR:      Kevin Frender (kbf@ngdc.noaa.gov)
 *
 * COMMENTS: Implemented as a macro
 *
 * KEYWORDS: array macro
 */
#define NDARR_SET_PADDING(nda_s_v, pad_c_v) {                                    \
    nda_s_v &= ~NDARRS_PADDING;                                                  \
    nda_s_v |= (NDARRS_PADDING & (pad_c_v * 257));}                              \
 
/*
 * NAME:    NDARR_GET_SEPARATION
 *
 * PURPOSE: To determine the length (in bytes) of the separation to follow the 
 *          element with the given index.
 *
 * USAGE:   void NDARR_GET_SEPARATION(ARRAY_INDEX_PTR aindex, long separation)
 *
 * RETURNS: void, but the separation length (in bytes) is stored in the long
 *          variable argument.
 *
 * DESCRIPTION: This is implmented as a macro, due to its relatively small size,
 *              and possible speed gains from inline code (this macro gets called
 *              frequently inside of big loops)
 *
 *              Determines the number of bytes to come after the element named
 *              in the ARRAY_INDEX_PTR as separation.
 *
 * SYSTEM DEPENDENT FUNCTIONS: none
 *
 * AUTHOR:      Kevin Frender (kbf@ngdc.noaa.gov)
 *
 * COMMENTS: Implemented as a macro
 *
 * KEYWORDS: array macro
 */
#define NDARR_GET_SEPARATION(nda_i_p, nda_l_v) { \
    int nda_t_i; \
    nda_l_v = nda_i_p->descriptor->separation[nda_i_p->descriptor->num_dim - 1]; \
    for(nda_t_i = nda_i_p->descriptor->num_dim - 2; nda_t_i >= 0; nda_t_i--) { \
        if(nda_i_p->descriptor->grouping[nda_t_i + 1]) { \
            if(!((nda_i_p->index[nda_t_i + 1] + 1) % \
                 nda_i_p->descriptor->grouping[nda_t_i + 1])) { \
                nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
                        } \
            else { \
                break; \
                        } \
                } \
        else { \
            if(((nda_i_p->index[nda_t_i + 1] + 1) == \
                nda_i_p->descriptor->dim_size[nda_t_i + 1])) { \
                nda_l_v += nda_i_p->descriptor->separation[nda_t_i]; \
            } \
            else { \
                break; \
                        } \
                } \
    }\
} \
 
 
/*
 * NAME:    NDARR_GET_MAP_SEPARATION
 *
 * PURPOSE: To determine the length (in bytes) of the separation to follow the 
 *          array mapping increment starting with amap->subaindex.
 *
 * USAGE:   void NDARR_GET_MAP_SEPARATION(ARRAY_MAPPING_PTR amap, long separation)
 *
 * RETURNS: void, but the separation length (in bytes) is stored in the long
 *          variable argument.
 *
 * DESCRIPTION: This is implmented as a macro, due to its relatively small size,
 *              and possible speed gains from inline code (this macro gets called
 *              frequently inside of big loops)
 *
 *              Determines the number of bytes to come after the amap->increment_block
 *              whose starting index is specified by amap->subaindex.
 *
 * SYSTEM DEPENDENT FUNCTIONS: none
 *
 * AUTHOR:      Kevin Frender (kbf@ngdc.noaa.gov)
 *
 * COMMENTS: Implemented as a macro
 *
 * KEYWORDS: array macro
 */
#define NDARR_GET_MAP_SEPARATION(nda_m_p, nda_l_v) {                             \
    int nda_t_i;                                                                 \
    ARRAY_INDEX_PTR nda_i_p = nda_m_p->subaindex;                                \
    nda_l_v = nda_i_p->descriptor->separation[nda_m_p->dimincrement];            \
    for(nda_t_i = nda_m_p->dimincrement - 1; nda_t_i >= 0; nda_t_i--)            \
    {                                                                            \
        if(nda_i_p->descriptor->grouping[nda_t_i + 1])                           \
        {                                                                        \
            if(!((nda_i_p->index[nda_t_i + 1] + 1) %                             \
                    nda_i_p->descriptor->grouping[nda_t_i + 1]))                 \
                nda_l_v += nda_i_p->descriptor->separation[nda_t_i];             \
            else                                                                 \
                break;                                                           \
        }                                                                        \
        else                                                                     \
        {                                                                        \
            if(((nda_i_p->index[nda_t_i + 1] + 1) ==                             \
                    nda_i_p->descriptor->dim_size[nda_t_i + 1]))                 \
                nda_l_v += nda_i_p->descriptor->separation[nda_t_i];             \
            else                                                                 \
                break;                                                           \
        }                                                                        \
    }                                                                            \
}
 
/* End of ndarray.h */
 
#include "freeform.h"
 
 
#endif