Document number: | D????=12-???? |
Date: | 2012-06-02 |
Project: | Programming Language C++ |
Reply-to: | Beman Dawes <bdawes at acm dot org> |
This paper proposes a filesystem library component suitable for a C++ Standard Library Technical Specification or for the C++ Standard Library. The proposed library is based on Version 3 of the Boost Filesystem Library (see www.boost.org/libs/filesystem). Preliminary wording is provided. A TODO list identifies remaining work to be done.
Material in this document high-lighted in yellow is known to be incomplete, incorrect, or otherwise require further refinement.
D????=12-???? , Filesystem Library Proposal (Revision 3). Changes include:
N3365=12-0055, Filesystem Library Proposal (Revision 2). Changes include:
std::tbd::filesystem
per
issue
1 discussion in Kona.N3335=12-0025, Filesystem Library for C++11/TR2 (Revision 1). Changes include:
files
as an experiment. Made this
issue number 1 so the LWG can pass judgment.N3239 = 11-0009, Filesystem Library Update for TR2 (Preliminary), reflected changes made to the Boost library version 3 since the previously accepted committee paper:
path
handles all aspects of
internationalization, replacing the previous template and its path
and wpath
instantiations. Character types char
,
wchar_t
, char16_t
, and char32_t
are
supported. This is a major simplification of the path abstraction,
particularly for functions that take path arguments. This change was based
on a suggestion by Peter Dimov.error_code
is now uniform
throughout the operations functions.N1975 = 06-0045, Filesystem Library Proposal for TR2 (Revision 3), was adopted by the committee in April, 2006, at the Berlin meeting. Shortly afterward the Library Working Group set aside work on TR2 to concentrate on C++0x.
The motivation and scope for a filesystem library were described in N1975, and are not repeated here. A minor scope reduction is that an addition to the current C++ runtime library is no longer needed.
Boost Filesystem Version 3 introduced a single path type that interoperates well with both
basic_string
and user defined string types. Thus the following Design
alternatives paragraph is no long applicable:
Single path type which can at runtime accept narrow or wide character pathnames. Although certainly interesting, and possibly superior, such a design would not interoperate well with the current Standard Library's compile-time typedbasic_string
. A new runtime polymorphic string class would be the best place to experiment with this concept, not a path class.
char16_t
and char32_t
support to verify the
specification for these is correct.Source
is not specified as actually
implemented. Expose path_traits
?copy
and copy_directory
need to be reviewed, revised, tested, peer reviewed.time_t
to chrono system_clock::time_point
,
per LWG discussion in Kona. Gray-shaded italic text is commentary on the proposal. It is not to be added to the working paper.
This clause describes components that perform operations on file systems and their components, such as paths, regular files, and directories.
ISO/IEC 9945 contains provisions which, through reference in this text, constitute provisions of this clause. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this clause are encouraged to investigate the possibility of applying the most recent editions of the standard indicated below. Members of IEC and ISO maintain registers of currently valid International Standards.
ISO/IEC 9945:2003 is also IEEE Std 1003.1-2001, and The Open Group Base Specifications, Issue 6, and is also known as The Single Unix® Specification, Version 3. It is available from each of those organizations, and may be read online or downloaded from www.unix.org/single_unix_specification/
End of new Clause.
The N3335 proposal places the library in namespace std::tr2::files
.
Rationale for a sub-namespace is that the library uses several names that don't
seem appropriate for namespace tr2
since full standardization would
then put the names into std
. The function names remove
and rename
are of particular concern because these functions differ
in behavior from current standard library functions with those names. It also
doesn't seem desirable to preempt names like equivalent
and
status
.
Kona: Strong support for filesystem
as the library's
namespace. Strong support for a technical specification namespace that alerts uses that
contents are likely to change if and when they later get moved into the
standard.
No decision yet on a TR namespace; tbs
being used as
a placeholder. Thus the full namespace is changed to
std::tbs::filesystem.
const codecvt_type&
arguments
Status: OpenUsers sometimes need to do path conversions that use something other than the
imbued codecvt facet. The need is particularly acute in multi-threaded
applications where changing the imbued facet would introduce a data race. That
said, providing an optional const codecvt_type&
argument for every
function where the need might possibly arise is excessive because its use is so
rare and it adds considerable interface clutter.
Kona:
Remove all existing class path const codecvt_type&
arguments.
Beman to pursue separate encoding conversion functionality, per Thursday N3336 "Adapting standard library strings and IO to a Unicode World" discussion. See Kona wiki.
If a separate encoding conversion facility isn't possible, then some form of minimal class path encoding conversion facility will be needed. But..., the LWG would like to see use cases and clearer explanation of motivation before deciding on specifics, and be very sure that there is no way to achieve with existing std library functionality, albeit with some loss of efficiency.
In Bloomington there was discussion of "implicit cast to implicit cast to native OS type to inter operate with existing iostream library and native functions instead of modifying fstream".
Kona: The Dinkumware/Microsoft implementation has added an implicit conversion to the string type, eliminating any need to modify fstream. (Discussion: might be safer to make the implicit conversion protected, then make fstream classes friends).
Action: Beman to investigate, test, as avoiding modification of existing header and classes is much desired.
The issue title pretty much says it all.
Kona: Return plain strings. Remove the permission for implementations to return const refs, since uses are not in performace critical code and subtle portability bugs may occur.
Action: Beman to apply to proposed wording.
Version 3: Resolution applied.
Question raised by Pablo in Bloomington.
Beman suggests NAD, Future. I've done some work on this, including looking at systems like OpenVMS that have an escape mechanism to handle otherwise unrepresentable characters. There was a comment to that effect in N3239. I believe it should be deferred to some future release since (1) it is complex enough that I'd like to see actual implementation and use experience (presumably via Boost), and (2) I can't recall a user ever requesting such a feature.
Kona: No consensus for change, since there doesn't appear to be any compelling use case.
Question raised by a committee member in private email.
Kona: Much discussion.
Action: Alisdair to write paper, based on a real implementation, so that it is possible to assess the impact on interface, performance, etc.
Post-Kona: Alisdair will defer paper until after TR.
Class path
currently is specified to used the Boost detail
quoted
stream manipulator. A path object is inserted delimited by quotes,
and extracted accordingly, ensuring that paths containing spaces are
round-tripped correctly. Quotes in the path itself are escaped, and io
state is saved and restored.
See http://www.boost.org/doc/libs/1_48_0/libs/io/doc/quoted_manip.html
Since the standard can't specify behavior in terms of something in Boost, we
have to change the specification. Since the quoted
stream
manipulator is a handy little component, the issue is raised as to whether it
should go in TR2.
Kona: Specify the path inserter and extractor to have the desired behavior without reference to how it is achieved. (If someone wants to propose a quoted manipulator, that's a separate proposal for a different TR.)
Action: Beman to apply to proposed wording.
Version 3: Resolution applied.
rename
Status: NewThere are minor problems with the name of the rename()
function:
Change the name of the rename()
function to move()
.
$endid $id backmatter= $endid