Re: [boost] [filesystem] Function name changes

From: David Abrahams (dave_at_[hidden])
Date: 2008-07-03 13:36:18

Beman Dawes wrote:
> All the changes mentioned below leave the current names in place as
> synonyms, so will break no existing code.
> 
> * Change is_regular() to is_regular_file().
> 
> Dave Abrahams and several other people, including me, have found that
> the name of the is_regular() function is too obscure. It was chosen over
> is_regular_file() for brevity, but isn't holding up well with
> experience. The status name is already "regular_file" and the term
> "regular file" is used by the POSIX standard.
> 
> * Change leaf() to base_name().
> * Change branch() to base_path().

What does the latter do, again?  Oh, yeah, it returns the path to the
directory containing the file indicated by the path object.

I'm sorry, but I don't like base_path() much.  We know it is going to
return a path, so the "path" part of the name doesn't tell me much about
what this function does.  The only thing left to go on is the meaning of
"base."

Well I'm afraid we don't know what that is.  The (only) good reason to
use base_name() is that there is precedent; it's not because it makes
particularly "good sense." You yourself find it counterintuitive, IIUC.
 If "base" _did_ make any sense, I would guess that base_path() was the
identity function.

How about parent_directory(), containing_directory(), container_path(),
container(), or parent()?

> In the long thread '[filesystem] "leaf"', several people found the
> current names obscure or invoking the wrong metaphor. Many alternative
> names were discussed, with an eye to making the names more obvious,
> conforming to names such as "basename" used in other programming
> languages, and/or using names already in use by the STL.  Not breaking
> existing code was also a major concern, given that "basename" is already
> used in Boost.Filesystem.
> 
> The mental model for the new names is that for a path, p:
> 
>    p == p.base_path() / p.base_name()
> 
> Thus if p == "foo/bar/boo.txt", p.base_path() == "foo/bar", and
> p.base_name() == "boo.txt".
> 
> * Change basename() to base_name_prefix().
> * Change to extension() to base_name_extension().
> 
> This change is to avoid confusion with base_name().

Works for me.

> The mental model for the new name is that for a path, p:
> 
>    p.base_name() == base_name_prefix(p) + base_name_extension(p)
> 
> Thus if p == "foo/bar/boo.txt", base_name_prefix(p) == "boo", and
> base_name_extension(p) == ".txt".
> 
> Comments?

I worry a bit about the chance of silent misbehavior due to
basename/base_name spelling errors, and about what happens when both
names make it into the same codebase.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com