#ifndef float_array_H
#define float_array_H

/* Multi-dimensional arrays with floating-point elements. */
/* Last edited on 2009-08-31 11:16:14 by stolfi */ 

#include <stdio.h>
#include <bool.h>
#include <indexing.h>
#include <indexing_descr.h>

#define float_array_MAX_AXES ix_descr_MAX_AXES
  /* Number of indices (dimensions, axes) in any array. Lower-dimensional
    arrays are obtained by setting the size to 1 along the unwanted axes. */

/* ARRAY DESCRIPTOR */

typedef struct float_array_t 
  { ix_descr_t ds;   /* Array sizes and indexing formula. */         
    float *el;       /* Start of storage area (NULL if no elements). */
  } float_array_t; 
  /* The element for an index tuple {ix[0..NA-1]} is stored in
    {el[p]} where {p = ix_descr_pos(ds, ix)}.  See {indexing_descr.h}
    for more details. */

/* DESCRIPTOR ALLOCATION */

float_array_t float_array_new ( ix_dim_t na, ix_size_t sz[], ix_order_t ixor );
  /* Allocates a new multidimensional {float} array with size {sz[i]}
    along axis {i}, for {i} in {0..NA-1}. 
    
    The elements are stored in consecutive positions, in the order
    specified by {ixor}.  Namely, if {ixor = ix_order_F}, the
    /first/ index varies fastest (as in Fortran); if {ixor = ix_order_L},
    the /last/ index varies fastest (as in C and Pascal). */

void float_array_free_elems ( float_array_t *A );
  /* Reclaims the element storage area {A.el} and sets {A.el = NULL}.  
    Does *not* reclaim the descriptor record {A}. */

/* DESCRIPTOR ALLOCATION */

float_array_t *float_array_new_descr ( void );
  /* Allocates a new descriptor record, with uninitialized indexing formula,
    and {el = NULL}. */

float_array_t *float_array_copy_descr ( float_array_t *A );
  /* Allocates a new descriptor records, and copies into it the
    contents of descriptor {A}, including the {el} pointer.
    Thus, the resuting array with share its elements with {A}. */

void float_array_free_descr ( float_array_t *A );
  /* Discards the descriptor of array {A} (but not the element storage
    area {A.el}). */

/* ACESSING INDIVIDUAL ELEMENTS */

float float_array_get_element ( float_array_t *A, ix_index_t ix[] );
  /* Returns the element of {A} with indices {ix[0..NA-1]}. */

float *float_array_get_element_address ( float_array_t *A, ix_index_t ix[] );
  /* Returns the address of the element of array {A} with indices {ix[0..NA-1]}. */

void float_array_set_element ( float_array_t *A, ix_index_t ix[], float v );
  /* Stores {v} into the element of array {A} with indices {ix[0..NA-1]}. */

/* GET/CHECK SIZE */
  
void float_array_get_size ( float_array_t *A, ix_size_t sz[] );
  /* Stores the size of {A} along axis {i} into {sz[i]},
    for {i} in {0..NA-1}. */
  
void float_array_check_size ( float_array_t *A, ix_size_t sz[] );
  /* Fails if the {A} does not have size {sz[i]} along axis {i},
    for any {i} in {0..NA-1}. */

/* INPUT/OUTPUT */

void float_array_write(FILE *wr, float_array_t *A, ix_order_t ixor);
  /* Writes the array {A} to {wr}, in ASCII floating point format. The
    file will start with a standard header line "begin float_array_t
    (version {DATE})", followed by two lines with "axes = {d}" and
    "size = {A.sz[0]} {A.sz[1]} ... {A.sz[d-1]}", where {d} is the largest
    integer such that {A.sz[d-1] > 1}.
    
    Then follow the array elements, one per line, in the format
    "{ix[0]} {ix[1]} ... {ix[d-1]} {ELEMENT}", in the order specified
    by {ixor}. For all elements except the first one, if the last {k}
    indices are zero, the line is preceded by {k} blank lines. The
    file ends with a footer "end float_array_t". */

float_array_t float_array_read(FILE *rd);
  /* Reads an array from {rd}, in ASCII floating point format
    generated by {float_array_write}. */

#undef NA
  /* External clients should use {float_array_MAX_AXES}. */

#endif