blc_array.h 10 KB
Newer Older
Arnaud Blanchard's avatar
Arnaud Blanchard committed
1
2
/* Basic Library for C/C++ (blclib)
 Copyright  ETIS — ENSEA, Université de Cergy-Pontoise, CNRS (2011 - 2014)
3
 
Arnaud Blanchard's avatar
Arnaud Blanchard committed
4
 Author: A. Blanchard
5
 
Arnaud Blanchard's avatar
Arnaud Blanchard committed
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 This software is a computer program whose purpose is to simulate neural networks and control robots or simulations.
 This software is governed by the CeCILL v2.1 license under French law and abiding by the rules of distribution of free software.
 You can use, modify and/ or redistribute the software under the terms of the CeCILL v2.1 license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".
 As a counterpart to the access to the source code and  rights to copy, modify and redistribute granted by the license,
  users are provided only with a limited warranty and the software's author, the holder of the economic rights,  and the successive licensors have only limited liability.
  In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software,
  that may mean  that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge.
 Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured
  and, more generally, to use and operate it in the same conditions as regards security.
  The fact that you are presently reading this means that you have had knowledge of the CeCILL v2.1 license and that you accept its terms. */

#ifndef BLC_ARRAY_H
#define BLC_ARRAY_H

#include "blc_tools.h"
#include "blc_mem.h"

23
24
25
26
27
28
29
/**
 @defgroup blc_array blc_array
 @{
 @brief blc_mem with more informations about type, format and structures (dimensions) of the data.
 */

/**Like EXIT_ON_ERROR but displays all the informations about the array on stderr before quitting. Useful to debug.*/
Arnaud Blanchard's avatar
Arnaud Blanchard committed
30
31
#define EXIT_ON_ARRAY_ERROR(array, ...) blc_array_fatal_error(array, __FILE__, __FUNCTION__, __LINE__, __VA_ARGS__)

32
///Description of a dimension properties of a blc_array.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
33
typedef struct blc_dim {
34
35
    size_t length; ///<number of element for the dimension
    size_t step; ///< shift in bytes to do to pass from one element of this dimension to the next one
Arnaud Blanchard's avatar
Arnaud Blanchard committed
36
37
} blc_dim;

38
39
40
41
42
START_EXTERN_C
blc_dim *vcreate_blc_dims(size_t *size, uint32_t type, int dims_nb, int length, va_list arguments);

blc_dim *create_blc_dims(size_t *size, uint32_t type, int dims_nb, int length0, ...);
END_EXTERN_C
43
44

///Description of a n-dimensional array with type and format
Arnaud Blanchard's avatar
Arnaud Blanchard committed
45
46
typedef struct blc_array
#ifdef __cplusplus
47
:blc_mem {
48
49
    
    /**Define an empty array*/
50
    blc_array();
51
52
    /**Define and allocates the array */
    blc_array(uint32_t type, uint32_t format, int dims_nb, int length0, ...);
53
    /**Free dims. The data is freed by ~blc_mem()*/
54
55
    ~blc_array();
    
56
57
/* Definiting the array without allocation. Useful when you want to use external buffer
 ====================================================================================*/
58
    
59
    /**Defines the blc_array but does not allocate memory (data)*/
60
    void vdef_array(uint32_t type, uint32_t format, int dims_nb, int length0, va_list arguments);
61
    /**Defines the blc_array but does not allocate memory (data)*/
62
    void def_array(uint32_t type, uint32_t format, int dims_nb, int length0, ...);
63
    /**Defines the blc_array but does not allocate memory (data)*/
Arnaud Blanchard's avatar
Arnaud Blanchard committed
64
    void def_array(uint32_t type, uint32_t format, int dims_nb, blc_dim const *dims);
65
    /**Defines the blc_array but does not allocate memory (data)*/
66
67
    void def_array(uint32_t type, uint32_t format, char const *dims_string);
    
68
69
70
71
72
    
/* Allocating the array
 ====================*/
    
    /**Defines and allocates the blc_array with a string (i.e. "UIN8 RGB3 3x800x600")*/
73
    void init(char const *properties);
74
    /**Defines and allocates the blc_array */
75
    void vinit(uint32_t type, uint32_t format, int dims_nb, int length, va_list arguments);
76
    /**Defines and allocates the blc_array */
77
    void init(uint32_t type, uint32_t format, int dims_nb, int length0, ...);
78
    
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
/* Printing informations about the blc_array
==========================================*/
    
    /**Print the properties of the dims in a string (i.e. "3x800x600" )*/
    int sprint_dims(char *string, int max_string_size);
    /**Print the properties of the dims in a file or stderr by default (i.e. "3x800x600" )*/
    int fprint_dims(FILE *file=stderr) const;
    /**Print all the informations about the blc_array. Useful for debuging.*/
    void fprint_debug(FILE *file=stderr) const;
    /**Print all the properties of the array in a string (i.e. "UIN8 RGB3 3x800x600")*/
    void sprint_properties(char *string, size_t max_string_size);
    /**Print all the properties of the array in a file or stderr by default. (i.e. "UIN8 RGB3 3x800x600")*/
    void fprint_properties(FILE *file=stderr);
    
/* Modifying the properties of the array
======================================*/

    /**Add one dimention to the definition of the blc_array. You have to  manage  eventual **memory reallocation** yourself.*/
97
    void add_dim(int length, int step);
98
    /**Add one dimension ti the definition of the blc_array. The step is infered from the type of the data and the size of the previous dimension. You have to manage the eventual **memory reallocation** yourself.*/
99
    void add_dim(int length);
100
    /** Set all the dims of the array*/
101
    void set_dims(int dims_nb, int length, ...);
102
103
104
    /**Set all dims by reading the properties from the string  (i.e. "3x800x600" ).  You have to  manage  eventual **memory reallocation** yourself. */
    int sscan_dims(char const* string);
    /**Set all dims by reading the properties from the file  (i.e. "3x800x600" ).  You have to  manage  eventual **memory reallocation** yourself. */
105
    void fscan_dims(FILE *file);
106
    /**Set all properties by reading the properties from the string  (i.e. "UIN8 RGB3 3x800x600" ).  You have to  manage  eventual **memory reallocation** yourself. */
107
    void sscan_properties(char const *string);
108
    /**Set all properties by reading the properties from the file  (i.e. "UIN8 RGB3 3x800x600" ).  You have to  manage  eventual **memory reallocation** yourself. */
109
    void fscan_properties(FILE *file);
110
111
112
113
   // size_t get_minimum_size();

/*Reading data from files
 ======================*/
114
    
115
    /**Defines the array without allocating the data by reading the file with .blc extension*/
116
    void def_with_blc_file(char const *filename);
117
    /**Defines and allocates the blc_array depending on the description of the blc file (with .blc extension) but does not update the data. This allow you to refresh data without reallocating memory.*/
118
    void init_with_blc_file(char const *filename);
119
    /**Update the content of the memory with the content of the blc file. The blc_array has to be properly defined and allocated before. .blc format is a specific format, whre de first line is the properties of the blc_array and them it is raw binary memory. It may be a problem with endianness */
120
    void update_with_blc_file(char const *filename);
121
122

    void def_with_tsv_file(char const *filename);
123
    /**Same as update_with_blc_file but this reas .tsv, tab separated values (i.e. 0.75     0.33    0.55    ). Typically used with excel and similar. You have to care yourself to define and allocate an appropriate blc_array.*/
124
    void update_with_tsv_file(char const *filename);
125
126
127

/*Writing data in files
=====================*/
128
    
129
130
131
132
133
134
135
    /**Create a .blc file with the content of the blc_array. This is meant to be used with init_with_blc_file, update_with_blc_file.*/
    void save_blc_file(char const *filename);
    /**Write the content of the blc_array as TSV (tab separated values) in a file. It can also be used to write on the terminal.*/    
    void fprint_tsv(FILE *file=stderr);
    /**Comme fprint_tsv but automtically create the file. With filename which must have .tsv extension.*/
    void save_tsv_file(char const *filename);
    /**Print the blc_array as a text_graph surface. Only works with 2D blc_array of type 'UIN8'. It draws a matrix of values. If ansi terminal is 1, it draws colored valuse depending on the blc_uchar_color_scale.*/
136
    void fprint_surface_uchars(FILE *file, int ansi_terminal=0);
137
138
139
140
141
142
143

/*miscellaneous
=============*/
    
    /**Return the size in bytes of one element depending on the type of data of the blc_array*/
    int get_type_size();
    
Arnaud Blanchard's avatar
Arnaud Blanchard committed
144
#else
145
    {
146
        blc_mem mem; ///< raw memory of the array
Arnaud Blanchard's avatar
Arnaud Blanchard committed
147
#endif
148
149
        uint32_t type; ///< type of data in the memory as a unsigned int of 4 bytes. Possibilities are 'UIN8' uchar, 'INT8' char, 'UI16' uint16_t, 'IN16' int16_t, 'UI32' uint32_t, 'IN32' int32_t, 'FL32' float, 'FL64' double
        uint32_t format; ///< describes how the data should be interpreted. 'NDEF' (no specification), 'TEXT' for strings, 'Y800' black and white image, 'RGB3' image in RGB, 'LPCM' sound in non compressed format, ...
150
151
        blc_dim * dims; ///< array of dimentions of the blc_array
        int dims_nb; ///< number of dimension of the blc_array
152
        size_t total_length; ///<Total number of elements in the array. This differ of size if an element is bigger than one byte.
153
154
    } blc_array;
    
155
156
157
/*Plain C functions ( work also with C++)
===============================*********/
    
158
    START_EXTERN_C
159
160
161
162
163
    /**Define but does not allocate the blc_array.*/
    void blc_array_def(blc_array *blc_array,  uint32_t type, uint32_t format, int dims_nb, int length0, ...);
    /**Define and allocate the blc_array*/
    void blc_array_init(blc_array *blc_array,  uint32_t type, uint32_t format, int dims_nb, int length0, ...);
    /** like blc_fatal_error but add informations about the blc_array.  You should not call it, it is called by EXIT_ON_ARRAY_ERROR*/
164
    void blc_array_fatal_error(blc_array const *array, const char *name_of_file, const char* name_of_function, int numero_of_line, const char *message, ...);
165
    /**Free the dims description and data if not null of the array*/
166
167
    void blc_array_destroy(blc_array *array);
    END_EXTERN_C
168

169
    ///@}
Arnaud Blanchard's avatar
Arnaud Blanchard committed
170
#endif
171