Issue #194 : Add Andrew's example for using tpie::file_stream

.github/workflows/build_windows.yml

@@ -18,7 +18,7 @@ jobs:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@master
         with:
-          paths: '["tpie/"]'
+          paths: '["tpie/**"]'
 
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip }}

.github/workflows/doxygen.yml

@@ -18,7 +18,7 @@ jobs:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@master
         with:
-          paths: '["tpie/", "doc/"]'
+          paths: '["tpie/**", "doc/**"]'
 
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip }}
@@ -38,8 +38,8 @@ jobs:
     - name: Install C++ project dependencies
       run: sudo apt install libboost-all-dev
 
-    - name: Install Doxygen and TeXLive
-      run: sudo apt install doxygen
+    - name: Install Doxygen, DOT and TeXLive
+      run: sudo apt install doxygen graphviz
 
     # CMake build and create docs
     - name: CMake build

.github/workflows/unit_test.yml

@@ -18,7 +18,7 @@ jobs:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@master
         with:
-          paths: '["tpie/", "test/"]'
+          paths: '["tpie/**", "test/**"]'
 
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip }}

doc/CMakeLists.txt

@@ -35,6 +35,9 @@ configure_file(Doxyfile.in ${DOXYFILE} @ONLY)
 file(READ code/file_stream.inl DOCCODE_FILE_STREAM)
 configure_file(file_stream.dox.in file_stream.dox @ONLY)
 
+file(READ code/file_stream_complete.inl DOCCODE_FILE_STREAM_COMPLETE)
+configure_file(file_stream.dox.in file_stream.dox @ONLY)
+
 file(READ code/fractiondb.inl DOCCODE_FRACTIONDB)
 configure_file(fractiondb.dox.in fractiondb.dox @ONLY)
 

doc/code/file_stream_complete.inl

@@ -0,0 +1,92 @@
+#include <tpie/tpie.h>
+#include <tpie/file_stream.h>
+#include <string>
+
+/* a basic struct storing a 3D segment. */
+struct segment_t {
+	double x1, y1, x2, y2;
+	float z1, z2;
+};
+
+/* Make a dummy segment with given x1,y1, but setting other coordinates to 0. */
+struct segment_t make_segment(double x1, double y1){
+	struct segment_t s;
+	s.x1=x1; s.y1=y1;
+	s.x2=s.y2=s.z1=s.z2=0.f;
+	return s;
+}
+
+/* Print x1, y1 coords of segment. */
+void print_item(const struct segment_t& item){
+  std::cout << "  (" << item.x1 << ", " << item.y1 << ")" << std::endl;
+}
+
+/* Write n segment items to tpie::file_stream with given output file name fname.
+ * Overwrites any previous file. */
+void writestream(const std::string& fname, size_t n){
+
+	tpie::file_stream<struct segment_t> out;
+	out.open(fname, tpie::open::write_only);
+	for(size_t i=0; i<n; i++){
+		struct segment_t item = make_segment(i, i*2.);
+		print_item(item);
+		out.write(item);
+	}
+}
+
+/* Read all segments from a tpie::file_stream with file name given by fname and
+ * prints results. */
+void readstream(const std::string& fname){
+
+	tpie::file_stream<struct segment_t> in;
+	in.open(fname, tpie::open::read_only);
+
+  std::cout << "  size of stream " << in.size() << std::endl;
+
+	while (in.can_read()) {
+		segment_t item = in.read();
+		print_item(item);
+	}
+}
+
+/* Copy infile name to outfile name. Assumes infile is a valid tpie::file_stream
+ * and overwrites outfile. */
+void copystream(const std::string & infile,
+		const std::string & outfile) {
+	tpie::file_stream<struct segment_t> in;
+	tpie::file_stream<struct segment_t> out;
+
+	in.open(infile);
+	out.open(outfile, tpie::open::write_only);
+	while (in.can_read()) {
+		segment_t item = in.read();
+		out.write(item);
+	}
+}
+
+/* Set up TPIE, write to a file, copy to another, read from the latter, and then
+   shut down TPIE again. */
+int main(int /*argc*/, char ** /*argv*/) {
+	size_t memory_limit_mb = 50;
+
+	/* start up TPIE subsystems, set memory limit */
+	tpie::tpie_init();
+	tpie::get_memory_manager().set_limit(memory_limit_mb*1024*1024);
+
+	std::string a = "test.in";
+	std::string b = "test.out";
+
+  std::cout << "Writing '" << a << "'" << std::endl;
+	writestream(a, 10);
+
+  std::cout << std::endl << "Copying '" << a << "' to '" << b << std::endl;
+	copystream(a, b);
+
+  std::cout << std::endl << "Reading '" << b << "'" << std::endl;
+	readstream(b);
+
+	/* wrap up */
+	tpie::tpie_finish();
+
+	return 0;
+}

doc/file_stream.dox.in

@@ -2,8 +2,8 @@
 \page file_stream Reading and writing file streams
 
 The central class in TPIE for reading from files and writing to files is the
-file_stream class. It reads and writes primitives and primitive structures to
-files.
+\ref tpie::file_stream class. It reads and writes primitives and primitive
+structures to files.
 
 \code
 @DOCCODE_FILE_STREAM@
@@ -16,4 +16,19 @@ The main methods of interest are \ref tpie::file_stream::open(),
 By default, \ref tpie::file_stream reads and writes blocks of size 2 MB at a
 time. You can change this by passing a block factor to the constructor of
 file_stream.
+
+TPIE file streams keep track of whether files have been closed \em cleanly, i.e.
+that a file_stream with write access to a file has been given the opportunity to
+close it properly. If a file is not closed properly, e.g. your program crashes
+while still having the stream open, then you will have to manually delete the
+stream files.
+
+\subsection file_stream_complete Complete Examplary Program
+
+Below is a complete C++ program in which the above example of a copy function is
+used.
+
+\code
+@DOCCODE_FILE_STREAM_COMPLETE@
+\endcode
 */