Module path

[Main Page] [Details] [Tests]

This documentation describes the Prokee module interface.

Templates

Show templates with parameter T set to: (T) -- (char) -- (wchar_t)

Use the char - versions for ANSI and UTF-8 encoded Strings.
The wchar_t - versions are only available on Windows operating systems.

Static Template Methods:

pathtype

pathtype (version 1)
template< class T > int path::pathtype(const T *path)

pathtype (version 2)
template< class T > int path::pathtype(const T *path,int system)

pathtype (version 3)
template< class T > int path::pathtype(const T *path,T dirsep)

pathtype (version 4)
template< class T > int path::pathtype(const T *path,T dirsep,T labelsep)

pathtype (version 5)
template< class T > int path::pathtype(const T *path,const T *dirsep,const T *labelsep)

pathtype (version 6)
template< class T > int path::pathtype(const T *path,const T *dirsep,const T *labelsep,const T *rootsym)

onopath

onopath (version 1)
template< class T > const T *path::onopath(const T *path)

onopath (version 2)
template< class T > const T *path::onopath(const T *path,T dirsep)

onopath (version 3)
template< class T > const T *path::onopath(const T *path,const T *dirsep)

fnopath

fnopath (version 1)
template< class T > const T *path::fnopath(const T *path)

fnopath (version 2)
template< class T > const T *path::fnopath(const T *path,T dirsep)

fnopath (version 3)
template< class T > const T *path::fnopath(const T *path,const T *dirsep)

dnopath

dnopath (version 1)
template< class T > T *path::dnopath(const T *path)

dnopath (version 2)
template< class T > T *path::dnopath(const T *path,T dirsep)

dnopath (version 3)
template< class T > T *path::dnopath(const T *path,const T *dirsep)

pnopath

pnopath (version 1)
template< class T > T *path::pnopath(const T *path)

pnopath (version 2)
template< class T > T *path::pnopath(const T *path,T dirsep)

pnopath (version 3)
template< class T > T *path::pnopath(const T *path,const T *dirsep)

sxopath

sxopath (version 1)
template< class T > const T *path::sxopath(const T *path)

sxopath (version 2)
template< class T > const T *path::sxopath(const T *path,T dirsep,T labelsep,T susep)

sxopath (version 3)
template< class T > const T *path::sxopath(const T *path,const T *dirsep,const T *labelsep,const T *susep)

sxopath (version 4)

template< class T > const T *path::sxopath(const T *path,const T *dirsep,const T *labelsep,const T *susep,const T *rootsym)

pathcmp

pathcmp (version 1)
template< class T > bool path::pathcmp(const T *path_a,const T *path_b)

compresspath

compresspath (version 1)
template< class T > T *path::compresspath(T *path)

compresspath (version 2)
template< class T > T *path::compresspath(T *path,const T *dirsep)

copy

copy (version 1)
template< class T > bool path::copy(const T *targetpath,const T *sourcepath)

copy (version 2)
template< class T > bool path::copy(const T *targetpath,const T *sourcepath,const T *object)

copy (version 3)
template< class T > bool path::copy(const T *targetpath,const T *sourcepath,CondCopyControl< T > *ccc)

copy (version 4)
template< class T > bool path::copy(const T *targetpath,const T *sourcepath,const T *object,CondCopyControl< T > *ccc)

makeabspath (version 1)
template< class T > T *path::makeabspath(const T *path)

makeabspath (version 2)
template< class T > T *path::makeabspath(const T *path,const T *cd)

makeabspath (version 3)
template< class T > T *path::makeabspath(const T *path,const T *cd,const T *dirsep)

testpath
template< class T > bool path::testpath(const T *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:

template< class T > int path::pathtype(const T *path)

Parameters:

const T *

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)

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:

template< class T > int path::pathtype(const T *path,int system)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
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)

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:

template< class T > int path::pathtype(const T *path,T dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
T	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)

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:

template< class T > int path::pathtype(const T *path,T dirsep,T labelsep)

Parameters:
\n\n

const T *	path	[IN]	The path (as null-terminated string).
T	dirsep		The symbol used to separate directory names.
T	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)

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:

template< class T > int path::pathtype(const T *path,const T *dirsep,const T *labelsep)

Parameters:
\n\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	dirsep	[IN]	The symbols used to separate directory names.
const T *	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)

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:

template< class T > int path::pathtype(const T *path,const T *dirsep,const T *labelsep,const T *rootsym)

Parameters:
\n\n\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	dirsep	[IN]	The symbols used to separate directory names.
const T *	labelsep	[IN]	The symbols used to mark the end of the label.
const T *	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)

onopath (version 1)

Returns a pointer to the object the path points to. This is the last named component of the path.

Signature:

template< class T > const T *path::onopath(const T *path)

Parameters:

const T *

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)

onopath (version 2)

Returns a pointer to the object the path points to. This is the last named component of the path.

Signature:

template< class T > const T *path::onopath(const T *path,T dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
T	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)

onopath (version 3)

Returns a pointer to the object the path points to. This is the last named component of the path.

Signature:

template< class T > const T *path::onopath(const T *path,const T *dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	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)

fnopath (version 1)

Returns a pointer to the file-name the path points to.

Signature:

template< class T > const T *path::fnopath(const T *path)

Parameters:

const T *

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)

fnopath (version 2)

Returns a pointer to the file-name the path points to.

Signature:

template< class T > const T *path::fnopath(const T *path,T dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
T	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)

fnopath (version 3)

Returns a pointer to the file-name the path points to.

Signature:

template< class T > const T *path::fnopath(const T *path,const T *dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	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)

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:

template< class T > T *path::dnopath(const T *path)

Parameters:

const T *

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)

template< class T > T *path::dnopath(const T *path,T dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
T	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)

template< class T > T *path::dnopath(const T *path,const T *dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	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:

template< class T > T *path::pnopath(const T *path)

Parameters:

const T *

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:

template< class T > T *path::pnopath(const T *path,T dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
T	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:

template< class T > T *path::pnopath(const T *path,const T *dirsep)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	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:

template< class T > const T *path::sxopath(const T *path)

Parameters:

const T *

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)

sxopath (version 2)

Returns a pointer to the file extension.

Signature:

template< class T > const T *path::sxopath(const T *path,T dirsep,T labelsep,T susep)

Parameters:
\n\n\n

const T *	path	[IN]	The path (as null-terminated string).
T	dirsep		The symbol used to separate directory names.
T	labelsep		The symbol used to mark the end of the label.
T	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)

sxopath (version 3)

Returns a pointer to the file extension.

Signature:

template< class T > const T *path::sxopath(const T *path,const T *dirsep,const T *labelsep,const T *susep)

Parameters:
\n\n\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	dirsep	[IN]	The symbols used to separate directory names.
const T *	labelsep	[IN]	The symbols used to mark the end of the label.
const T *	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)

sxopath (version 4)

Returns a pointer to the file extension.

Signature:

template< class T > const T *path::sxopath(const T *path,const T *dirsep,const T *labelsep,const T *susep,const T *rootsym)

Parameters:
\n\n\n\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	dirsep	[IN]	The symbols used to separate directory names.
const T *	labelsep	[IN]	The symbols used to mark the end of the label.
const T *	susep	[IN]	The symbols used to mark the beginning of the file extension.
const T *	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)

pathcmp (version 1)

Compares two pathes.

Signature:

template< class T > bool path::pathcmp(const T *path_a,const T *path_b)

Parameters:
\n

const T *	path_a	[IN]	The path (as null-terminated string).
const T *	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)

compresspath (version 1)

Signature:

template< class T > T *path::compresspath(T *path)

Parameters:

T *

path

[IN]

The path (as null-terminated string).

Return value:
Returns a pointer to the compressed path.

compresspath (version 2)

Signature:

template< class T > T *path::compresspath(T *path,const T *dirsep)

Parameters:
\n

T *	path	[IN]	The path (as null-terminated string).
const T *	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:

template< class T > bool path::copy(const T *targetpath,const T *sourcepath)

Parameters:
\n

const T *	targetpath	[IN]	The path (as null-terminated string).
const T *	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)
function copydir from module dir (version 1 - 0)

copy (version 2)

Copies the content from sourcepath to targetpath.

Signature:

template< class T > bool path::copy(const T *targetpath,const T *sourcepath,const T *object)

Parameters:
\n\n

const T *	targetpath	[IN]	The path (as null-terminated string).
const T *	sourcepath	[IN]	The path (as null-terminated string).
const T *	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)
function copydir from module dir (version 1 - 0)

copy (version 3)

Copies the content from sourcepath to targetpath.

Signature:

template< class T > bool path::copy(const T *targetpath,const T *sourcepath,CondCopyControl< T > *ccc)

Parameters:
\n\n

const T *	targetpath	[IN]	The path (as null-terminated string).
const T *	sourcepath	[IN]	The path (as null-terminated string).
CondCopyControl< T > *	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)
function copydir from module dir (version 1 - 0)

copy (version 4)

Copies the content from sourcepath to targetpath.

Signature:

template< class T > bool path::copy(const T *targetpath,const T *sourcepath,const T *object,CondCopyControl< T > *ccc)

Parameters:
\n\n\n

const T *	targetpath	[IN]	The path (as null-terminated string).
const T *	sourcepath	[IN]	The path (as null-terminated string).
const T *	object	[IN]	The name of the object (as null-terminated string).
CondCopyControl< T > *	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)
function copydir from module dir (version 1 - 0)

makeabspath (version 1)

Constructs the absolute path.

Signature:

template< class T > T *path::makeabspath(const T *path)

Parameters:

const T *

path

[IN]

The path (as null-terminated string).

Return value:
Returns the absolute path.

makeabspath (version 2)

Constructs the absolute path.

Signature:

template< class T > T *path::makeabspath(const T *path,const T *cd)

Parameters:
\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	cd	[IN]	The current working directory (as null-terminated string).

Return value:
Returns the absolute path.

makeabspath (version 3)

Constructs the absolute path.

Signature:

template< class T > T *path::makeabspath(const T *path,const T *cd,const T *dirsep)

Parameters:
\n\n

const T *	path	[IN]	The path (as null-terminated string).
const T *	cd	[IN]	The current working directory (as null-terminated string).
const T *	dirsep	[IN]	The symbols used to separate directory names.

Return value:
Returns the absolute path.

testpath

Tests if a path exists.

Signature:

template< class T > bool path::testpath(const T *path)

Parameters:

const T *

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)
function copydir from module dir (version 1 - 0)