Hint directory support (temp_file) (synesissoftware#46)

* ~ preparatory refactoring

* `xtests::cpp::util::temp_file` : + now supports `hint_dir` parameter, to allow caller to specify temporary directory

* ~ VC++ compatibility

* `xtests::cpp::util::temp_file` : + now supports `hint_dir` parameter on Windows, to allow caller to specify temporary directory

* ~ tidying

Author: mwsis

examples/cpp/example.cpp.temp_file/main.cpp

@@ -1,14 +1,19 @@
 /* /////////////////////////////////////////////////////////////////////////
  * File:    examples/cpp/example.cpp.temp_file/main.cpp
  *
- * Purpose: Example use of `xtests::cpp::util::temp_file`.
+ * Purpose: Example use of `xtests::cpp::util::temp_file`, illustrating:
+ *              - use of various flags, including `DeleteOnOpen`, etc.;
+ *              - use of hint-directory, which overrides the default temp
+ *                directory for a given platform;
+ *              - specifying temporary file's initial contents from an
+ *                array;
  *
  * Created: ... mid 2010s ...
  * Updated: 31st December 2024
  *
  * ////////////////////////////////////////////////////////////////////// */
 
-/** \file example.cpp.temp_file.cpp
+/** \file example.cpp.temp_file/main.cpp
  */
 
 
@@ -22,7 +27,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include <xtests/internal/checked_main.hpp>
+#include <xtests/internal/checked_main.hpp> // wraps the ostensible `main()` in exception handling
 
 
 /* /////////////////////////////////////////////////////////////////////////
@@ -38,25 +43,13 @@ typedef platformstl::filesystem_traits<char>                fs_traits_t;
 
 
 /* /////////////////////////////////////////////////////////////////////////
- * helper functions
+ * helper function declarations
  */
 
 namespace {
 
     fs_traits_t::large_size_type
-    get_file_size(temp_file const& tf)
-    {
-        fs_traits_t::stat_data_type sd;
-
-        if (!fs_traits_t::stat(tf.c_str(), &sd))
-        {
-            return 0;
-        }
-        else
-        {
-            return fs_traits_t::get_file_size(sd);
-        }
-    }
+    get_file_size(temp_file const& tf);
 } // anonymous namespace
 
 
@@ -108,7 +101,7 @@ int main(int argc, char* argv[])
 
     /* Use `None`, which means no special behaviour */
     {
-        std::cout << "temp_file::None :" << std::endl;
+        std::cout << "temp_file::None (without hint directory):" << std::endl;
 
         temp_file tf(temp_file::None);
 
@@ -119,6 +112,19 @@ int main(int argc, char* argv[])
         std::cout << "\tfile-size:\t" << get_file_size(tf) << std::endl;
     }
 
+    /* Use `None`, but in a specific directory */
+    {
+        std::cout << "temp_file::None (with hint directory '" << hint_dir << "'):" << std::endl;
+
+        temp_file tf(temp_file::None, hint_dir);
+
+        std::cout << "\tpath:     \t" << tf << std::endl;
+        std::cout << "\texist?:   \t" << fs_traits_t::file_exists(tf.c_str()) << std::endl;
+        std::cout << "\tfile?:    \t" << fs_traits_t::is_file(tf.c_str()) << std::endl;
+        std::cout << "\tdir?:     \t" << fs_traits_t::is_directory(tf.c_str()) << std::endl;
+        std::cout << "\tfile-size:\t" << get_file_size(tf) << std::endl;
+    }
+
     /* Use `DeleteOnClose`, which causes the file to be deleted when the
      * `temp_file` instance is destroyed
      */
@@ -179,13 +185,49 @@ int main(int argc, char* argv[])
         std::cout << "\tfile-size:\t" << get_file_size(tf) << std::endl;
     }
 
+    /* Specifying some initial contents, but in a specific directory
+     */
+    {
+        std::cout << "some initial contents (with hint directory '" << hint_dir << "') :" << std::endl;
+
+        int const initial_contents[] = { 0, 1, 2, 3, 4, 5, 6, 7 };
+
+        temp_file tf(temp_file::DeleteOnClose | temp_file::EmptyOnOpen, hint_dir, &initial_contents, sizeof(initial_contents));
 
-    ((void)&hint_dir);
+        std::cout << "\tpath:     \t" << tf << std::endl;
+        std::cout << "\texist?:   \t" << fs_traits_t::file_exists(tf.c_str()) << std::endl;
+        std::cout << "\tfile?:    \t" << fs_traits_t::is_file(tf.c_str()) << std::endl;
+        std::cout << "\tdir?:     \t" << fs_traits_t::is_directory(tf.c_str()) << std::endl;
+        std::cout << "\tfile-size:\t" << get_file_size(tf) << std::endl;
+    }
 
 
     return EXIT_SUCCESS;
 }
 
 
+/* /////////////////////////////////////////////////////////////////////////
+ * helper function implementations
+ */
+
+namespace {
+
+    fs_traits_t::large_size_type
+    get_file_size(temp_file const& tf)
+    {
+        fs_traits_t::stat_data_type sd;
+
+        if (!fs_traits_t::stat(tf.c_str(), &sd))
+        {
+            return 0;
+        }
+        else
+        {
+            return fs_traits_t::get_file_size(sd);
+        }
+    }
+} // anonymous namespace
+
+
 /* ///////////////////////////// end of file //////////////////////////// */
 

include/xtests/util/temp_directory.hpp

@@ -4,7 +4,7 @@
  * Purpose: Definition of the temp_directory class.
  *
  * Created: 1st October 2015
- * Updated: 4th December 2024
+ * Updated: 31st December 2024
  *
  * Home:    https://github.com/synesissoftware/xTests/
  *
@@ -51,8 +51,8 @@
 #ifndef XTESTS_DOCUMENTATION_SKIP_SECTION
 # define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_MAJOR    0
 # define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_MINOR    2
-# define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_REVISION 2
-# define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_EDIT     15
+# define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_REVISION 3
+# define XTESTS_VER_XTESTS_UTIL_HPP_TEMP_DIRECTORY_EDIT     17
 #endif /* !XTESTS_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -127,11 +127,11 @@ class temp_directory
 {
 public: // Types
     /// The character type
-    typedef char                            char_type;
+    typedef char                                            char_type;
     /// The size type
-    typedef size_t                          size_type;
+    typedef size_t                                          size_type;
     /// This type
-    typedef temp_directory                  class_type;
+    typedef temp_directory                                  class_type;
 
     /// Flags that control behaviour of ctor and/or dtor
     enum Flags
@@ -146,9 +146,9 @@ class temp_directory
     class could_not_create_temporary_directory_exception;
 
 private:
-    typedef std::basic_string<char_type>                string_type_;
-    typedef platformstl::filesystem_traits<char_type>   fs_traits_type_;
-    typedef fs_traits_type_::file_handle_type           file_handle_type_;
+    typedef std::basic_string<char_type>                    string_type_;
+    typedef platformstl::filesystem_traits<char_type>       fs_traits_type_;
+    typedef fs_traits_type_::file_handle_type               file_handle_type_;
 
 public: // Construction
     /// Establishes an empty temporary file according to the given
@@ -641,14 +641,17 @@ namespace stlsoft
     !defined(STLSOFT_NO_NAMESPACE)
 } /* namespace stlsoft */
 # endif
-
 #endif /* !XTESTS_DOCUMENTATION_SKIP_SECTION */
 
 
 /* /////////////////////////////////////////////////////////////////////////
  * inclusion control
  */
 
+#ifdef STLSOFT_CF_PRAGMA_ONCE_SUPPORT
+# pragma once
+#endif /* STLSOFT_CF_PRAGMA_ONCE_SUPPORT */
+
 #endif /* XTESTS_INCL_XTESTS_UTIL_HPP_TEMP_DIRECTORY */
 
 /* ///////////////////////////// end of file //////////////////////////// */