Utility: deprecate Directory in favor of a new Path namespace.

Started as an optimistic task of porting away from std::string, ended up
being a full redesign to fix other outstanding issues like a lack of
clearly distinguishable failure states for most of the APIs.

I tried to make the sweeping changes in-place at first, but it proved to
be a backwards compatibility hell that would make everyone angry. So
instead it's a whole new namespace and I took that as an opportunity to
also fix various naming issues.

The Directory namespace is now implemented in terms of the Path
functionality and isn't really any slower than it was before. On the
other hand, thanks to string views there's no useless string allocations
anymore and Path::readString() can now take over the memory ownership
coming from read(), being no longer 2x slower.

While all Directory APIs are marked as deprecated, existing code is not
updated yet, only the DirectoryTest failure message tests to make the
test still pass. Updating to the new APIs will be done in next commits.

CMakeLists.txt

@@ -284,7 +284,7 @@ set(CORRADE_VERSION_MONTH 6)
 #   all plugins are put into the same place, so PluginManager has a single
 #   place to look into; and thanks to the dynamic libraries being there as
 #   well, this location can be automagically detected as relative to
-#   Directory::libraryLocation().
+#   Utility::Path::libraryLocation().
 # - Thanks to the $<CONFIG> being part of the output path, you are always sure
 #   you never accidentally mix up debug/release libraries when switching
 #   CMAKE_BUILD_TYPE in an existing build dir.

doc/corrade-changelog-old.dox

@@ -239,12 +239,13 @@ a high-level overview.
     used
 -   Added @ref Utility::Fatal output. Similar to @ref Utility::Error but exits
     with defined return code right after printing the message.
--   Added @ref Utility::Directory::isSandboxed(),
-    @ref Utility::Directory::executableLocation(), @ref Utility::Directory::tmp(),
-    @ref Utility::Directory::fromNativeSeparators() and
-    @ref Utility::Directory::toNativeSeparators()
--   Added @ref Utility::Directory::map() and @ref Utility::mapRead() for
-    mapping files into memory, works on non-RT Windows and all Unix-like
+-   Added @cpp Utility::Directory::isSandboxed() @ce,
+    @cpp Utility::Directory::executableLocation() @ce,
+    @cpp Utility::Directory::tmp() @ce,
+    @cpp Utility::Directory::fromNativeSeparators() @ce and
+    @cpp Utility::Directory::toNativeSeparators() @ce
+-   Added @cpp Utility::Directory::map() @ce and @cpp Utility::mapRead() @ce
+    for mapping files into memory, works on non-RT Windows and all Unix-like
     systems (see [mosra/corrade#27](https://github.com/mosra/corrade/pull/27))
 -   Added @ref Utility::Resource::hasGroup()
 -   Added @ref Utility::Unicode::prevChar(), @ref Utility::Unicode::utf8()
@@ -300,10 +301,10 @@ a high-level overview.
     consistently on all platforms
 -   Ensuring that floating-point values printed by @ref Utility::Debug have
     enough digits of precision based on their type
--   All @ref Utility::Directory functions now properly take and return UTF-8
-    encoded paths on Windows (see [mosra/corrade#31](https://github.com/mosra/corrade/issues/31))
--   Implemented @ref Utility::Directory::configurationDir() and
-    @ref Utility::Directory::home() on Emscripten, OSX and iOS with proper
+-   All @cpp Utility::Directory @ce functions now properly take and return
+    UTF-8 encoded paths on Windows (see [mosra/corrade#31](https://github.com/mosra/corrade/issues/31))
+-   Implemented @cpp Utility::Directory::configurationDir() @ce and
+    @cpp Utility::Directory::home() @ce on Emscripten, OSX and iOS with proper
     handling of sandboxed apps (see [mosra/corrade#6](https://github.com/mosra/corrade/issues/6))
 -   @ref Utility::Resource and @ref corrade-cmake-add-resource "corrade_add_resource()"
     CMake macro now properly handle UTF-8 filenames on all platforms
@@ -362,9 +363,9 @@ a high-level overview.
     for named arguments
 -   Prefixed @ref Utility::Arguments failed on encountering value starting with
     `-`
--   @ref Utility::Directory::mkpath() now properly returns @cpp false @ce if
-    path creation fails
--   Fixed @ref Utility::Directory::rm() for directories on Emscripten
+-   @cpp Utility::Directory::mkpath() @ce now properly returns @cpp false @ce
+    if path creation fails
+-   Fixed @cpp Utility::Directory::rm() @ce for directories on Emscripten
 -   Fixed unaligned reads and iterative digesting in @ref Utility::Sha1
 -   Properly re-running CMake and updating dependencies when resource
     configuration file added by @ref corrade-cmake-add-resource "corrade_add_resource()"

doc/corrade-changelog.dox

@@ -199,26 +199,25 @@ namespace Corrade {
     compilers
 -   @ref Utility::Debug now accepts also a C++17 @ref std::string_view if
     you include @ref Corrade/Utility/DebugStlStringView.h
--   Improved error handling in @ref Utility::Directory APIs where all APIs now
+-   Improved error handling in @ref Utility::Path APIs where all APIs now
     consistently print an error code and message coming from the system on
     failure instead of a generic message or nothing at all
--   @ref Utility::Directory::isDirectory() now follows symlinks on Unix
-    platforms
--   @ref Utility::Directory::Flag::SkipFiles and
-    @ref Utility::Directory::Flag::SkipDirectories passed to
-    @ref Utility::Directory::list() now affects symlinks as well --- previously
-    they were treated as neither, now they get correctly skipped based on
-    whether the target is a file or a directory
--   @ref Utility::Directory::Flag::SkipSpecial passed to
-    @ref Utility::Directory::list() now has no effect on Emscripten, the same
+-   @ref Utility::Path::isDirectory() now follows symlinks on Unix platforms
+-   @ref Utility::Path::ListFlag::SkipFiles and
+    @ref Utility::Path::ListFlag::SkipDirectories passed to
+    @ref Utility::Path::list() now affects symlinks as well --- previously they
+    were treated as neither, now they get correctly skipped based on whether
+    the target is a file or a directory
+-   @ref Utility::Path::ListFlag::SkipSpecial passed to
+    @ref Utility::Path::list() now has no effect on Emscripten, the same
     as on Windows, as those two platforms have no notion of a special file.
     Previously this behaved equivalently to
-    @ref Utility::Directory::Flag::SkipFiles on Emscripten but that made no
+    @ref Utility::Path::ListFlag::SkipFiles on Emscripten but that made no
     sense from a portability point of view.
--   @ref Utility::Directory::fileSize(), @relativeref{Utility::Directory,read()},
-    and @relativeref{Utility::Directory,copy()} now explicitly check if the
-    path is a directory and fail in that case, instead of returning nonsense,
-    crashing on an allocation failure or silently doing the wrong thing
+-   @ref Utility::Path::size(), @relativeref{Utility::Path,read()} and
+    @relativeref{Utility::Path,copy()} now explicitly check if the path is a
+    directory and fail in that case, instead of returning nonsense, crashing on
+    an allocation failure or silently doing the wrong thing
 -   @ref Utility::format() now supports printing integers as characters using
     the @cpp "{:c}" @ce modifier
 -   @ref Utility::format() now accepts also a C++17 @ref std::string_view if
@@ -228,8 +227,8 @@ namespace Corrade {
     @ref Containers::StringView overloads that allocate much less
 -   Ability to print @ref Containers::BasicStringView and
     @ref Containers::String using @ref Utility::format()
--   Creating an empty path with @ref Utility::Directory::mkpath() now succeeds
-    because it makes no sense to fail for such case
+-   Creating an empty path with @ref Utility::Path::make() now succeeds because
+    it makes no sense to fail for such case
 -   @ref Utility::IsStringLike now recognizes also C++17 @ref std::string_view
     by checking for a @cpp substr() @ce member instead of @cpp c_str() @ce
 -   The @ref CORRADE_LONG_DOUBLE_SAME_AS_DOUBLE macro is now defined on
@@ -286,8 +285,8 @@ namespace Corrade {
 
 @subsection corrade-changelog-latest-bugfixes Bug fixes
 
--   @ref Utility::Directory::list() was leaking the file handle on Windows
-    (see [mosra/corrade#99](https://github.com/mosra/corrade/pull/99))
+-   @ref Utility::Path::list() was leaking the file handle on Windows (see
+    [mosra/corrade#99](https://github.com/mosra/corrade/pull/99))
 -   Added GCC 4.8-specific workarounds to @ref Containers::Array, growable
     array utils, @ref Containers::Optional, @ref Containers::Pointer and
     @ref Containers::StaticArray where using @cpp T{b} @ce or
@@ -328,6 +327,74 @@ namespace Corrade {
 -   @cpp Utility::Directory::isSandboxed() @ce is deprecated in favor of
     @ref Utility::System::isSandboxed(), as that's the better place for this
     API to live in
+-   All other @cpp Utility::Directory @ce APIs are deprecated in favor of a new
+    @ref Utility::Path namespace. It uses the more efficient
+    @ref Containers::StringView instead of @ref std::string for function
+    arguments and non-owned return values, @ref Containers::String
+    instead of @ref std::string for owned return values, wraps return values
+    for all failable APIs in a @ref Containers::Optional and makes various API
+    naming cleanups and clarifications. Because of the sweeping nature of the
+    changes, it was not possible to make these updates
+    in @cpp Utility::Directory @ce directly, as it would cause basically all
+    existing code to break. Thus the new APIs are in a completely new
+    namespace:
+    -   @cpp Utility::Directory::fromNativeSeparators() @ce and
+        @cpp toNativeSeparators() @ce is deprecated in favor
+        of @ref Utility::Path::fromNativeSeparators() and
+        @relativeref{Utility::Path,toNativeSeparators()}
+    -   @cpp Utility::Directory::path() @ce and @cpp filename() @ce is
+        deprecated in favor of @ref Utility::Path::split() that returns both
+        parts together
+    -   @cpp Utility::Directory::splitExtension() @ce is deprecated in favor of
+        @ref Utility::Path::splitExtension()
+    -   @cpp Utility::Directory::join() @ce is deprecated in favor of
+        @ref Utility::Path::join()
+    -   @cpp Utility::Directory::list() @ce, @cpp Flag @ce and @cpp Flags @ce
+        are deprecated in favor of @ref Utility::Path::list(),
+        @relativeref{Utility::Path,ListFlag} and
+        @relativeref{Utility::Path,ListFlags}, returning the list wrapped in a
+        @ref Containers::Optional
+    -   @cpp Utility::Directory::mkpath() @ce, @cpp rm() @ce and
+        @cpp move() @ce are deprecated in favor of @ref Utility::Path::make(),
+        @relativeref{Utility::Path,remove()} and
+        @relativeref{Utility::Path,move()}
+    -   @cpp Utility::Directory::current() @ce, @cpp libraryLocation() @ce,
+        @cpp executableLocation() @ce, @cpp home() @ce,
+        @cpp configurationDir() @ce and @cpp tmp() @ce are deprecated in favor
+        of @ref Utility::Path::currentDirectory(),
+        @relativeref{Utility::Path,libraryLocation()},
+        @relativeref{Utility::Path,executableLocation()},
+        @relativeref{Utility::Path,homeDirectory()},
+        @relativeref{Utility::Path,configurationDirectory()} and
+        @relativeref{Utility::Path,temporaryDirectory()}, all returning the
+        path wrapped in a @ref Containers::Optional
+    -   @cpp Utility::Directory::exists() @ce and @cpp isDirectory() @ce is
+        deprecated in favor of @ref Utility::Path::exists() and
+        @relativeref{Utility::Path,isDirectory()}
+    -   @cpp Utility::Directory::fileSize() @ce is deprecated in favor of
+        @ref Utility::Path::size()
+    -   @cpp Utility::Directory::read() @ce is deprecated in favor of
+        @ref Utility::Path::read(), returning a @ref Containers::Optional
+    -   @cpp Utility::Directory::readString() @ce is deprecated in favor of
+        @ref Utility::Path::readString(), returning a
+        @ref Containers::String in a @ref Containers::Optional, transferring
+        the memory ownership from a @ref Containers::Array instead of making a
+        copy
+    -   @cpp Utility::Directory::write() @ce, @cpp writeString() @ce,
+        @cpp append() @ce and @cpp appendString() @ce are deprecated in favor
+        of @ref Utility::Path::write() and
+        @relativeref{Utility::Path,append()}. Because a
+        @ref Containers::StringView is implicitly convertible to a
+        @ref Containers::ArrayView<const void>, there's no need for a dedicated
+        string overload anymore.
+    -   @cpp Utility::Directory::copy() @ce is deprecated in favor of
+        @ref Utility::Path::copy(),
+    -   @cpp Utility::Directory::map() @ce, @cpp mapRead() @ce,
+        @cpp mapWrite() @ce and @cpp MapDeleter @ce are deprecated in favor of
+        @ref Utility::Path::map(), @relativeref{Utility::Path,mapRead()},
+        @relativeref{Utility::Path,mapWrite()} and
+        @relativeref{Utility::Path,MapDeleter}, returning the mapped array
+        wrapped in an @ref Containers::Optional
 -   @ref Utility::String::split() and
     @ref Utility::String::splitWithoutEmptyParts() overloads taking
     @ref Containers::BasicStringView are deprecated in favor of
@@ -505,9 +572,9 @@ Released 2020-06-27, tagged as
     is available in the standard library
 -   Added a @ref CORRADE_LONG_DOUBLE_SAME_AS_DOUBLE macro for detecting
     platforms where @cpp long double @ce and @cpp double @ce have the same size
--   Added @ref Utility::Directory::map(const std::string&) that provides
+-   Added @cpp Utility::Directory::map(const std::string&) @ce that provides
     read-write access to mapped files without truncating them.
--   Added @ref Utility::Directory::fileSize()
+-   Added @cpp Utility::Directory::fileSize() @ce
 -   New @ref Utility::Endianness::littleEndianInPlace() and
     @ref Utility::Endianness::bigEndianInPlace() overloads taking strided array
     views
@@ -611,8 +678,8 @@ Released 2020-06-27, tagged as
     commas
 -   Enabled @ref Utility::Debug::operator<<(long double) on Emscripten as well,
     as it being unavailable was a pointless restriction hurting portability
--   @ref Utility::Directory::mkpath() now properly reports errors instead of
-    just arrogantly returning @cpp false @ce (see [mosra/corrade#92](https://github.com/mosra/corrade/pull/92))
+-   @cpp Utility::Directory::mkpath() @ce now properly reports errors instead
+    of just arrogantly returning @cpp false @ce (see [mosra/corrade#92](https://github.com/mosra/corrade/pull/92))
 
 @subsection corrade-changelog-2020-06-buildsystem Build system
 
@@ -661,9 +728,9 @@ Released 2020-06-27, tagged as
 @subsection corrade-changelog-2020-06-deprecated Deprecated APIs
 
 -   @cpp Utility::Directory::map(const std::string&, std::size_t) @ce is
-    deprecated and renamed to @ref Utility::Directory::mapWrite() as it doesn't
-    preserve original file contents and thus can't be used for read-write
-    access
+    deprecated and renamed to @cpp Utility::Directory::mapWrite() @ce as it
+    doesn't preserve original file contents and thus can't be used for
+    read-write access
 -   The internal @cpp CORRADE_BIG_ENDIAN @ce macro got renamed to
     @ref CORRADE_TARGET_BIG_ENDIAN and made public. The old variant is still
     present for backwards compatibility, but will be removed in the future.
@@ -684,7 +751,7 @@ Released 2020-06-27, tagged as
     with 15 significant digits instead of 18 on platforms where it is 64-bit
     instead of 80-bit
 -   @ref Utility::Endianness is now a namespace, similarly to the change done
-    to @ref Utility::Directory or @ref Utility::String in 2018.02. The API
+    to @cpp Utility::Directory @ce or @ref Utility::String in 2018.02. The API
     doesn't change apart from that, but code previously doing
     @cpp using Utility::Endianness @ce needs to be changed to
     @cpp using namespace Utility::Endianness @ce to compile again.
@@ -789,21 +856,21 @@ Released 2019-10-24, tagged as
 -   @ref Utility::Debug::packed and @ref Utility::Debug::color output modifiers
     for tighter printing of container types and printing color-like values as
     actual 24bit ANSI color sequences
--   New @ref Utility::Directory::append() and
-    @ref Utility::Directory::appendString() counterparts to
-    @ref Utility::Directory::write()
--   New @ref Utility::Directory::copy() utility for zero-allocation file
+-   New @cpp Utility::Directory::append() @ce and
+    @cpp Utility::Directory::appendString() @ce counterparts to
+    @cpp Utility::Directory::write() @ce
+-   New @cpp Utility::Directory::copy() @ce utility for zero-allocation file
     copies.
--   New @ref Utility::Directory::join(std::initializer_list<std::string>)
+-   New @cpp Utility::Directory::join(std::initializer_list<std::string>) @ce
     overload for joining a path from multiple parts at once
--   New @ref Utility::Directory::current() utility for getting current working
-    directory
--   New @ref Utility::Directory::isDirectory() utility for distinguishing
+-   New @cpp Utility::Directory::current() @ce utility for getting current
+    working directory
+-   New @cpp Utility::Directory::isDirectory() @ce utility for distinguishing
     between files and directories
--   @ref Utility::Directory::libraryLocation() as a counterpart to
-    @ref Utility::Directory::executableLocation()
--   @ref Utility::Directory::splitExtension() as a complement to
-    @ref Utility::Directory::path() and @ref Utility::Directory::filename()
+-   @cpp Utility::Directory::libraryLocation() @ce as a counterpart to
+    @cpp Utility::Directory::executableLocation() @ce
+-   @cpp Utility::Directory::splitExtension() @ce as a complement to
+    @cpp Utility::Directory::path() @ce and @cpp Utility::Directory::filename() @ce
 -   New @ref Corrade/Utility/StlForwardArray.h,
     @ref Corrade/Utility/StlForwardString.h,
     @ref Corrade/Utility/StlForwardTuple.h and
@@ -1009,9 +1076,9 @@ Released 2019-10-24, tagged as
     [mosra/corrade#58](https://github.com/mosra/corrade/pull/58))
 -   Fixed @ref Utility::Sha1 calculation on big-endian platforms (see
     [mosra/corrade#60](https://github.com/mosra/corrade/pull/60))
--   Fixed @ref Utility::Directory::read() to not use `ftello()` on 32-bit
+-   Fixed @cpp Utility::Directory::read() @ce to not use `ftello()` on 32-bit
     Android and API levels below 24
--   Fixed @ref Utility::Directory::read() to work with files that report an
+-   Fixed @cpp Utility::Directory::read() @ce to work with files that report an
     early EOF (such as stuff from `/sys` on Linux)
 -   Fixed @ref Interconnect::Emitter::emit() for signals from
     multiply-inherited base classes on MSVC --- it was due to an insufficiently
@@ -1029,8 +1096,8 @@ Released 2019-10-24, tagged as
     @ref Utility::Resource data happens more than once. While this was allowed
     for registration, the unregistration caused an assert to be fired. Fixed
     this to be allowed on both.
--   @ref Utility::Directory::copy() wasn't properly freeing both opened files
-    if one of them failed to open (see [mosra/corrade#70](https://github.com/mosra/corrade/pull/70))
+-   @cpp Utility::Directory::copy() @ce wasn't properly freeing both opened
+    files if one of them failed to open (see [mosra/corrade#70](https://github.com/mosra/corrade/pull/70))
 -   @ref Interconnect::Emitter::emit() (and signal/slot connections in general)
     now work correctly with non-copyable arguments
 -   Fixed @ref Utility::Debug::isTty() (and thus also @ref TestSuite colored
@@ -1049,7 +1116,7 @@ Released 2019-10-24, tagged as
     favor of @ref Utility::Arguments::setGlobalHelp() to avoid it being used
     for documenting named arguments by accident.
 -   @cpp Utility::Directory::fileExists() @ce is now deprecated in favor of
-    @ref Utility::Directory::exists(). It was named like this to prevent it
+    @cpp Utility::Directory::exists() @ce. It was named like this to prevent it
     from looking like it works on directories only, but such name then caused
     people to ask if it works on directories as well, not helping anything.
 -   `Interconnect::Connection::isConnected()` and

doc/snippets/Utility.cpp

@@ -627,9 +627,9 @@ if(stuff.broken())
 #if defined(DOXYGEN_GENERATING_OUTPUT) || defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT))
 {
 std::string from, to;
-/* [Directory-copy-mmap] */
-Utility::Directory::write(to, Utility::Directory::mapRead(from));
-/* [Directory-copy-mmap] */
+/* [Path-copy-mmap] */
+Utility::Path::write(to, *Utility::Path::mapRead(from));
+/* [Path-copy-mmap] */
 }
 #endif
 

modules/FindCorrade.cmake

@@ -529,7 +529,7 @@ foreach(_component ${Corrade_FIND_COMPONENTS})
             set_property(TARGET Corrade::${_component} APPEND PROPERTY
                 COMPATIBLE_INTERFACE_NUMBER_MAX CORRADE_CXX_STANDARD)
 
-            # Directory::libraryLocation() needs this
+            # Path::libraryLocation() needs this
             if(CORRADE_TARGET_UNIX)
                 set_property(TARGET Corrade::${_component} APPEND PROPERTY
                     INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})

modules/UseCorrade.cmake

@@ -235,7 +235,7 @@ endif()
 
 if(CORRADE_TARGET_CLANG_CL)
     list(APPEND CORRADE_PEDANTIC_COMPILER_OPTIONS
-        # See Utility::Directory::libraryLocation() for details
+        # See Utility::Path::libraryLocation() for details
         "-Wno-microsoft-cast")
 endif()