Document number: | N3335=12-0025 |
Date: | 2012-01-13 |
Project: | Programming Language C++, Library Working Group |
Reply-to: | Beman Dawes <bdawes at acm dot org> |
This paper proposes that the filesystem library component of C++ Standard Library Technical Report 2 be 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.
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 judgement.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.boost::io::quoted
.Source
is not specified as actually
implemented. Expose path_traits
?copy
and copy_directory
need to be reviewed, revised, tested, peer reviewed.Gray-shaded italic text is commentary on the proposal. It is not to be added to the TR.
Add the following to the Technical Report's front matter:
The following standard contains provisions which, through reference in this text, constitute provisions of this Technical Report. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this Technical Report 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.
[Note: 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 Unix2 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 note]
ISO/IEC 9945:2003, with the indicated corrections, is hereinafter called POSIX.
Footnote 1: POSIX® is a registered trademark of The IEEE.
Footnote 2: UNIX® is a registered trademark of The Open Group.
Add the following to the Technical Report as a new Clause:
End of new Clause.
Modify File streams [fstreams] as follows:
To class basic_filebuf public members add:
basic_filebuf<charT,traits>* open(const path& p, std::ios_base::openmode mode);
To class basic_ifstream public members add:
explicit basic_ifstream(const path& p, std::ios_base::openmode mode=std::ios_base::in)void open(const path& p, std::ios_base::openmode mode=std::ios_base::in);
To class basic_ofstream public members add:
explicit basic_ofstream(const path& p, std::ios_base::openmode mode=std::ios_base::out);void open(const path& p, std::ios_base::openmode mode=std::ios_base::out);
To class basic_fstream public members add:
explicit basic_fstream(const path& p, std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);void open(const path& p, std::ios_base::openmode mode=std::ios_base::in | std::ios_base::out);
End of proposed wording.
The proposal places the library in namespace std::tr2::$SUBNAMESPACE;
.
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
.
The Boost Filesystem library used namespace boost::filesystem
,
but that always seemed a bit too long.
Status quo. Leave in namespace std::tr2::$SUBNAMESPACE;
.
const codecvt_type&
argumentsUsers 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.
Remove all existing class path const codecvt_type&
arguments.
Add an additional non-member function:
unspecified-iterator-type convert(const path& p, const codecvt_type& codecvt
);Returns: An unspecified iterator type whose value type is
path::value_type
. The returned iterator points to the beginning of a sequence equivalent top.native()
with encoding as specified bycodecvt
.
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".
Beman comments: I wasn't in Bloomington and am not sure of the context of the above. N3239 inadvertently included the Boost docs for <fstream> rather than suggested <fstream> changes for TR2, and that may have caused some confusion. Or maybe I'm just missing something from the wiki notes. Some further discussions are needed to better define the issue.
The issue title pretty much says it all.
As part of the C++11 refinements to the interface, review returns of const strings and change to plain strings where appropriate.
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.
Question raised by a committee member in private email.
Comment from Beman: How would allocator support work, given that class path is not a template?
$endid $id backmatter= $endid