libstdc++
experimental/bits/fs_path.h
Go to the documentation of this file.
1 // Class filesystem::path -*- C++ -*-
2 
3 // Copyright (C) 2014-2021 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file experimental/bits/fs_path.h
26  * This is an internal header file, included by other library headers.
27  * Do not attempt to use it directly. @headername{experimental/filesystem}
28  */
29 
30 #ifndef _GLIBCXX_EXPERIMENTAL_FS_PATH_H
31 #define _GLIBCXX_EXPERIMENTAL_FS_PATH_H 1
32 
33 #if __cplusplus < 201103L
34 # include <bits/c++0x_warning.h>
35 #else
36 
37 #include <utility>
38 #include <type_traits>
39 #include <vector>
40 #include <locale>
41 #include <iosfwd>
42 #include <codecvt>
43 #include <system_error>
44 #include <bits/stl_algobase.h>
45 #include <bits/quoted_string.h>
46 #include <bits/locale_conv.h>
47 #if __cplusplus == 201402L
48 # include <experimental/string_view>
49 #endif
50 
51 #if defined(_WIN32) && !defined(__CYGWIN__)
52 # define _GLIBCXX_FILESYSTEM_IS_WINDOWS 1
53 # include <algorithm>
54 #endif
55 
56 namespace std _GLIBCXX_VISIBILITY(default)
57 {
58 _GLIBCXX_BEGIN_NAMESPACE_VERSION
59 
60 namespace experimental
61 {
62 namespace filesystem
63 {
64 inline namespace v1
65 {
66 _GLIBCXX_BEGIN_NAMESPACE_CXX11
67 
68 #if __cplusplus == 201402L
70 #elif __cplusplus > 201402L
72 #endif
73 
74  /// @cond undocumented
75 namespace __detail
76 {
77  /** @addtogroup filesystem-ts
78  * @{
79  */
80 
81  template<typename _CharT,
82  typename _Ch = typename remove_const<_CharT>::type>
83  using __is_encoded_char
84  = __or_<is_same<_Ch, char>,
85  is_same<_Ch, wchar_t>,
86 #ifdef _GLIBCXX_USE_CHAR8_T
87  is_same<_Ch, char8_t>,
88 #endif
89  is_same<_Ch, char16_t>,
90  is_same<_Ch, char32_t>>;
91 
92  template<typename _Iter,
93  typename _Iter_traits = std::iterator_traits<_Iter>>
94  using __is_path_iter_src
95  = __and_<__is_encoded_char<typename _Iter_traits::value_type>,
97  typename _Iter_traits::iterator_category>>;
98 
99  template<typename _Iter>
100  static __is_path_iter_src<_Iter>
101  __is_path_src(_Iter, int);
102 
103  template<typename _CharT, typename _Traits, typename _Alloc>
104  static __is_encoded_char<_CharT>
105  __is_path_src(const basic_string<_CharT, _Traits, _Alloc>&, int);
106 
107 #if __cplusplus >= 201402L
108  template<typename _CharT, typename _Traits>
109  static __is_encoded_char<_CharT>
110  __is_path_src(const basic_string_view<_CharT, _Traits>&, int);
111 #endif
112 
113  template<typename _Unknown>
114  static std::false_type
115  __is_path_src(const _Unknown&, ...);
116 
117  template<typename _Tp1, typename _Tp2>
118  struct __constructible_from;
119 
120  template<typename _Iter>
121  struct __constructible_from<_Iter, _Iter>
122  : __is_path_iter_src<_Iter>
123  { };
124 
125  template<typename _Source>
126  struct __constructible_from<_Source, void>
127  : decltype(__is_path_src(std::declval<const _Source&>(), 0))
128  { };
129 
130  template<typename _Tp1, typename _Tp2 = void,
131  typename _Tp1_nocv = typename remove_cv<_Tp1>::type,
132  typename _Tp1_noptr = typename remove_pointer<_Tp1>::type>
133  using _Path = typename
135  __not_<is_void<_Tp1_noptr>>,
136  __constructible_from<_Tp1, _Tp2>>::value,
137  path>::type;
138 
139  template<typename _Source>
140  inline _Source
141  _S_range_begin(_Source __begin) { return __begin; }
142 
143  struct __nul_terminated { };
144 
145  template<typename _Source>
146  inline __nul_terminated
147  _S_range_end(_Source) { return {}; }
148 
149  template<typename _CharT, typename _Traits, typename _Alloc>
150  inline const _CharT*
151  _S_range_begin(const basic_string<_CharT, _Traits, _Alloc>& __str)
152  { return __str.data(); }
153 
154  template<typename _CharT, typename _Traits, typename _Alloc>
155  inline const _CharT*
156  _S_range_end(const basic_string<_CharT, _Traits, _Alloc>& __str)
157  { return __str.data() + __str.size(); }
158 
159 #if __cplusplus >= 201402L
160  template<typename _CharT, typename _Traits>
161  inline const _CharT*
162  _S_range_begin(const basic_string_view<_CharT, _Traits>& __str)
163  { return __str.data(); }
164 
165  template<typename _CharT, typename _Traits>
166  inline const _CharT*
167  _S_range_end(const basic_string_view<_CharT, _Traits>& __str)
168  { return __str.data() + __str.size(); }
169 #endif
170 
171  template<typename _Tp,
172  typename _Iter = decltype(_S_range_begin(std::declval<_Tp>())),
173  typename _Val = typename std::iterator_traits<_Iter>::value_type,
174  typename _UnqualVal = typename std::remove_const<_Val>::type>
175  using __value_type_is_char = typename std::enable_if<
177  _UnqualVal>::type;
178 
179  template<typename _Tp,
180  typename _Iter = decltype(_S_range_begin(std::declval<_Tp>())),
181  typename _Val = typename std::iterator_traits<_Iter>::value_type,
182  typename _UnqualVal = typename std::remove_const<_Val>::type>
183  using __value_type_is_char_or_char8_t = typename std::enable_if<
184  __or_<
186 #ifdef _GLIBCXX_USE_CHAR8_T
188 #endif
189  >::value, _UnqualVal>::type;
190 
191  /// @} group filesystem-ts
192 } // namespace __detail
193  /// @endcond
194 
195  /** @addtogroup filesystem-ts
196  * @{
197  */
198 
199  /// A filesystem path.
200  /// @ingroup filesystem-ts
201  class path
202  {
203  public:
204 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
205  typedef wchar_t value_type;
206  static constexpr value_type preferred_separator = L'\\';
207 #else
208  typedef char value_type;
209  static constexpr value_type preferred_separator = '/';
210 #endif
211  typedef std::basic_string<value_type> string_type;
212 
213  // constructors and destructor
214 
215  path() noexcept { }
216 
217  path(const path& __p) = default;
218 
219  path(path&& __p) noexcept
220  : _M_pathname(std::move(__p._M_pathname)), _M_type(__p._M_type)
221  {
222  if (_M_type == _Type::_Multi)
223  _M_split_cmpts();
224  __p.clear();
225  }
226 
227  path(string_type&& __source)
228  : _M_pathname(std::move(__source))
229  { _M_split_cmpts(); }
230 
231  template<typename _Source,
232  typename _Require = __detail::_Path<_Source>>
233  path(_Source const& __source)
234  : _M_pathname(_S_convert(__detail::_S_range_begin(__source),
235  __detail::_S_range_end(__source)))
236  { _M_split_cmpts(); }
237 
238  template<typename _InputIterator,
239  typename _Require = __detail::_Path<_InputIterator, _InputIterator>>
240  path(_InputIterator __first, _InputIterator __last)
241  : _M_pathname(_S_convert(__first, __last))
242  { _M_split_cmpts(); }
243 
244  template<typename _Source,
245  typename _Require = __detail::_Path<_Source>,
246  typename _Require2 = __detail::__value_type_is_char<_Source>>
247  path(_Source const& __source, const locale& __loc)
248  : _M_pathname(_S_convert_loc(__detail::_S_range_begin(__source),
249  __detail::_S_range_end(__source), __loc))
250  { _M_split_cmpts(); }
251 
252  template<typename _InputIterator,
253  typename _Require = __detail::_Path<_InputIterator, _InputIterator>,
254  typename _Require2 = __detail::__value_type_is_char<_InputIterator>>
255  path(_InputIterator __first, _InputIterator __last, const locale& __loc)
256  : _M_pathname(_S_convert_loc(__first, __last, __loc))
257  { _M_split_cmpts(); }
258 
259  ~path() = default;
260 
261  // assignments
262 
263  path& operator=(const path& __p) = default;
264  path& operator=(path&& __p) noexcept;
265  path& operator=(string_type&& __source);
266  path& assign(string_type&& __source);
267 
268  template<typename _Source>
269  __detail::_Path<_Source>&
270  operator=(_Source const& __source)
271  { return *this = path(__source); }
272 
273  template<typename _Source>
274  __detail::_Path<_Source>&
275  assign(_Source const& __source)
276  { return *this = path(__source); }
277 
278  template<typename _InputIterator>
279  __detail::_Path<_InputIterator, _InputIterator>&
280  assign(_InputIterator __first, _InputIterator __last)
281  { return *this = path(__first, __last); }
282 
283  // appends
284 
285  path& operator/=(const path& __p) { return _M_append(__p._M_pathname); }
286 
287  template<typename _Source>
288  __detail::_Path<_Source>&
289  operator/=(_Source const& __source)
290  { return append(__source); }
291 
292  template<typename _Source>
293  __detail::_Path<_Source>&
294  append(_Source const& __source)
295  {
296  return _M_append(_S_convert(__detail::_S_range_begin(__source),
297  __detail::_S_range_end(__source)));
298  }
299 
300  template<typename _InputIterator>
301  __detail::_Path<_InputIterator, _InputIterator>&
302  append(_InputIterator __first, _InputIterator __last)
303  { return _M_append(_S_convert(__first, __last)); }
304 
305  // concatenation
306 
307  path& operator+=(const path& __x);
308  path& operator+=(const string_type& __x);
309  path& operator+=(const value_type* __x);
310  path& operator+=(value_type __x);
311 #if __cplusplus >= 201402L
312  path& operator+=(basic_string_view<value_type> __x);
313 #endif
314 
315  template<typename _Source>
316  __detail::_Path<_Source>&
317  operator+=(_Source const& __x) { return concat(__x); }
318 
319  template<typename _CharT>
320  __detail::_Path<_CharT*, _CharT*>&
321  operator+=(_CharT __x);
322 
323  template<typename _Source>
324  __detail::_Path<_Source>&
325  concat(_Source const& __x)
326  {
327  return *this += _S_convert(__detail::_S_range_begin(__x),
328  __detail::_S_range_end(__x));
329  }
330 
331  template<typename _InputIterator>
332  __detail::_Path<_InputIterator, _InputIterator>&
333  concat(_InputIterator __first, _InputIterator __last)
334  { return *this += _S_convert(__first, __last); }
335 
336  // modifiers
337 
338  void clear() noexcept { _M_pathname.clear(); _M_split_cmpts(); }
339 
340  path& make_preferred();
341  path& remove_filename();
342  path& replace_filename(const path& __replacement);
343  path& replace_extension(const path& __replacement = path());
344 
345  void swap(path& __rhs) noexcept;
346 
347  // native format observers
348 
349  const string_type& native() const noexcept { return _M_pathname; }
350  const value_type* c_str() const noexcept { return _M_pathname.c_str(); }
351  operator string_type() const { return _M_pathname; }
352 
353  template<typename _CharT, typename _Traits = std::char_traits<_CharT>,
354  typename _Allocator = std::allocator<_CharT>>
356  string(const _Allocator& __a = _Allocator()) const;
357 
358  std::string string() const;
359 #if _GLIBCXX_USE_WCHAR_T
360  std::wstring wstring() const;
361 #endif
362 #ifdef _GLIBCXX_USE_CHAR8_T
363  __attribute__((__abi_tag__("__u8")))
364  std::u8string u8string() const;
365 #else
366  std::string u8string() const;
367 #endif // _GLIBCXX_USE_CHAR8_T
368  std::u16string u16string() const;
369  std::u32string u32string() const;
370 
371  // generic format observers
372  template<typename _CharT, typename _Traits = std::char_traits<_CharT>,
373  typename _Allocator = std::allocator<_CharT>>
375  generic_string(const _Allocator& __a = _Allocator()) const;
376 
377  std::string generic_string() const;
378 #if _GLIBCXX_USE_WCHAR_T
379  std::wstring generic_wstring() const;
380 #endif
381 #ifdef _GLIBCXX_USE_CHAR8_T
382  __attribute__((__abi_tag__("__u8")))
383  std::u8string generic_u8string() const;
384 #else
385  std::string generic_u8string() const;
386 #endif // _GLIBCXX_USE_CHAR8_T
387  std::u16string generic_u16string() const;
388  std::u32string generic_u32string() const;
389 
390  // compare
391 
392  int compare(const path& __p) const noexcept;
393  int compare(const string_type& __s) const;
394  int compare(const value_type* __s) const;
395 #if __cplusplus >= 201402L
396  int compare(const basic_string_view<value_type> __s) const;
397 #endif
398 
399  // decomposition
400 
401  path root_name() const;
402  path root_directory() const;
403  path root_path() const;
404  path relative_path() const;
405  path parent_path() const;
406  path filename() const;
407  path stem() const;
408  path extension() const;
409 
410  // query
411 
412  _GLIBCXX_NODISCARD bool empty() const noexcept { return _M_pathname.empty(); }
413  bool has_root_name() const;
414  bool has_root_directory() const;
415  bool has_root_path() const;
416  bool has_relative_path() const;
417  bool has_parent_path() const;
418  bool has_filename() const;
419  bool has_stem() const;
420  bool has_extension() const;
421  bool is_absolute() const;
422  bool is_relative() const { return !is_absolute(); }
423 
424  // iterators
425  class iterator;
426  typedef iterator const_iterator;
427 
428  iterator begin() const;
429  iterator end() const;
430 
431  /// @cond undocumented
432  // Create a basic_string by reading until a null character.
433  template<typename _InputIterator,
434  typename _Traits = std::iterator_traits<_InputIterator>,
435  typename _CharT
436  = typename std::remove_cv<typename _Traits::value_type>::type>
438  _S_string_from_iter(_InputIterator __source)
439  {
441  for (_CharT __ch = *__source; __ch != _CharT(); __ch = *++__source)
442  __str.push_back(__ch);
443  return __str;
444  }
445  /// @endcond
446 
447  private:
448  enum class _Type : unsigned char {
449  _Multi, _Root_name, _Root_dir, _Filename
450  };
451 
452  path(string_type __str, _Type __type) : _M_pathname(__str), _M_type(__type)
453  {
454  __glibcxx_assert(!empty());
455  __glibcxx_assert(_M_type != _Type::_Multi);
456  }
457 
458  enum class _Split { _Stem, _Extension };
459 
460  path& _M_append(const string_type& __str)
461  {
462  if (!_M_pathname.empty() && !_S_is_dir_sep(_M_pathname.back())
463  && !__str.empty() && !_S_is_dir_sep(__str.front()))
464  _M_pathname += preferred_separator;
465  _M_pathname += __str;
466  _M_split_cmpts();
467  return *this;
468  }
469 
470  pair<const string_type*, size_t> _M_find_extension() const;
471 
472  template<typename _CharT>
473  struct _Cvt;
474 
475  static string_type
476  _S_convert(value_type* __src, __detail::__nul_terminated)
477  { return string_type(__src); }
478 
479  static string_type
480  _S_convert(const value_type* __src, __detail::__nul_terminated)
481  { return string_type(__src); }
482 
483  template<typename _Iter>
484  static string_type
485  _S_convert(_Iter __first, _Iter __last)
486  {
487  using __value_type = typename std::iterator_traits<_Iter>::value_type;
488  return _Cvt<typename remove_cv<__value_type>::type>::
489  _S_convert(__first, __last);
490  }
491 
492  template<typename _InputIterator>
493  static string_type
494  _S_convert(_InputIterator __src, __detail::__nul_terminated)
495  {
496  auto __s = _S_string_from_iter(__src);
497  return _S_convert(__s.c_str(), __s.c_str() + __s.size());
498  }
499 
500  static string_type
501  _S_convert_loc(const char* __first, const char* __last,
502  const std::locale& __loc);
503 
504  static string_type
505  _S_convert_loc(char* __first, char* __last, const std::locale& __loc)
506  {
507  return _S_convert_loc(const_cast<const char*>(__first),
508  const_cast<const char*>(__last), __loc);
509  }
510 
511  template<typename _Iter>
512  static string_type
513  _S_convert_loc(_Iter __first, _Iter __last, const std::locale& __loc)
514  {
515  const std::string __str(__first, __last);
516  return _S_convert_loc(__str.data(), __str.data()+__str.size(), __loc);
517  }
518 
519  template<typename _InputIterator>
520  static string_type
521  _S_convert_loc(_InputIterator __src, __detail::__nul_terminated,
522  const std::locale& __loc)
523  {
524  const std::string __s = _S_string_from_iter(__src);
525  return _S_convert_loc(__s.data(), __s.data() + __s.size(), __loc);
526  }
527 
528  static bool _S_is_dir_sep(value_type __ch)
529  {
530 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
531  return __ch == L'/' || __ch == preferred_separator;
532 #else
533  return __ch == '/';
534 #endif
535  }
536 
537  void _M_split_cmpts();
538  void _M_trim();
539  void _M_add_root_name(size_t __n);
540  void _M_add_root_dir(size_t __pos);
541  void _M_add_filename(size_t __pos, size_t __n);
542 
543  string_type _M_pathname;
544 
545  struct _Cmpt;
546  using _List = _GLIBCXX_STD_C::vector<_Cmpt>;
547  _List _M_cmpts; // empty unless _M_type == _Type::_Multi
548  _Type _M_type = _Type::_Multi;
549  };
550 
551  /// @relates std::experimental::filesystem::path @{
552 
553  /// Swap overload for paths
554  inline void swap(path& __lhs, path& __rhs) noexcept { __lhs.swap(__rhs); }
555 
556  /// Compute a hash value for a path
557  size_t hash_value(const path& __p) noexcept;
558 
559  /// Compare paths
560  inline bool operator<(const path& __lhs, const path& __rhs) noexcept;
561 
562  /// Compare paths
563  inline bool operator<=(const path& __lhs, const path& __rhs) noexcept
564  { return !(__rhs < __lhs); }
565 
566  /// Compare paths
567  inline bool operator>(const path& __lhs, const path& __rhs) noexcept
568  { return __rhs < __lhs; }
569 
570  /// Compare paths
571  inline bool operator>=(const path& __lhs, const path& __rhs) noexcept
572  { return !(__lhs < __rhs); }
573 
574  /// Compare paths
575  inline bool operator==(const path& __lhs, const path& __rhs) noexcept;
576 
577  /// Compare paths
578  inline bool operator!=(const path& __lhs, const path& __rhs) noexcept
579  { return !(__lhs == __rhs); }
580 
581  /// Append one path to another
582  inline path operator/(const path& __lhs, const path& __rhs)
583  {
584  path __result(__lhs);
585  __result /= __rhs;
586  return __result;
587  }
588 
589  /// Write a path to a stream
590  template<typename _CharT, typename _Traits>
591  basic_ostream<_CharT, _Traits>&
592  operator<<(basic_ostream<_CharT, _Traits>& __os, const path& __p)
593  {
594  auto __tmp = __p.string<_CharT, _Traits>();
595  using __quoted_string
596  = std::__detail::_Quoted_string<decltype(__tmp)&, _CharT>;
597  __os << __quoted_string{__tmp, _CharT('"'), _CharT('\\')};
598  return __os;
599  }
600 
601  /// Read a path from a stream
602  template<typename _CharT, typename _Traits>
603  basic_istream<_CharT, _Traits>&
604  operator>>(basic_istream<_CharT, _Traits>& __is, path& __p)
605  {
606  basic_string<_CharT, _Traits> __tmp;
607  using __quoted_string
608  = std::__detail::_Quoted_string<decltype(__tmp)&, _CharT>;
609  if (__is >> __quoted_string{ __tmp, _CharT('"'), _CharT('\\') })
610  __p = std::move(__tmp);
611  return __is;
612  }
613 
614  /// Create a path from a UTF-8-encoded sequence of char
615 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
616  template<typename _InputIterator>
617  inline path
618  __u8path(_InputIterator __first, _InputIterator __last, char)
619  {
620  // XXX This assumes native wide encoding is UTF-16.
621  std::codecvt_utf8_utf16<path::value_type> __cvt;
622  path::string_type __tmp;
623  const std::string __u8str{__first, __last};
624  const char* const __ptr = __u8str.data();
625  if (__str_codecvt_in_all(__ptr, __ptr + __u8str.size(), __tmp, __cvt))
626  return path{ __tmp };
627  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
628  "Cannot convert character sequence",
629  std::make_error_code(errc::illegal_byte_sequence)));
630  }
631 
632 #ifdef _GLIBCXX_USE_CHAR8_T
633  template<typename _InputIterator>
634  inline path
635  __u8path(_InputIterator __first, _InputIterator __last, char8_t)
636  {
637  return path{ __first, __last };
638  }
639 #endif // _GLIBCXX_USE_CHAR8_T
640 #endif // _GLIBCXX_FILESYSTEM_IS_WINDOWS
641 
642  template<typename _InputIterator,
643  typename _Require = __detail::_Path<_InputIterator, _InputIterator>,
644  typename _CharT =
645  __detail::__value_type_is_char_or_char8_t<_InputIterator>>
646  inline path
647  u8path(_InputIterator __first, _InputIterator __last)
648  {
649 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
650  return __u8path(__first, __last, _CharT{});
651 #else
652  return path{ __first, __last };
653 #endif
654  }
655 
656  /// Create a path from a UTF-8-encoded sequence of char
657 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
658  inline path
659  __u8path(const string& __s, char)
660  {
661  return filesystem::u8path(__s.data(), __s.data() + __s.size());
662  }
663 
664  template<typename _Source>
665  inline __enable_if_t<is_convertible<const _Source&, string>::value, path>
666  __u8path(const _Source& __source, char)
667  {
668  std::string __s = __source;
669  return filesystem::u8path(__s.data(), __s.data() + __s.size());
670  }
671 
672  template<typename _Source>
673  inline __enable_if_t<!is_convertible<const _Source&, string>::value, path>
674  __u8path(const _Source& __source, char)
675  {
676  std::string __s = path::_S_string_from_iter(__source);
677  return filesystem::u8path(__s.data(), __s.data() + __s.size());
678  }
679 
680 #ifdef _GLIBCXX_USE_CHAR8_T
681  template<typename _Source>
682  inline path
683  __u8path(const _Source& __source, char8_t)
684  {
685  return path{ __source };
686  }
687 #endif // _GLIBCXX_USE_CHAR8_T
688 #endif // _GLIBCXX_FILESYSTEM_IS_WINDOWS
689 
690  template<typename _Source,
691  typename _Require = __detail::_Path<_Source>,
692  typename _CharT =
693  __detail::__value_type_is_char_or_char8_t<_Source>>
694  inline path
695  u8path(const _Source& __source)
696  {
697 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
698  return __u8path(__source, _CharT{});
699 #else
700  return path{ __source };
701 #endif
702  }
703 
704  /// @}
705 
706  /// Exception type thrown by the Filesystem TS library
708  {
709  public:
710  filesystem_error(const string& __what_arg, error_code __ec)
711  : system_error(__ec, __what_arg) { }
712 
713  filesystem_error(const string& __what_arg, const path& __p1,
714  error_code __ec)
715  : system_error(__ec, __what_arg), _M_path1(__p1) { }
716 
717  filesystem_error(const string& __what_arg, const path& __p1,
718  const path& __p2, error_code __ec)
719  : system_error(__ec, __what_arg), _M_path1(__p1), _M_path2(__p2)
720  { }
721 
722  ~filesystem_error();
723 
724  const path& path1() const noexcept { return _M_path1; }
725  const path& path2() const noexcept { return _M_path2; }
726  const char* what() const noexcept { return _M_what.c_str(); }
727 
728  private:
729  std::string _M_gen_what();
730 
731  path _M_path1;
732  path _M_path2;
733  std::string _M_what = _M_gen_what();
734  };
735 
736  /// @cond undocumented
737  struct path::_Cmpt : path
738  {
739  _Cmpt(string_type __s, _Type __t, size_t __pos)
740  : path(std::move(__s), __t), _M_pos(__pos) { }
741 
742  _Cmpt() : _M_pos(-1) { }
743 
744  size_t _M_pos;
745  };
746 
747  // specialize _Cvt for degenerate 'noconv' case
748  template<>
749  struct path::_Cvt<path::value_type>
750  {
751  // We need this type to be defined because we don't have `if constexpr`
752  // in C++11 and so path::string<C,T,A>(const A&) needs to be able to
753  // declare a variable of this type and pass it to __str_codecvt_in_all.
754  using __codecvt_utf8_to_wide = _Cvt;
755  // Dummy overload used for unreachable calls in path::string<C,T,A>.
756  template<typename _WStr>
757  friend bool
758  __str_codecvt_in_all(const char*, const char*,
759  _WStr&, __codecvt_utf8_to_wide&) noexcept
760  { return true; }
761 
762  template<typename _Iter>
763  static string_type
764  _S_convert(_Iter __first, _Iter __last)
765  { return string_type{__first, __last}; }
766  };
767 
768  // Performs conversions from _CharT to path::string_type.
769  template<typename _CharT>
770  struct path::_Cvt
771  {
772  // FIXME: We currently assume that the native wide encoding for wchar_t
773  // is either UTF-32 or UTF-16 (depending on the width of wchar_t).
774  // See comments in <bits/fs_path.h> for further details.
775  using __codecvt_utf8_to_wchar
776  = typename conditional<sizeof(wchar_t) == sizeof(char32_t),
777  std::codecvt_utf8<wchar_t>, // from UTF-32
778  std::codecvt_utf8_utf16<wchar_t> // from UTF-16
779  >::type;
780 
781  // Converts from char16_t or char32_t using std::codecvt<charNN_t, char>.
782  // Need derived class here because std::codecvt has protected destructor.
783  struct __codecvt_utf8_to_utfNN : std::codecvt<_CharT, char, mbstate_t>
784  { };
785 
786  // Convert from native pathname format (assumed to be UTF-8 everywhere)
787  // to the encoding implied by the wide character type _CharT.
788  using __codecvt_utf8_to_wide
789  = typename conditional<is_same<_CharT, wchar_t>::value,
790  __codecvt_utf8_to_wchar,
791  __codecvt_utf8_to_utfNN>::type;
792 
793 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
794 #ifdef _GLIBCXX_USE_CHAR8_T
795  static string_type
796  _S_wconvert(const char8_t* __f, const char8_t* __l, const char8_t*)
797  {
798  const char* __f2 = (const char*)__f;
799  const char* __l2 = (const char*)__l;
800  std::wstring __wstr;
801  std::codecvt_utf8_utf16<wchar_t> __wcvt;
802  if (__str_codecvt_in_all(__f2, __l2, __wstr, __wcvt))
803  return __wstr;
804  }
805 #endif
806 
807  static string_type
808  _S_wconvert(const char* __f, const char* __l, const char*)
809  {
810  std::codecvt_utf8_utf16<wchar_t> __cvt;
811  std::wstring __wstr;
812  if (__str_codecvt_in_all(__f, __l, __wstr, __cvt))
813  return __wstr;
814  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
815  "Cannot convert character sequence",
816  std::make_error_code(errc::illegal_byte_sequence)));
817  }
818 
819  static string_type
820  _S_wconvert(const _CharT* __f, const _CharT* __l, const void*)
821  {
822  __codecvt_utf8_to_wide __cvt;
823  std::string __str;
824  if (__str_codecvt_out_all(__f, __l, __str, __cvt))
825  {
826  const char* __f2 = __str.data();
827  const char* __l2 = __f2 + __str.size();
828  std::codecvt_utf8_utf16<wchar_t> __wcvt;
829  std::wstring __wstr;
830  if (__str_codecvt_in_all(__f2, __l2, __wstr, __wcvt))
831  return __wstr;
832  }
833  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
834  "Cannot convert character sequence",
835  std::make_error_code(errc::illegal_byte_sequence)));
836  }
837 
838  static string_type
839  _S_convert(const _CharT* __f, const _CharT* __l)
840  {
841  return _S_wconvert(__f, __l, (const _CharT*)nullptr);
842  }
843 #else
844  static string_type
845  _S_convert(const _CharT* __f, const _CharT* __l)
846  {
847 #ifdef _GLIBCXX_USE_CHAR8_T
848  if constexpr (is_same<_CharT, char8_t>::value)
849  return string_type(__f, __l);
850  else
851 #endif
852  {
853  __codecvt_utf8_to_wide __cvt;
854  std::string __str;
855  if (__str_codecvt_out_all(__f, __l, __str, __cvt))
856  return __str;
857  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
858  "Cannot convert character sequence",
859  std::make_error_code(errc::illegal_byte_sequence)));
860  }
861  }
862 #endif
863 
864  static string_type
865  _S_convert(_CharT* __f, _CharT* __l)
866  {
867  return _S_convert(const_cast<const _CharT*>(__f),
868  const_cast<const _CharT*>(__l));
869  }
870 
871  template<typename _Iter>
872  static string_type
873  _S_convert(_Iter __first, _Iter __last)
874  {
875  const std::basic_string<_CharT> __str(__first, __last);
876  return _S_convert(__str.data(), __str.data() + __str.size());
877  }
878 
879  template<typename _Iter, typename _Cont>
880  static string_type
881  _S_convert(__gnu_cxx::__normal_iterator<_Iter, _Cont> __first,
882  __gnu_cxx::__normal_iterator<_Iter, _Cont> __last)
883  { return _S_convert(__first.base(), __last.base()); }
884  };
885  /// @endcond
886 
887  /// An iterator for the components of a path
889  {
890  public:
891  using difference_type = std::ptrdiff_t;
892  using value_type = path;
893  using reference = const path&;
894  using pointer = const path*;
896 
897  iterator() : _M_path(nullptr), _M_cur(), _M_at_end() { }
898 
899  iterator(const iterator&) = default;
900  iterator& operator=(const iterator&) = default;
901 
902  reference operator*() const;
903  pointer operator->() const { return std::__addressof(**this); }
904 
905  iterator& operator++();
906  iterator operator++(int) { auto __tmp = *this; ++*this; return __tmp; }
907 
908  iterator& operator--();
909  iterator operator--(int) { auto __tmp = *this; --*this; return __tmp; }
910 
911  friend bool operator==(const iterator& __lhs, const iterator& __rhs)
912  { return __lhs._M_equals(__rhs); }
913 
914  friend bool operator!=(const iterator& __lhs, const iterator& __rhs)
915  { return !__lhs._M_equals(__rhs); }
916 
917  private:
918  friend class path;
919 
920  iterator(const path* __path, path::_List::const_iterator __iter)
921  : _M_path(__path), _M_cur(__iter), _M_at_end()
922  { }
923 
924  iterator(const path* __path, bool __at_end)
925  : _M_path(__path), _M_cur(), _M_at_end(__at_end)
926  { }
927 
928  bool _M_equals(iterator) const;
929 
930  const path* _M_path;
931  path::_List::const_iterator _M_cur;
932  bool _M_at_end; // only used when type != _Multi
933  };
934 
935 
936  inline path&
937  path::operator=(path&& __p) noexcept
938  {
939  _M_pathname = std::move(__p._M_pathname);
940  _M_cmpts = std::move(__p._M_cmpts);
941  _M_type = __p._M_type;
942  __p.clear();
943  return *this;
944  }
945 
946  inline path&
947  path::operator=(string_type&& __source)
948  { return *this = path(std::move(__source)); }
949 
950  inline path&
951  path::assign(string_type&& __source)
952  { return *this = path(std::move(__source)); }
953 
954  inline path&
955  path::operator+=(const path& __p)
956  {
957  return operator+=(__p.native());
958  }
959 
960  inline path&
961  path::operator+=(const string_type& __x)
962  {
963  _M_pathname += __x;
964  _M_split_cmpts();
965  return *this;
966  }
967 
968  inline path&
969  path::operator+=(const value_type* __x)
970  {
971  _M_pathname += __x;
972  _M_split_cmpts();
973  return *this;
974  }
975 
976  inline path&
977  path::operator+=(value_type __x)
978  {
979  _M_pathname += __x;
980  _M_split_cmpts();
981  return *this;
982  }
983 
984 #if __cplusplus >= 201402L
985  inline path&
986  path::operator+=(basic_string_view<value_type> __x)
987  {
988  _M_pathname.append(__x.data(), __x.size());
989  _M_split_cmpts();
990  return *this;
991  }
992 #endif
993 
994  template<typename _CharT>
995  inline __detail::_Path<_CharT*, _CharT*>&
996  path::operator+=(_CharT __x)
997  {
998  auto* __addr = std::__addressof(__x);
999  return concat(__addr, __addr + 1);
1000  }
1001 
1002  inline path&
1003  path::make_preferred()
1004  {
1005 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
1006  std::replace(_M_pathname.begin(), _M_pathname.end(), L'/',
1007  preferred_separator);
1008 #endif
1009  return *this;
1010  }
1011 
1012  inline void path::swap(path& __rhs) noexcept
1013  {
1014  _M_pathname.swap(__rhs._M_pathname);
1015  _M_cmpts.swap(__rhs._M_cmpts);
1016  std::swap(_M_type, __rhs._M_type);
1017  }
1018 
1019  template<typename _CharT, typename _Traits, typename _Allocator>
1021  path::string(const _Allocator& __a) const
1022  {
1023  if _GLIBCXX17_CONSTEXPR (is_same<_CharT, value_type>::value)
1024  return { _M_pathname.begin(), _M_pathname.end(), __a };
1025 
1026  using _WString = basic_string<_CharT, _Traits, _Allocator>;
1027 
1028  const value_type* __first = _M_pathname.data();
1029  const value_type* __last = __first + _M_pathname.size();
1030 
1031 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
1032  using _CharAlloc = __alloc_rebind<_Allocator, char>;
1033  using _String = basic_string<char, char_traits<char>, _CharAlloc>;
1034 
1035  // First convert native string from UTF-16 to to UTF-8.
1036  // XXX This assumes that the execution wide-character set is UTF-16.
1037  codecvt_utf8_utf16<value_type> __cvt;
1038  _String __u8str{_CharAlloc{__a}};
1039  if (__str_codecvt_out_all(__first, __last, __u8str, __cvt))
1040  {
1041  struct
1042  {
1043  const _String*
1044  operator()(const _String& __from, _String&, true_type)
1045  { return std::__addressof(__from); }
1046 
1047  _WString*
1048  operator()(const _String& __from, _WString& __to, false_type)
1049  {
1050 #ifdef _GLIBCXX_USE_CHAR8_T
1051  if constexpr (is_same<_CharT, char8_t>::value)
1052  {
1053  __to.assign(__from.begin(), __from.end());
1054  return std::__addressof(__to);
1055  }
1056  else
1057 #endif
1058  {
1059  // Convert UTF-8 to char16_t or char32_t string.
1060  typename path::_Cvt<_CharT>::__codecvt_utf8_to_wide __cvt;
1061  const char* __f = __from.data();
1062  const char* __l = __f + __from.size();
1063  if (__str_codecvt_in_all(__f, __l, __to, __cvt))
1064  return std::__addressof(__to);
1065  }
1066  return nullptr;
1067  }
1068  } __dispatch;
1069  _WString __wstr(__a);
1070  if (auto* __p = __dispatch(__u8str, __wstr, is_same<_CharT, char>{}))
1071  return *__p;
1072  }
1073 #else // ! Windows
1074 #ifdef _GLIBCXX_USE_CHAR8_T
1075  if constexpr (is_same<_CharT, char8_t>::value)
1076  return _WString(__first, __last, __a);
1077  else
1078 #endif
1079  {
1080  typename path::_Cvt<_CharT>::__codecvt_utf8_to_wide __cvt;
1081  _WString __wstr(__a);
1082  if (__str_codecvt_in_all(__first, __last, __wstr, __cvt))
1083  return __wstr;
1084  }
1085 #endif
1086  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
1087  "Cannot convert character sequence",
1088  std::make_error_code(errc::illegal_byte_sequence)));
1089  }
1090 
1091  inline std::string
1092  path::string() const { return string<char>(); }
1093 
1094 #if _GLIBCXX_USE_WCHAR_T
1095  inline std::wstring
1096  path::wstring() const { return string<wchar_t>(); }
1097 #endif
1098 
1099 #ifdef _GLIBCXX_USE_CHAR8_T
1100  inline std::u8string
1101  path::u8string() const { return string<char8_t>(); }
1102 #else
1103  inline std::string
1104  path::u8string() const
1105  {
1106 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
1107  std::string __str;
1108  // convert from native wide encoding (assumed to be UTF-16) to UTF-8
1109  std::codecvt_utf8_utf16<value_type> __cvt;
1110  const value_type* __first = _M_pathname.data();
1111  const value_type* __last = __first + _M_pathname.size();
1112  if (__str_codecvt_out_all(__first, __last, __str, __cvt))
1113  return __str;
1114  _GLIBCXX_THROW_OR_ABORT(filesystem_error(
1115  "Cannot convert character sequence",
1116  std::make_error_code(errc::illegal_byte_sequence)));
1117 #else
1118  return _M_pathname;
1119 #endif
1120  }
1121 #endif // _GLIBCXX_USE_CHAR8_T
1122 
1123  inline std::u16string
1124  path::u16string() const { return string<char16_t>(); }
1125 
1126  inline std::u32string
1127  path::u32string() const { return string<char32_t>(); }
1128 
1129  template<typename _CharT, typename _Traits, typename _Allocator>
1131  path::generic_string(const _Allocator& __a) const
1132  {
1133 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
1134  const _CharT __slash = is_same<_CharT, wchar_t>::value
1135  ? _CharT(L'/')
1136  : _CharT('/'); // Assume value is correct for the encoding.
1137 #else
1138  const _CharT __slash = _CharT('/');
1139 #endif
1140  basic_string<_CharT, _Traits, _Allocator> __str(__a);
1141  __str.reserve(_M_pathname.size());
1142  bool __add_slash = false;
1143  for (auto& __elem : *this)
1144  {
1145  if (__elem._M_type == _Type::_Root_dir)
1146  {
1147  __str += __slash;
1148  continue;
1149  }
1150  if (__add_slash)
1151  __str += __slash;
1152  __str += __elem.string<_CharT, _Traits, _Allocator>(__a);
1153  __add_slash = __elem._M_type == _Type::_Filename;
1154  }
1155  return __str;
1156  }
1157 
1158  inline std::string
1159  path::generic_string() const { return generic_string<char>(); }
1160 
1161 #if _GLIBCXX_USE_WCHAR_T
1162  inline std::wstring
1163  path::generic_wstring() const { return generic_string<wchar_t>(); }
1164 #endif
1165 
1166 #ifdef _GLIBCXX_USE_CHAR8_T
1167  inline std::u8string
1168  path::generic_u8string() const { return generic_string<char8_t>(); }
1169 #else
1170  inline std::string
1171  path::generic_u8string() const { return generic_string<char>(); }
1172 #endif
1173 
1174  inline std::u16string
1175  path::generic_u16string() const { return generic_string<char16_t>(); }
1176 
1177  inline std::u32string
1178  path::generic_u32string() const { return generic_string<char32_t>(); }
1179 
1180  inline int
1181  path::compare(const string_type& __s) const { return compare(path(__s)); }
1182 
1183  inline int
1184  path::compare(const value_type* __s) const { return compare(path(__s)); }
1185 
1186 #if __cplusplus >= 201402L
1187  inline int
1188  path::compare(basic_string_view<value_type> __s) const
1189  { return compare(path(__s)); }
1190 #endif
1191 
1192  inline path
1193  path::filename() const { return empty() ? path() : *--end(); }
1194 
1195  inline path
1196  path::stem() const
1197  {
1198  auto ext = _M_find_extension();
1199  if (ext.first && ext.second != 0)
1200  return path{ext.first->substr(0, ext.second)};
1201  return {};
1202  }
1203 
1204  inline path
1205  path::extension() const
1206  {
1207  auto ext = _M_find_extension();
1208  if (ext.first && ext.second != string_type::npos)
1209  return path{ext.first->substr(ext.second)};
1210  return {};
1211  }
1212 
1213  inline bool
1214  path::has_stem() const
1215  {
1216  auto ext = _M_find_extension();
1217  return ext.first && ext.second != 0;
1218  }
1219 
1220  inline bool
1221  path::has_extension() const
1222  {
1223  auto ext = _M_find_extension();
1224  return ext.first && ext.second != string_type::npos;
1225  }
1226 
1227  inline bool
1228  path::is_absolute() const
1229  {
1230 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
1231  return has_root_name() && has_root_directory();
1232 #else
1233  return has_root_directory();
1234 #endif
1235  }
1236 
1237  inline path::iterator
1238  path::begin() const
1239  {
1240  if (_M_type == _Type::_Multi)
1241  return iterator(this, _M_cmpts.begin());
1242  return iterator(this, false);
1243  }
1244 
1245  inline path::iterator
1246  path::end() const
1247  {
1248  if (_M_type == _Type::_Multi)
1249  return iterator(this, _M_cmpts.end());
1250  return iterator(this, true);
1251  }
1252 
1253  inline path::iterator&
1254  path::iterator::operator++()
1255  {
1256  __glibcxx_assert(_M_path != nullptr);
1257  if (_M_path->_M_type == _Type::_Multi)
1258  {
1259  __glibcxx_assert(_M_cur != _M_path->_M_cmpts.end());
1260  ++_M_cur;
1261  }
1262  else
1263  {
1264  __glibcxx_assert(!_M_at_end);
1265  _M_at_end = true;
1266  }
1267  return *this;
1268  }
1269 
1270  inline path::iterator&
1271  path::iterator::operator--()
1272  {
1273  __glibcxx_assert(_M_path != nullptr);
1274  if (_M_path->_M_type == _Type::_Multi)
1275  {
1276  __glibcxx_assert(_M_cur != _M_path->_M_cmpts.begin());
1277  --_M_cur;
1278  }
1279  else
1280  {
1281  __glibcxx_assert(_M_at_end);
1282  _M_at_end = false;
1283  }
1284  return *this;
1285  }
1286 
1287  inline path::iterator::reference
1289  {
1290  __glibcxx_assert(_M_path != nullptr);
1291  if (_M_path->_M_type == _Type::_Multi)
1292  {
1293  __glibcxx_assert(_M_cur != _M_path->_M_cmpts.end());
1294  return *_M_cur;
1295  }
1296  return *_M_path;
1297  }
1298 
1299  inline bool
1300  path::iterator::_M_equals(iterator __rhs) const
1301  {
1302  if (_M_path != __rhs._M_path)
1303  return false;
1304  if (_M_path == nullptr)
1305  return true;
1306  if (_M_path->_M_type == path::_Type::_Multi)
1307  return _M_cur == __rhs._M_cur;
1308  return _M_at_end == __rhs._M_at_end;
1309  }
1310 
1311  // Define these now that path and path::iterator are complete.
1312  // They needs to consider the string_view(Range&&) constructor during
1313  // overload resolution, which depends on whether range<path> is satisfied,
1314  // which depends on whether path::iterator is complete.
1315  inline bool operator<(const path& __lhs, const path& __rhs) noexcept
1316  { return __lhs.compare(__rhs) < 0; }
1317 
1318  inline bool operator==(const path& __lhs, const path& __rhs) noexcept
1319  { return __lhs.compare(__rhs) == 0; }
1320 
1321  /// @} group filesystem-ts
1322 _GLIBCXX_END_NAMESPACE_CXX11
1323 } // namespace v1
1324 } // namespace filesystem
1325 } // namespace experimental
1326 
1327 _GLIBCXX_END_NAMESPACE_VERSION
1328 } // namespace std
1329 
1330 #endif // C++11
1331 
1332 #endif // _GLIBCXX_EXPERIMENTAL_FS_PATH_H
constexpr duration< __common_rep_t< _Rep2, _Rep1 >, _Period > operator*(const _Rep1 &__s, const duration< _Rep2, _Period > &__d)
Definition: chrono:700
constexpr complex< _Tp > operator/(const complex< _Tp > &__x, const complex< _Tp > &__y)
Return new complex value x divided by y.
Definition: complex:422
integral_constant< bool, true > true_type
The type used as a compile-time boolean with true value.
Definition: type_traits:83
integral_constant< bool, false > false_type
The type used as a compile-time boolean with false value.
Definition: type_traits:86
constexpr _Tp * __addressof(_Tp &__r) noexcept
Same as C++11 std::addressof.
Definition: move.h:49
constexpr std::remove_reference< _Tp >::type && move(_Tp &&__t) noexcept
Convert a value to an rvalue.
Definition: move.h:104
void swap(any &__x, any &__y) noexcept
Exchange the states of two any objects.
Definition: any:428
_Tp * end(valarray< _Tp > &__va) noexcept
Return an iterator pointing to one past the last element of the valarray.
Definition: valarray:1239
_Tp * begin(valarray< _Tp > &__va) noexcept
Return an iterator pointing to the first element of the valarray.
Definition: valarray:1217
basic_string< char > string
A string of char.
Definition: stringfwd.h:74
basic_string< char32_t > u32string
A string of char32_t.
Definition: stringfwd.h:96
basic_string< char16_t > u16string
A string of char16_t.
Definition: stringfwd.h:93
basic_string< wchar_t > wstring
A string of wchar_t.
Definition: stringfwd.h:83
ISO C++ entities toplevel namespace is std.
std::basic_istream< _CharT, _Traits > & operator>>(std::basic_istream< _CharT, _Traits > &__is, bitset< _Nb > &__x)
Global I/O operators for bitsets.
Definition: bitset:1472
std::basic_ostream< _CharT, _Traits > & operator<<(std::basic_ostream< _CharT, _Traits > &__os, const bitset< _Nb > &__x)
Global I/O operators for bitsets.
Definition: bitset:1540
constexpr auto empty(const _Container &__cont) noexcept(noexcept(__cont.empty())) -> decltype(__cont.empty())
Return whether a container is empty.
Definition: range_access.h:263
A non-owning reference to a string.
Definition: string_view:99
An exception type that includes an error_code value.
Definition: system_error:447
integral_constant
Definition: type_traits:66
is_same
Definition: type_traits:1410
is_base_of
Definition: type_traits:1423
Define a member typedef type only if a boolean constant is true.
Definition: type_traits:2194
void push_back(_CharT __c)
Append a single character.
const _CharT * c_str() const noexcept
Return const pointer to null-terminated contents.
void reserve(size_type __res_arg)
Attempt to preallocate enough memory for specified number of characters.
size_type size() const noexcept
Returns the number of characters in the string, not including any null-termination.
const _CharT * data() const noexcept
Return const pointer to contents.
basic_string & append(const basic_string &__str)
Append a string to this string.
void clear() noexcept
bool empty() const noexcept
reference back()
static const size_type npos
Value returned by various member functions when they fail.
Primary class template codecvt.
Definition: codecvt.h:279
Traits class for iterators.
Container class for localization functionality.
Struct for delimited strings.
Definition: quoted_string.h:50
Marking input iterators.
Bidirectional iterators support a superset of forward iterator operations.
Common iterator class.
Struct holding two objects of arbitrary type.
Definition: stl_pair.h:213
iterator begin() noexcept
Definition: stl_vector.h:811
iterator end() noexcept
Definition: stl_vector.h:829
Exception type thrown by the Filesystem TS library.
A non-owning reference to a string.