path_tools : AsPath, TryIntoPath, TryIntoCowPath

Author: Wandalen

module/core/proper_path_tools/Cargo.toml

@@ -35,6 +35,8 @@ full = [
   "path_utf8",
 ]
 no_std = []
+# qqq : xxx : negate no_std
+# use_std = []
 use_alloc = [ "no_std" ]
 enabled = [ "mod_interface/enabled" ]
 

module/core/proper_path_tools/Readme.md

@@ -9,6 +9,22 @@ Collection of algorithms and structures to handle paths properly.
 
 All functions in the crate don't touch file system, but only process paths.
 
+### Type `AbsolutePath`
+
+The AbsolutePath type ensures that paths are absolute, which helps reduce issues and maintenance costs associated with relative paths. Relative paths can be problematic as they introduce additional variables and complexities, making code analysis, integration, refactoring, and testing more difficult. By using absolute paths, software architecture can be improved, similar to how avoiding global variables can enhance code quality. It is recommended to use relative paths only at the outskirts of an application.
+
+### Trait `AsPath`
+
+This trait is used to avoid redundant allocation of memory by providing a reference to a Path. It is implemented only for types that can either be referenced or are references to Path itself. Unlike `TryIntoPath`, it does not allocate memory on the heap. However, `TryIntoPath` is implemented for a wider range of types because it is not restricted from allocating memory. Unlike `AsRef< Path >`, `AsPath` is implemented for a wider number of types, including those that are not directly convertible to a Path using `AsRef`. This is because `AsPath` is designed to provide a more flexible interface for path-like types, accommodating various representations that can logically be treated as paths.
+
+### Trait `TryIntoPath`
+
+This trait is used to convert any path-like type into an owned PathBuf. Unlike `TryIntoCowPath`, it always returns an owned PathBuf, so there is no need to differentiate between borrowed and owned paths at runtime. Unlike `AsPath`, it is implemented for a wider range of path-like types, similar to `TryIntoCowPath`.
+
+### Trait `TryIntoCowPath`
+
+This trait is designed to avoid redundant memory allocation. Unlike TryIntoPath, it does not allocate memory on the heap if it’s not necessary. Unlike `AsPath`, it is implemented for a wider number of path-like types, similar to TryIntoPath. The drawback is the necessity to differentiate borrowed and owned paths at runtime.
+
 <!-- ### Basic use-case
 
 ```rust

module/core/proper_path_tools/src/as_path.rs

@@ -0,0 +1,71 @@
+/// Internal namespace.
+mod private
+{
+  // use crate::*;
+  #[cfg( feature = "no_std" )]
+  extern crate std;
+
+  use std::path::Path;
+  use camino::Utf8Path;
+
+  /// A trait for converting various types into a reference to a `Path`.
+  ///
+  /// This trait is used to avoid redundant allocation of memory by providing a reference to a `Path`.
+  /// It is implemented only for types that can either be referenced or are references to `Path` itself.
+  /// Unlike `TryIntoPath`, it does not allocate memory on the heap. However, `TryIntoPath` is implemented for a wider range of types because it is not restricted from allocating memory.
+  /// Unlike `AsRef<Path>`, `AsPath` is implemented for a wider number of types, including those that are not directly convertible to a `Path` using `AsRef`.
+  /// This is because `AsPath` is designed to provide a more flexible interface for path-like types, accommodating various representations that can logically be treated as paths.
+  pub trait AsPath
+  {
+    /// Converts the implementing type into a reference to a `Path`.
+    ///
+    /// # Returns
+    ///
+    /// A reference to a `Path`.
+    fn as_path( &self ) -> &Path;
+  }
+
+  /// Implementation of `AsPath` for `str`.
+  impl AsPath for str
+  {
+    fn as_path( &self ) -> &Path
+    {
+      Path::new( self )
+    }
+  }
+
+  /// Implementation of `AsPath` for `Path`.
+  impl AsPath for Path
+  {
+    fn as_path( &self ) -> &Path
+    {
+      self
+    }
+  }
+
+  /// Implementation of `AsPath` for `Utf8Path`.
+  #[cfg( feature = "path_utf8" )]
+  impl AsPath for Utf8Path
+  {
+    fn as_path( &self ) -> &Path
+    {
+      self.as_std_path()
+    }
+  }
+
+  /// Blanket implementation of `AsPath` for all types that implement `AsRef<Path>`.
+  impl< T > AsPath for T
+  where
+    T : AsRef< Path >,
+  {
+    fn as_path( &self ) -> &Path
+    {
+      self.as_ref()
+    }
+  }
+}
+
+crate::mod_interface!
+{
+  orphan use AsPath;
+}

module/core/proper_path_tools/src/lib.rs

@@ -20,12 +20,21 @@ mod_interface!
   /// Basic functionality.
   layer path;
 
+  /// AsPath trait.
+  layer as_path;
+  /// TryIntoPath trait.
+  layer try_into_path;
+  /// TryIntoPath trait.
+  layer try_into_cow_path;
+
   /// Transitive TryFrom and TryInto.
   layer transitive;
 
   #[ cfg( feature = "path_utf8" ) ]
   own use ::camino::{ Utf8Path, Utf8PathBuf };
   #[ cfg( not( feature = "no_std" ) ) ]
-  own use ::std::path::{ PathBuf, Path };
+  own use ::std::path::{ PathBuf, Path, Component };
+  #[ cfg( not( feature = "no_std" ) ) ]
+  own use ::std::borrow::Cow;
 
 }

module/core/proper_path_tools/src/path.rs

@@ -2,6 +2,8 @@
 
 mod private
 {
+  use crate::*;
+
   #[ cfg( feature = "no_std" ) ]
   extern crate std;
 
@@ -321,11 +323,10 @@ mod private
   ///
   /// ```
   // qqq : make macro paths_join!( ... )
-  pub fn join_paths< 'a, I >( paths : I ) -> std::path::PathBuf
+  pub fn join_paths< I, P >( paths : I ) -> PathBuf
   where
-    // AsPath : AsRef< std::path::Path >,
-    // I : Iterator< Item = AsPath >,
-    I : Iterator< Item = &'a std::path::Path >,
+    I : Iterator< Item = P >,
+    P : AsPath,
   {
     #[ cfg( feature = "no_std" ) ]
     extern crate alloc;
@@ -338,8 +339,11 @@ mod private
 
     for path in paths
     {
-      let mut path = path.to_string_lossy().replace( '\\', "/" );
-      path = path.replace( ':', "" );
+      // let mut path = path.to_string_lossy().replace( '\\', "/" );
+      let path = path.as_path().to_string_lossy().replace( '\\', "/" );
+      // qqq : xxx : avoid converting to String, keep it Path
+
+      // path = path.replace( ':', "" );
       // qqq : this is a bug
 
       let mut added_slah = false;
@@ -1072,4 +1076,7 @@ crate::mod_interface!
   /// Describe native path. Use to pass path to the platfrom.
   layer native_path;
 
+  /// Convenient joining.
+  layer join;
+
 }