Module path [Version: ]
[Main Page] [Details] [Tests]
This documentation describes the Prokee module interface.
Templates
Show templates with parameter T set to: (
T) -- (
char) -- (
wchar_t)
Static Template Methods:
pathtype
pathtype (version 6)
int path::pathtype(const char *path,const char *dirsep,const char *labelsep,const char *rootsym)
onopath
fnopath
dnopath
pnopath
sxopath
sxopath (version 2)
const char *path::sxopath(const char *path,char dirsep,char labelsep,char susep)
sxopath (version 3)
const char *path::sxopath(const char *path,const char *dirsep,const char *labelsep,const char *susep)
sxopath (version 4)
const char *path::sxopath(const char *path,const char *dirsep,const char *labelsep,const char *susep,const char *rootsym)
pathcmp
compresspath
copy
copy (version 2)
bool path::copy(const char *targetpath,const char *sourcepath,const char *object)
copy (version 3)
bool path::copy(const char *targetpath,const char *sourcepath,CondCopyControl< char > *ccc)
copy (version 4)
bool path::copy(const char *targetpath,const char *sourcepath,const char *object,CondCopyControl< char > *ccc)
more
testpath
bool path::testpath(const char *path)
Motivation
This module provides functions for the manipulation of strings which contain paths. A path in this context is a description of the way from the root to a specific position within a hierarchic structure (like a tree). Paths can be paths within the local file system, but can also be used for any other structures. Paths do not have to correspond with the file system (or any other structure).
Syntax of Paths
There are five special characters used in paths:
|
|
examples
|
description
|
|
directory separator
|
/ (or \)
|
to separate two different named components (f.e. directory names), for file system paths typically / on linux or \ on Windows
|
|
label separator
|
:
|
normally a : character to mark the end of the label (like in C:/ or http://)
|
|
root symbol
|
/
|
normally the same as the directory separator
|
|
file extension point
|
.
|
the point used to mark the beginning of the file extension. (f.e. the point in info.txt)
|
|
|
.
|
|
You can define your own characters to be used instead of the suggestions above.
Syntax with optional components in brackets [...]:
path = [label:][/][object/[...]][object[.suffix]]
object = a sequence of any characters other than '/' and '\'.
label = a sequence of any characters other than '/', '\' and ':'.
suffix = a sequence of any characters other than '/', '\' and '.'.
Types of Paths
1) Paths may be categorized by the target where they are pointing to.
| target |
examples |
description |
| file |
C:/Users/peter/info.txt
/users/peter/info.txt
|
A path to a file is every path which is not considered pointing to a directory.
|
| directory |
C:/Users/peter/
/home/peter/
../test/
|
A path to a directory is a path which ends with a special character. F.e. the character / (or \\ on Windows) used for paths in file systems.
|
| label |
C:/
C:
http://
Extras Disk:
|
A label-path either points to the root directory of a labelled file system (C:/) or to the label itself (C:). But only paths which consist of only one named component (the name of the label) are considered a label-path. See remarks below.
|
Remarks: The functions only evaluate the structure of the string. There is no requirement, that the path matches to a given file system or any other structure to be a valid path. Furthermore paths are not analysed (simplified or expanded in any way) until this is absolutely necessary. Meaning for example the path
C:/users/../ points to the same directory as the path
C:/. But finding this equivalence of the two paths would require knowledge of the meaning of
../ as the parent directory. As long as we do not care about such meanings, or even if we deal with a file system or any other structure, where paths could be applied, we can not just simply assume such a meaning. Therefore
C:/users/../ and
C:/ are two different strings and also two different paths. And as a consequence, the path
C:/users/../ would be considered being a path to a directory (which is not the root directory) while
C:/ being a path to the root directory and being a label-path consisting of only the label and no other named components. In comparison the path
C:/users/../ is no label-path because it has three named components: '
C', '
users' and '
..'. You can use
compresspath() to simplify (compress) the path from
C:/users/../ into
C:/.
Labels:
A label can also be seen as the name of the optional top-level element of a path. For Windows file systems, labels are used to specify the device (or partition), f.e. C:\\. The label can also specify the name of the floppy disk (as on the Amiga) or something else depending on your application. The name of the path can be an arbitrary string which does not include any label-separator or directory-separator characters. The operating system may specify further restrictions on the naming of labels used in file systems. Unix file systems do not have label elements, as the topmost element is always root (/).
Duplication of special characters: In the example above: C:\\, the label-separator character is ':' and the directory-separator character is '\'. This path is equivalent to C:, without the directory separator. And multiple label- or directory separators are treated as one. Therefore the Path C:::\\\\\\ is also equivalent to C:\\.
2) Paths can either be absolute or relative.
An absolute path may either start with a label or with the directory-separator character (root / on Linux). All other paths are considered relative.
Examples of absolute paths:
C:
C:\\
C:\\Users\\
C:/Users/
/home/peter/info.txt
Examples of relative paths:
test/
./Users/
..\\Users\\
../peter/info.txt
3) Not implemented.
- There is no special treatment of the tilde '~'. Paths starting with the tilde (~/...) are considered as relative.
- There is no expansion of variables like in the path %USER%/..., where f.e. %USER% could stands for the path to the user directory of the current user.
- There is no differentiation between regular files or other types of files or links.
Static Template Methods
pathtype (version 1)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathtype (version 2)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path,int system)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| int | system | | Specifies the format of the path according to the operating system. Set this value to 1 for paths on Unix and 2 for paths on Windows files systems. |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathtype (version 3)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path,char dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathtype (version 4)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path,char dirsep,char labelsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
\n| char | labelsep | | The symbol used to mark the end of the label. |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathtype (version 5)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path,const char *dirsep,const char *labelsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
\n| const char * | labelsep | [IN] | The symbols used to mark the end of the label. |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathtype (version 6)
Determines if a string specifies an absolute or relative path and if it is a path to a file or a path to a directory. See section
Types of Paths for more information.
Signature:
int path::pathtype(const char *path,const char *dirsep,const char *labelsep,const char *rootsym)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
\n| const char * | labelsep | [IN] | The symbols used to mark the end of the label. |
\n| const char * | rootsym | [IN] | The symbols used for root. |
Return value:Returns the type of the path.
|
|
absolute path
|
relative path
|
|
file
|
1
|
0
|
|
directory
|
3
|
2
|
|
label
|
5 or 7
|
-
|
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
onopath (version 1)
Returns a pointer to the object the path points to. This is the last named component of the path.
Signature:
const char *path::onopath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the first character of the last named component within the path string.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
onopath (version 2)
Returns a pointer to the object the path points to. This is the last named component of the path.
Signature:
const char *path::onopath(const char *path,char dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
Return value:Returns a pointer to the first character of the last named component within the path string.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
onopath (version 3)
Returns a pointer to the object the path points to. This is the last named component of the path.
Signature:
const char *path::onopath(const char *path,const char *dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns a pointer to the first character of the last named component within the path string.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
fnopath (version 1)
Returns a pointer to the file-name the path points to.
Signature:
const char *path::fnopath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the first character of the file-name.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
fnopath (version 2)
Returns a pointer to the file-name the path points to.
Signature:
const char *path::fnopath(const char *path,char dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
Return value:Returns a pointer to the first character of the file-name.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
fnopath (version 3)
Returns a pointer to the file-name the path points to.
Signature:
const char *path::fnopath(const char *path,const char *dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns a pointer to the first character of the file-name.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
dnopath (version 1)
Returns the path to the directory the path points to. If the path is a path to a directory, this function returns a copy of the path. If it is a path to a file, the function returns the path to the directory of this file.
Signature:
char *path::dnopath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the directory.
Remarks:
The application has to free the returned buffer.
dnopath (version 2)
Returns the path to the directory the path points to. If the path is a path to a directory, this function returns a copy of the path. If it is a path to a file, the function returns the path to the directory of this file.
Signature:
char *path::dnopath(const char *path,char dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the directory.
Remarks: The application has to free the returned buffer.
dnopath (version 3)
Returns the path to the directory the path points to. If the path is a path to a directory, this function returns a copy of the path. If it is a path to a file, the function returns the path to the directory of this file.
Signature:
char *path::dnopath(const char *path,const char *dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the directory.
Remarks: The application has to free the returned buffer.
pnopath (version 1)
Returns the path to the parent directory.
Signature:
char *path::pnopath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the parent directory.
Remarks: The application has to free the returned buffer.
pnopath (version 2)
Returns the path to the parent directory.
Signature:
char *path::pnopath(const char *path,char dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the parent directory.
Remarks: The application has to free the returned buffer.
pnopath (version 3)
Returns the path to the parent directory.
Signature:
char *path::pnopath(const char *path,const char *dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns a pointer to the newly allocated buffer, that holds the path to the parent directory.
Remarks: The application has to free the returned buffer.
sxopath (version 1)
Returns a pointer to the file extension.
Signature:
const char *path::sxopath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the first character of the file-extension.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
sxopath (version 2)
Returns a pointer to the file extension.
Signature:
const char *path::sxopath(const char *path,char dirsep,char labelsep,char susep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| char | dirsep | | The symbol used to separate directory names. |
\n| char | labelsep | | The symbol used to mark the end of the label. |
\n| char | susep | | The symbol used to mark the beginning of the file extension. |
Return value:Returns a pointer to the first character of the file-extension.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
sxopath (version 3)
Returns a pointer to the file extension.
Signature:
const char *path::sxopath(const char *path,const char *dirsep,const char *labelsep,const char *susep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
\n| const char * | labelsep | [IN] | The symbols used to mark the end of the label. |
\n| const char * | susep | [IN] | The symbols used to mark the beginning of the file extension. |
Return value:Returns a pointer to the first character of the file-extension.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
sxopath (version 4)
Returns a pointer to the file extension.
Signature:
const char *path::sxopath(const char *path,const char *dirsep,const char *labelsep,const char *susep,const char *rootsym)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
\n| const char * | labelsep | [IN] | The symbols used to mark the end of the label. |
\n| const char * | susep | [IN] | The symbols used to mark the beginning of the file extension. |
\n| const char * | rootsym | [IN] | The symbols used for root. |
Return value:Returns a pointer to the first character of the file-extension.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
pathcmp (version 1)
Compares two pathes.
Signature:
bool path::pathcmp(const char *path_a,const char *path_b)
Parameters:| const char * | path_a | [IN] | The path (as null-terminated string). |
\n| const char * | path_b | [IN] | The path (as null-terminated string). |
Return value:Returns true, if both paths are identical, and otherwise false.
Required code:
function
matchsymbol from module
strman (version 1 - 0 -- default: )
compresspath (version 1)
Signature:
char *path::compresspath(char *path)
Parameters:| char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns a pointer to the compressed path.
compresspath (version 2)
Signature:
char *path::compresspath(char *path,const char *dirsep)
Parameters:| char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns a pointer to the compressed path.
copy (version 1)
Copies the content from sourcepath to targetpath.
Signature:
bool path::copy(const char *targetpath,const char *sourcepath)
Parameters:| const char * | targetpath | [IN] | The path (as null-terminated string). |
\n| const char * | sourcepath | [IN] | The path (as null-terminated string). |
Return value:Returns true, if successful and otherwise false.
Required code:
function
copyfile from module
file (version 1 - 0 -- default: )
function
copydir from module
dir (version 1 - 0 -- default: )
copy (version 2)
Copies the content from sourcepath to targetpath.
Signature:
bool path::copy(const char *targetpath,const char *sourcepath,const char *object)
Parameters:| const char * | targetpath | [IN] | The path (as null-terminated string). |
\n| const char * | sourcepath | [IN] | The path (as null-terminated string). |
\n| const char * | object | [IN] | The name of the object (as null-terminated string). |
Return value:Returns true, if successful and otherwise false.
Required code:
function
copyfile from module
file (version 1 - 0 -- default: )
function
copydir from module
dir (version 1 - 0 -- default: )
copy (version 3)
Copies the content from sourcepath to targetpath.
Signature:
bool path::copy(const char *targetpath,const char *sourcepath,CondCopyControl< char > *ccc)
Parameters:| const char * | targetpath | [IN] | The path (as null-terminated string). |
\n| const char * | sourcepath | [IN] | The path (as null-terminated string). |
\n| CondCopyControl< char > * | ccc | [IN] | Pointer to an instance of an implementation of CondCopyControl.
See file\:CondCopyControl. |
Return value:Returns true, if successful and otherwise false.
Required code:
function
copyfile from module
file (version 1 - 0 -- default: )
function
copydir from module
dir (version 1 - 0 -- default: )
copy (version 4)
Copies the content from sourcepath to targetpath.
Signature:
bool path::copy(const char *targetpath,const char *sourcepath,const char *object,CondCopyControl< char > *ccc)
Parameters:| const char * | targetpath | [IN] | The path (as null-terminated string). |
\n| const char * | sourcepath | [IN] | The path (as null-terminated string). |
\n| const char * | object | [IN] | The name of the object (as null-terminated string). |
\n| CondCopyControl< char > * | ccc | [IN] | Pointer to an instance of an implementation of CondCopyControl.
See file\:CondCopyControl. |
Return value:Returns true, if successful and otherwise false.
Required code:
function
copyfile from module
file (version 1 - 0 -- default: )
function
copydir from module
dir (version 1 - 0 -- default: )
makeabspath (version 1)
Constructs the absolute path.
Signature:
char *path::makeabspath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns the absolute path.
makeabspath (version 2)
Constructs the absolute path.
Signature:
char *path::makeabspath(const char *path,const char *cd)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | cd | [IN] | The current working directory (as null-terminated string). |
Return value:Returns the absolute path.
makeabspath (version 3)
Constructs the absolute path.
Signature:
char *path::makeabspath(const char *path,const char *cd,const char *dirsep)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
\n| const char * | cd | [IN] | The current working directory (as null-terminated string). |
\n| const char * | dirsep | [IN] | The symbols used to separate directory names. |
Return value:Returns the absolute path.
testpath
Tests if a path exists.
Signature:
bool path::testpath(const char *path)
Parameters:| const char * | path | [IN] | The path (as null-terminated string). |
Return value:Returns
true, if the path exists and
false otherwise.
Required code:
function
copyfile from module
file (version 1 - 0 -- default: )
function
copydir from module
dir (version 1 - 0 -- default: )
This documenta- tion describes the current state of development.
A
aprint