As a user of the filesystem library, I am having the experience that
obvious things are hard to find, and the docs are much harder to
understand than they ought to be. The use of creative naming really
gets in the way. For example, the term "complete" is never defined
anywhere. The closest we come is in the following naming rationale.
is_complete
bool is_complete() const;
Returns: For single-root operating systems,
has_root_directory(). For multi-root operating systems,
has_root_directory() && has_root_name().
Naming rationale: The alternate name, is_absolute(), causes
confusion and controversy because on multi-root operating systems
some people believe root_name() should participate in
is_absolute(), and some don't.
I'm sorry if this sounds harsh, but I think the cure for someone being
confused about the term "absolute" on multi-root OSes is to pick the
definition that allows the term to be meaningful (an absolute path
identifies a specific location, and so must include the root) and *add
a clarifying note or definition for the corner case*, not to pick some
new term which nobody knows about and makes the library hard to
approach.
--- aside ---
Regarding complete paths, is there any guarantee that they are
canonical? Is foo/bar/../baz reduced to foo/baz? See
http://java.sun.com/j2se/1.3/docs/api/java/io/File.html#getCanonicalPath()
for an example of the possible semantics. We could learn a lot about
what's useful and broadly implementable by studying the libraries of
Java and/or Python (yes, I realize that the portability of Java ain't
quite what it's cracked up to be).
--- aside ---
The formal description of some of the function semantics leaves
something to be desired. For example, the docs for remove_all say:
unsigned long remove_all( const path & ph );
Precondition: !ph.empty()
Postcondition: !exists( ph )
Returns: The number of files and directories removed.
Throws: if ph.empty(). See empty path rationale.
So, what does this do? At first I thought it removed all the
directories along the branch described by ph. I think I'm now
inferring that if ph is a file, it is the same as remove( ph ) and
otherwise it removes all of the files and subdirectories in ph and
then removes ph. A plain English description would help a lot here.
This applies to many other functions in the library also.
I also have some doubts about the validity of the postcondition, since
another process can come along and create ph again before remove_all
returns. This applies to many other functions in the library also.
The difference between is_empty(ph) and ph.empty() is too slight, IMO,
for their differing semantics. IMO it's not useful to have one
function which reports both empty files and empty directories - the
implications of the two are much too different.
--
Dave Abrahams
Boost Consulting
www.boost-consulting.com
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
