spirit-code / ovf

OVF (OOMMF Vector Field file format) parser library with C API and language bindings
MIT License
8 stars 2 forks source link

Design a minimalistic API #1

Closed GPMueller closed 6 years ago

GPMueller commented 6 years ago

The following guide gives a very good intro to minimalistic C API Design http://nullprogram.com/blog/2018/06/10/ I believe most of the suggestions cannot be realized with the complexity of OVF file parsing

My first suggestion:

/* return codes */
#define OVF_OK          -1
#define OVF_INVALID     -2

/* the geometrical information on the vector field */
struct ovf_geometry {
    int n_cells[3];
    int N;

    float bounds_min[3];
    float bounds_max[3];

    /* then some "private" internal fields */
};

/* all header info on a segment */
struct ovf_segment {
    char *title;
    char *meshunits;
    int valuedim;
    char *valueunits;
    char *valuelabels;
    char *meshtype;

    /* then some "private" internal fields */
};

/* opaque handle which holds the file pointer */
struct ovf_file_handle;

/* the main struct which keeps the info on the main header of a file */
struct ovf_file {
    /* file could be found */
    bool found;
    /* file contains an ovf header */
    bool is_ovf;
    /* number of segments the file should contain */
    int n_segments;

    /* then some "private" internal fields */
    struct ovf_file_handle _file;
};

/* opening a file will fill the struct and prepare everything for read/write */
void ovf_open(struct ovf_file *, const char *filename);
/* reading a segment will write the data, if present, into the buffer.
    The ordering of the data will depend on the specification of the geometry.
    It will also check the file against the expected geometry.
    The ovf_file will be filled with the information from the segment header. */
int  ovf_read_segment(struct ovf_file *, int index, const struct ovf_geometry *expected, struct ovf_segment *segment, float *data);
int  ovf_read_segment(struct ovf_file *, int index, const struct ovf_geometry *expected, struct ovf_segment *segment, double *data);
/* write a segment to the file, overwriting all contents. The new header will have segment count = 1 */
int  ovf_write_segment(struct ovf_file *, long codepoint);
/* append a segment to the file. The segment count will be incremented */
int  ovf_append_segment(struct ovf_file *, long codepoint);
/* close the file and clean up resources */
long ovf_close(struct ovf_file *);
GPMueller commented 6 years ago

With the v0.1.0 release (ca5e6a62caed4143c61cc2aab0712808360601fc), the initial version of the API has been created. For now it should do OK.