Examples/C-examples.md

+# Introduction
+Here we present and describe the examples included in the [w-data library](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples).
+
+In order to compile examples (optionally you will need to modify Makefile):  
+```bash
+[wtools@dell ~]$ cd wdata
+[wtools@dell wdata]$ make examples
+```
+Folder [wdata](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/) contains library that provides support for w-data processing.  
+List of examples demonstrating how to use this library are presented below. One can see more detailed descritption of each of it in [Examples](Examples/Examples)
+* [example-write.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples/example-write.c): code creates artificial set of variables and writes them to wdat files.
+* [example-write-many.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples/example-write-many.c): code creates artificial set of variables and writes them do wdat files. The differnence between the above is the non repeating parts of the code, however it introduces some limitations.
+* [example-write-many-t_varying.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples/example-write-many-t_varying.c): code creates artificial set of variables and writes them do wdat files.
+* [example-read.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples/example-read.c):  code reads data from wdat files (created by [example-write.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/example-write.c)).  
+* [example-addvar.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/c-examples/example-addvar.c):  code adds new variable to existing data set (created by [example-write.c](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/tree/master/example-write.c)).  
+
+# Low-level reading and writing of data
+## Reading
+Code snippet demonstrating how to load datablock from `wdat` file:  
+```c
+double *dataR; // pointer to real data
+int cycleid;  // id of cycle for loading 
+
+char file_name[128]="test_density_a.wdat";
+
+FILE *pFile;
+
+pFile= fopen (file_name, "rb"); // open file in `read` and `binary` mode
+if(pFile==NULL) 
+    printf("ERROR: Cannot open file\n");   
+    
+// set pointer to correct location
+size_t blocklength = nx*ny*nz;  // for datadim=3
+size_t blocksize = blocklength*sizeof(double); // for real variable
+size_t ptr_shift = 0;
+// in case of other formats, like npy:
+// ptr_shift += size_of_header; // skip header
+ptr_shift += blocksize*cycleid; // set pointer to correct location
+if(fseek(pFile, ptr_shift, SEEK_SET) != 0)
+    printf("ERROR: Cannot set pointer to datablock\n");
+
+size_t test_ele = fread(data, blocksize, 1, pFile); // read datablock
+if(test_ele != 1)
+    printf("ERROR: Cannot read datablock\n");
+
+fclose(pFile); // close file
+```
+
+The above code demonstrates the idea behind the library, however we want to introduce some abstraction, and the code that uses the library function looks like that:
+```c
+double *dataR;  // pointer to real data
+int cycleid; // id of cycle to be loaded
+
+wdata_metadata md; // WData metadata struct
+
+wdata_parse_metadata_file("test.wtxt", &md); // parse the metadata `*wtxt` file
+
+wdata_read_cycle(&md, "dataR", cycleid, dataR); // read the block of the code
+```
+
+## Writing
+```c
+double *dataR; // pointer to real data
+ 
+char file_name[128] = "test_density_a.wdat";
+
+FILE *pFile;
+
+pFile = fopen (file_name, "ab"); // open file 
+if(pFile==NULL)
+    printf("ERROR: Cannot open file\n");
+      
+size_t blocklength = nx*ny*nz;                         // for datadim=3
+size_t blocksize = blocklength*sizeof(double);         // for real variable
+size_t test_ele = fwrite (dataR, blocksize, 1, pFile); // add datablock
+if(test_ele != 1)
+    printf("ERROR: Cannot add datablock\n");
+
+// in case of other formats, like npy, additional change of header is required.
+//    ...
+
+fclose(pFile); // close file
+```
+
+Using WData library:
+```c
+double *dataR;  // real data
+
+wdata_metadata md; // WData metadata struct
+
+wdata_write_cycle(&md, "density_a", dataR);
+```
\ No newline at end of file