filesystem::filename Class Reference
Provides operations commonly needed on file names. More...
#include <filename.h>
Public Types | |
| enum | write_modes { ALLOW_NEITHER = 0x0, ALLOW_READ = 0x1, ALLOW_WRITE = 0x2, ALLOW_BOTH = ALLOW_READ | ALLOW_WRITE } |
| enum | ownership_modes { NO_RIGHTS = 0x0, USER_RIGHTS = 0x1, GROUP_RIGHTS = 0x2, OTHER_RIGHTS = 0x4, ALL_RIGHTS = USER_RIGHTS | GROUP_RIGHTS | OTHER_RIGHTS } |
| enum | directory_separator { pc_separator = '\\', unix_separator = '/' } |
the default separator for directories per operating system. More... | |
Public Member Functions | |
| filename () | |
| blank constructor. | |
| filename (const basis::astring &name) | |
| creates a filename from any part of a full pathname, if possible. | |
| filename (const basis::astring &directory, const basis::astring &name_of_file) | |
| constructs a filename from a "directory" and the "name_of_file". | |
| filename (const filename &to_copy) | |
| copy constructor. | |
| virtual | ~filename () |
| bool | good () const |
| returns true if the filename seems to be valid. | |
| const basis::astring & | raw () const |
| returns the astring that we're holding onto for the path. | |
| basis::astring & | raw () |
| accesses the astring that we're holding onto for the path. | |
| filename & | operator= (const filename &to_copy) |
| provides assignment for this object, plus a simple string. | |
| filename & | operator= (const basis::astring &to_copy) |
| provides assignment for this object, plus a simple string. | |
| void | canonicalize () |
| cleans up the filename as needed for the current operating system. | |
| bool | exists () const |
| returns true if the file exists. | |
| bool | unlink () const |
| actually removes the file, if possible. | |
| filename | parent () const |
| returns the parent filename for this one. | |
| basis::astring | pop () |
| removes the deepest component of the pathname. | |
| void | push (const basis::astring &to_push) |
| pushes a new filename onto the current pathname. | |
| filename | basename () const |
| returns the base of the filename; no directory. | |
| filename | dirname () const |
| returns the directory for the filename. | |
| basis::astring | dirname (bool add_slash) const |
| returns the directory for the filename and optionally adds a slash. | |
| bool | had_directory () const |
| returns true if the name that we were given had a non-empty directory. | |
| char | drive (bool interact_with_fs=false) const |
| returns the drive letter for the file, without the colon. | |
| basis::astring | extension () const |
| returns the extension for the file, if one is present. | |
| basis::astring | rootname () const |
| returns the root part of the basename without an extension. | |
| bool | is_directory () const |
| bool | is_writable () const |
| bool | is_readable () const |
| bool | is_executable () const |
| bool | chmod (int write_mode, int owner_mode) const |
| changes the access rights on the file. | |
| void | separate (structures::string_array &pieces) const |
| breaks the filename into its component directories. | |
| void | join (const structures::string_array &pieces) |
| undoes a separate() operation to get the filename back. | |
| virtual void | pack (basis::byte_array &packed_form) const |
| stores this string in the "target". it can later be unpacked again. | |
| virtual bool | unpack (basis::byte_array &packed_form) |
| retrieves a string (packed with pack()) from "source" into this string. | |
| virtual int | packed_size () const |
| Reports the size required to pack this string into a byte array. | |
| bool | compare_prefix (const filename &to_compare, basis::astring &sequel) |
| examines "this" filename to see if it's a prefix of "to_compare". | |
| bool | compare_prefix (const filename &to_compare) |
| this simpler form doesn't bother with computing the sequel. | |
| bool | compare_suffix (const filename &to_compare, basis::astring &prequel) |
| compares the back end of a filename to this. | |
| bool | compare_suffix (const filename &to_compare) |
Static Public Member Functions | |
| static bool | separator (char is_it) |
| returns true if the character "is_it" in question is a separator. | |
| static basis::astring | default_separator () |
| returns the default separator character for this OS. | |
| static bool | legal_character (char to_check) |
| returns true if "to_check" is a valid character in a filename. | |
| static void | detooth_filename (basis::astring &to_clean, char replacement= '_') |
| takes any known illegal file system characters out of "to_clean". | |
| static basis::astring | null_device () |
| returns the name for the black hole device that consumes all input, i.e. /dev/null. | |
Detailed Description
Provides operations commonly needed on file names.
Definition at line 48 of file filename.h.
Member Enumeration Documentation
the default separator for directories per operating system.
the PC uses the backward slash to separate file and directory names from each other, while Unix uses the forward slash.
Definition at line 162 of file filename.h.
Definition at line 150 of file filename.h.
Definition at line 144 of file filename.h.
Constructor & Destructor Documentation
| filesystem::filename::filename | ( | ) |
| filesystem::filename::filename | ( | const basis::astring & | name | ) |
creates a filename from any part of a full pathname, if possible.
if the name contains quotes, they are stripped out.
Definition at line 58 of file filename.cpp.
References canonicalize().
| filesystem::filename::filename | ( | const basis::astring & | directory, | |
| const basis::astring & | name_of_file | |||
| ) |
constructs a filename from a "directory" and the "name_of_file".
the "name_of_file" can itself be a directory.
Definition at line 63 of file filename.cpp.
References basis::astring::astring(), canonicalize(), filesystem::DEFAULT_SEPARATOR, basis::astring::end(), and filesystem::NO_PARENT_DEFAULT.
| filesystem::filename::filename | ( | const filename & | to_copy | ) |
| filesystem::filename::~filename | ( | ) | [virtual] |
Definition at line 87 of file filename.cpp.
Member Function Documentation
| filename filesystem::filename::basename | ( | ) | const |
returns the base of the filename; no directory.
Definition at line 279 of file filename.cpp.
References basis::astring::zap().
Referenced by extension(), processes::process_control::find_process_in_list(), main(), configuration::ini_configurator::name(), pop(), rootname(), and processes::process_entry::text_form().
| void filesystem::filename::canonicalize | ( | ) |
cleans up the filename as needed for the current operating system.
reforms the name by replacing any alternate directory separators with the operating system's preferred character.
Definition at line 147 of file filename.cpp.
References basis::astring::astring(), filesystem::DEFAULT_SEPARATOR, basis::astring::end(), basis::astring::length(), basis::astring::put(), separator(), and basis::astring::zap().
Referenced by filename(), and operator=().
| bool filesystem::filename::chmod | ( | int | write_mode, | |
| int | owner_mode | |||
| ) | const |
changes the access rights on the file.
Definition at line 510 of file filename.cpp.
References ALLOW_READ, ALLOW_WRITE, GROUP_RIGHTS, OTHER_RIGHTS, raw(), basis::astring::s(), and USER_RIGHTS.
| bool filesystem::filename::compare_prefix | ( | const filename & | to_compare | ) |
this simpler form doesn't bother with computing the sequel.
Definition at line 451 of file filename.cpp.
| bool filesystem::filename::compare_prefix | ( | const filename & | to_compare, | |
| basis::astring & | sequel | |||
| ) |
examines "this" filename to see if it's a prefix of "to_compare".
this returns true if all of "this" is the same as the first portion of "to_compare". that is, if "this" is a prefix of "to_compare", then true is returned. this will always fail if there are fewer components in "to_compare". it will always succeed if the two filenames are identical. on success, the "sequel" is set to the portion of "to_compare" that's not included in this filename.
Definition at line 433 of file filename.cpp.
References filesystem::DEFAULT_SEPARATOR, basis::astring::empty_string(), and basis::array< contents >::length().
Referenced by filesystem::directory_tree::jump_to(), and filesystem::directory_tree::seek().
| bool filesystem::filename::compare_suffix | ( | const filename & | to_compare | ) |
Definition at line 503 of file filename.cpp.
| bool filesystem::filename::compare_suffix | ( | const filename & | to_compare, | |
| basis::astring & | prequel | |||
| ) |
compares the back end of a filename to this.
this is similar to compare_prefix() but it checks to see if the back end of "this" filename is the same as "to_compare". if "this" is longer than "to_compare", then failure occurs. only if all of the bits in "this" are seen in the back of "to_compare" is true returned.
Definition at line 486 of file filename.cpp.
References filesystem::DEFAULT_SEPARATOR, basis::astring::empty_string(), and basis::array< contents >::length().
| astring filesystem::filename::default_separator | ( | ) | [static] |
returns the default separator character for this OS.
Definition at line 89 of file filename.cpp.
References basis::astring::astring(), and filesystem::DEFAULT_SEPARATOR.
Referenced by filesystem::directory_tree::compare_trees(), filesystem::directory_tree::jump_to(), and filesystem::directory_tree::seek().
| void filesystem::filename::detooth_filename | ( | basis::astring & | to_clean, | |
| char | replacement = '_' | |||
| ) | [static] |
takes any known illegal file system characters out of "to_clean".
this prepares "to_clean" for use as a component in a larger filename by ensuring that the file system will not reject the name (as long as a suitable directory path is prepended to the name and permissions allow the file to be created or accessed). the "replacement" is used as the character that is substituted instead of illegal characters.
Definition at line 347 of file filename.cpp.
References legal_character(), and basis::astring::length().
| astring filesystem::filename::dirname | ( | bool | add_slash | ) | const |
returns the directory for the filename and optionally adds a slash.
if "add_slash" is true, then the default directory separator will be present on the end of the string.
Definition at line 313 of file filename.cpp.
References filesystem::DEFAULT_SEPARATOR, dirname(), and raw().
| filename filesystem::filename::dirname | ( | ) | const |
returns the directory for the filename.
if no directory name can be found in the filename, then "." is returned.
Definition at line 287 of file filename.cpp.
References basis::astring::astring(), filesystem::DEFAULT_SEPARATOR, basis::astring::end(), filesystem::NO_PARENT_DEFAULT, and basis::astring::zap().
Referenced by filesystem::heavy_file_operations::copy_file(), dirname(), parent(), processes::process_entry::text_form(), versions::version_ini::write_assembly(), versions::version_ini::write_code(), filesystem::heavy_file_operations::write_file_chunk(), and versions::version_ini::write_rc().
| char filesystem::filename::drive | ( | bool | interact_with_fs = false |
) | const |
returns the drive letter for the file, without the colon.
this only makes sense for a fully qualified MS-DOS style name. if no drive letter is found, then '' is returned. if "interact_with_fs" is true, then the file system will be checked for the actual drive if no drive letter was found in the contents.
Definition at line 193 of file filename.cpp.
References basis::astring::length().
| bool filesystem::filename::exists | ( | ) | const |
returns true if the file exists.
byte_filer opened(observe(), "rb"); return opened.good();
Definition at line 320 of file filename.cpp.
References is_directory(), is_readable(), and basis::astring::length().
Referenced by filesystem::file_info::calculate(), filesystem::heavy_file_operations::copy_file(), find_unique_backup_name(), good(), application::launch_manager::launch_now(), filesystem::directory::recursive_create(), and filesystem::heavy_file_operations::write_file_chunk().
| astring filesystem::filename::extension | ( | ) | const |
returns the extension for the file, if one is present.
Definition at line 210 of file filename.cpp.
References basename(), basis::astring::end(), basis::astring::find(), basis::astring::length(), basis::negative(), raw(), and basis::astring::substring().
Referenced by main().
| bool filesystem::filename::good | ( | ) | const |
returns true if the filename seems to be valid.
this means that not only was the pathname parsed and found valid, but the file actually exists.
Definition at line 95 of file filename.cpp.
References exists().
Referenced by filesystem::directory_tree::add_path().
| bool filesystem::filename::had_directory | ( | ) | const [inline] |
returns true if the name that we were given had a non-empty directory.
this allows one to distinguish between a file with the current directory (.) attached and a file with no directory specified.
Definition at line 119 of file filename.h.
Referenced by configuration::application_configuration::get_cmdline_from_proc(), and configuration::ini_configurator::name().
| bool filesystem::filename::is_directory | ( | ) | const |
Definition at line 236 of file filename.cpp.
References S_IFDIR.
Referenced by filesystem::directory_tree::add_path(), exists(), filesystem::directory::recursive_create(), and filesystem::directory::rescan().
| bool filesystem::filename::is_executable | ( | ) | const |
Definition at line 260 of file filename.cpp.
References S_IEXEC.
| bool filesystem::filename::is_readable | ( | ) | const |
| bool filesystem::filename::is_writable | ( | ) | const |
Definition at line 244 of file filename.cpp.
References S_IWRITE.
Referenced by versions::version_ini::writable().
| void filesystem::filename::join | ( | const structures::string_array & | pieces | ) |
undoes a separate() operation to get the filename back.
"this" is set to a filename made from each of the "pieces". if there are any directory separators inside the pieces, then they will be removed by canonicalize().
Definition at line 397 of file filename.cpp.
References filesystem::DEFAULT_SEPARATOR, and basis::array< contents >::length().
Referenced by filesystem::directory_tree::compare_trees(), filesystem::directory_tree::jump_to(), and filesystem::directory::recursive_create().
| bool filesystem::filename::legal_character | ( | char | to_check | ) | [static] |
returns true if "to_check" is a valid character in a filename.
this does not consider separator characters; it only looks at the the name components. also, it is appropriate for the union of the operating systems we support.
Definition at line 331 of file filename.cpp.
Referenced by detooth_filename().
| astring filesystem::filename::null_device | ( | ) | [static] |
returns the name for the black hole device that consumes all input, i.e. /dev/null.
Definition at line 99 of file filename.cpp.
| filename & filesystem::filename::operator= | ( | const basis::astring & | to_copy | ) |
provides assignment for this object, plus a simple string.
the latter version invokes canonicalize to clean the string up.
Reimplemented from basis::astring.
Definition at line 119 of file filename.cpp.
References canonicalize().
provides assignment for this object, plus a simple string.
Definition at line 111 of file filename.cpp.
| void filesystem::filename::pack | ( | basis::byte_array & | target | ) | const [virtual] |
stores this string in the "target". it can later be unpacked again.
Reimplemented from basis::astring.
Reimplemented in filesystem::file_info.
Definition at line 360 of file filename.cpp.
References basis::attach().
Referenced by filesystem::filename_tree::pack().
| int filesystem::filename::packed_size | ( | ) | const [virtual] |
Reports the size required to pack this string into a byte array.
Reimplemented from basis::astring.
Reimplemented in filesystem::file_info.
Definition at line 355 of file filename.cpp.
References structures::PACKED_SIZE_INT32.
Referenced by filesystem::filename_tree::packed_size().
| filename filesystem::filename::parent | ( | ) | const |
returns the parent filename for this one.
Definition at line 140 of file filename.cpp.
References dirname().
Referenced by pop().
| astring filesystem::filename::pop | ( | ) |
removes the deepest component of the pathname.
the component might be a file or directory name, but popping beyond the top-level directory will not succeed. the returned string contains the component that was removed. it will be a blank string if nothing could be popped.
Definition at line 128 of file filename.cpp.
References basename(), basis::astring::equal_to(), filesystem::NO_PARENT_DEFAULT, parent(), and raw().
| void filesystem::filename::push | ( | const basis::astring & | to_push | ) |
pushes a new filename onto the current pathname.
this only makes sense as a real pathname if this is currently a directory name and the component "to_push" is a child of that directory (or one intends to create that component as a child). this is the opposite of pop.
Definition at line 142 of file filename.cpp.
References filename().
| astring & filesystem::filename::raw | ( | ) |
accesses the astring that we're holding onto for the path.
important note: if you change the string with this non-const raw() method, you MUST call canonicalize() on it again afterwards.
Definition at line 91 of file filename.cpp.
| const astring & filesystem::filename::raw | ( | ) | const |
returns the astring that we're holding onto for the path.
Definition at line 93 of file filename.cpp.
Referenced by filesystem::directory_tree::add_path(), configuration::application_configuration::application_configuration_file(), filesystem::heavy_file_operations::buffer_files(), filesystem::file_info::calculate(), filesystem::directory_tree::calculate(), filesystem::filename_list::calculate_progress(), chmod(), filesystem::directory_tree::compare_trees(), filesystem::heavy_file_operations::copy_file(), dirname(), extension(), filesystem::filename_list::find(), processes::process_control::find_process_in_list(), filesystem::directory_tree::jump_to(), filesystem::filename_list::locate(), main(), filesystem::filename_list::member(), filesystem::filename_list::member_with_state(), configuration::ini_configurator::name(), pop(), filesystem::directory::recursive_create(), filesystem::directory_tree::remove_path(), rootname(), filesystem::directory_tree::seek(), separate(), processes::process_entry::text_form(), filesystem::file_info::text_form(), filesystem::directory_tree::text_form(), versions::version_ini::write_assembly(), versions::version_ini::write_code(), and filesystem::heavy_file_operations::write_file_chunk().
| astring filesystem::filename::rootname | ( | ) | const |
returns the root part of the basename without an extension.
Definition at line 219 of file filename.cpp.
References basename(), basis::astring::end(), basis::astring::find(), basis::negative(), raw(), and basis::astring::substring().
Referenced by loggers::file_logger::log_file_for_app_name().
| void filesystem::filename::separate | ( | structures::string_array & | pieces | ) | const |
breaks the filename into its component directories.
this returns an array containing the component names. the last component, unless the filename held is actually a directory, should be the name of the file. if the first character is a directory, then the first component will be empty.
Definition at line 377 of file filename.cpp.
References basis::astring::empty_string(), basis::astring::length(), raw(), basis::array< contents >::reset(), and separator().
Referenced by filesystem::directory_tree::compare_trees(), and filesystem::directory::recursive_create().
| bool filesystem::filename::separator | ( | char | is_it | ) | [static] |
returns true if the character "is_it" in question is a separator.
Definition at line 108 of file filename.cpp.
References pc_separator, and unix_separator.
Referenced by canonicalize(), and separate().
| bool filesystem::filename::unlink | ( | ) | const |
actually removes the file, if possible.
if the file was successfully deleted, then true is returned.
Definition at line 97 of file filename.cpp.
References basis::astring::observe().
| bool filesystem::filename::unpack | ( | basis::byte_array & | source | ) | [virtual] |
retrieves a string (packed with pack()) from "source" into this string.
note that the string is grabbed from the array destructively; whatever portion of the byte array was used to store the string will be removed from the head of the array.
Reimplemented from basis::astring.
Reimplemented in filesystem::file_info.
Definition at line 366 of file filename.cpp.
References basis::detach(), and structures::unpack().
Referenced by filesystem::filename_tree::unpack(), and filesystem::file_info::unpack().
The documentation for this class was generated from the following files:
- /var/www/hoople2/source/core/library/filesystem/filename.h
- /var/www/hoople2/source/core/library/filesystem/filename.cpp
