Description:

This class builds on ALib type StringTree. The contained elements (tree nodes) are of typeFInfo and represent entries in filesystems. Usually the tree is filled using function ScanFiles.

StringTree Interface

Public base class StringTree provides all interfaces necessary to create and delete entries, iterate and recursively walk the file tree. Please consult its documentation for further information.

Note: As documented with function ScanFiles, entities of this module ALib Files exclusively store entries along their "Real Path", hence always resolving symbolic links. A user of this library may deviate from this "data contract".

Class File

The base classes' method StringTree::Root is overloaded by this class and returns an instance of class File instead of an instance of class alib{containers;StringTree::Cursor}. This class can be turned into a cursor using AsCursor and then used to navigate through the tree. Then, the cursor can be cast back (or assigned) to a File instance.

Monotonic Behavior

The class fulfills weak monotonic allocation requirements, which is achieved by recycling not only the nodes (what base type StringTree does by default) but also any extended node information. This is implemented with the StringTree handler-type detail::FTreeNodeHandler on the one hand, and on the other hand, with the implementation of the method AllocateExtendedInfo, which has to be exclusively used to attach information structs on FInfo elements.
Furthermore, class File (the nodes of the tree) provides method AttachCustomData, which likewise uses the internal pool-allocator.

In summary, this allows an indefinite sequence of file-scan and result filtering (deletions) with using more memory than the highest resulting fill state in such sequence requires.

Definition at line 165 of file ftree.hpp.

#include <ftree.hpp>

Inheritance diagram for FTree:

[legend]

Collaboration diagram for FTree:

[legend]

Inner Type Index:
struct	ListenerRecord
	Record used to manage registered listeners. More...

Public Static Method Index:
static ALIB_API void	FixSums (Cursor directory)

Public Field Index:
PoolAllocator	Pool

Public Method Index:
ALIB_API	FTree (MonoAllocator &allocator)

ALIB_API	~FTree ()
	Destructor.

void	AllocateExtendedInfo (Cursor &node, const lang::system::PathString &symLinkDest, const lang::system::PathString &symLinkRealPath)

template<typename TCustom >
void	DeleteAllCustomData ()

NumberFormat &	GetNumberFormat ()

OwnerAndGroupResolver &	GetOGResolver ()

bool	HasListeners ()

void	MonitorDistinctFile (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const File &file)

void	MonitorFilesByName (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const lang::system::PathString &fileName)

void	MonitorPath (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const FTree::Cursor &cursor)

void	MonitorPathPrefix (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const lang::system::PathString &pathPrefix)

void	MonitorPathSubstring (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const lang::system::PathString &pathSubstring)

ALIB_API int	MonitorStop (FTreeListener *listener)

void	Notify (FTreeListener::Event event, File &file, SharedLock *lock, const String &filePath=NULL_STRING)

File	Root ()

Public Method Index: inherited from StringTree< TAllocator, T, TNodeHandler, TRecycling >
	StringTree (AllocatorType &allocator, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType, ATMP_T_IF(int, !ATMP_EQ(TSharedRecycler, void)) = 0>
	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)

	~StringTree ()

void	Clear ()

template<typename... TArgs>
void	ConstructRootValue (TArgs &&... args)

void	DbgSetDCSName (const char *name) const

void	DestructRootValue ()

AllocatorType &	GetAllocator () noexcept

ConstCursor	ImportCursor (ConstCursorHandle handle)

Cursor	ImportCursor (CursorHandle handle)

bool	IsEmpty () const

auto &	NodeTable ()

const auto &	NodeTable () const

integer	RecyclablesCount () const

void	ReserveRecyclables (integer qty, lang::ValueReference reference)

void	Reset ()

Cursor	Root ()

const ConstCursor	Root () const

constexpr CharacterType	Separator () const noexcept

integer	Size () const

Protected Type Index:
using	base = StringTree<MonoAllocator, FInfo, detail::FTreeNodeHandler>
	Type alias of this classes' base class.

Protected Type Index: inherited from StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
using	CharacterType = typename TNodeHandler::CharacterType

using	ConstCursorBase = TCursorBase<true>
	The constant version of type StringTreeBase::TCursorBase<TConst>.

using	CursorBase = TCursorBase<false>
	The mutable version of type StringTreeBase::TCursorBase<TConst>.

using	NameStorageType = typename TNodeHandler::NameStringType

using	NameType = const strings::TString<CharacterType>
	The string-type of node names and paths if provided externally for comparison.

using	NodeList = lang::BidiListHook<NodeBase>
	Alias shortcut for a bidirectional list of Node elements.

using	SharedRecyclerType = typename decltype(nodeTable)::SharedRecyclerType

using	SubstringType = typename strings::TSubstring<CharacterType>

Protected Field Index:
List< MonoAllocator, ListenerRecord >	listeners
	The list of registered listeners.

NumberFormat	numberFormat

OwnerAndGroupResolver	ogResolver

Protected Field Index: inherited from StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
int	dbgRootDataSet = 0

HashTable< TAllocator, typename NodeKey::ValueDescriptor, typename NodeKey::Hash, typename NodeKey::EqualTo, lang::Caching::Enabled, TRecycling >	nodeTable

RootNodeSpacer	root
	The root node.

CharacterType	separator

Protected Method Index:
ALIB_API void	notifyListeners (FTreeListener::Event event, File &file, SharedLock *lock, const lang::system::PathString &filePath)

ALIB_API void	registerListener (FTreeListener listener, lang::ContainerOp insertOrRemove, FTreeListener::Event event, const File file, const StringTree::Cursor *subTree, const lang::system::PathString &fileName, const lang::system::PathString &pathPrefix, const lang::system::PathString &pathSubstring)

Protected Method Index: inherited from StringTree< TAllocator, T, TNodeHandler, TRecycling >
Cursor	createCursor (baseNode &node)

Protected Method Index: inherited from StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
	StringTreeBase (TAllocator &allocator, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType, ATMP_T_IF(int, !ATMP_EQ(TSharedRecycler, void)) = 0>
	StringTreeBase (TAllocator &allocator, TSharedRecycler &pRecycler, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType, ATMP_T_IF(int, !ATMP_EQ(TSharedRecycler, void)) = 0>
	StringTreeBase (TSharedRecycler &pRecycler, CharacterType pathSeparator)

bool	checkChildName (const NameType &name) const

TAllocator &	GetAllocator () noexcept

Additional Inherited Members
Public Type Index: inherited from StringTree< TAllocator, T, TNodeHandler, TRecycling >
using	AllocatorType = TAllocator
	Type definition publishing template parameter TAllocator.

using	CharacterType = typename TNodeHandler::CharacterType

using	ConstCursor = TCursor<true>
	The constant version of type StringTree::TCursor<TConst>.

using	ConstRecursiveIterator = TRecursiveIterator<true>
	The constant version of type StringTree::TRecursiveIterator<TConst>.

using	Cursor = TCursor<false>
	The mutable version of type StringTree::TCursor<TConst>.

using	HandlerType = TNodeHandler
	Type definition publishing template parameter TNodeHandler.

using	NameType = strings::TString<CharacterType>

using	RecursiveIterator = TRecursiveIterator<false>
	The mutable version of type StringTree::TRecursiveIterator<TConst>.

using	SharedRecyclerType = typename basetree::SharedRecyclerType

using	SubstringType = typename strings::TSubstring<CharacterType>

Friends And Related Entity Details:

◆ detail::FTreeNodeHandler

friend struct detail::FTreeNodeHandler

friend

Friendship declaration.

Definition at line 184 of file ftree.hpp.

◆ files::File

friend class files::File

friend

Friendship declaration.

Definition at line 185 of file ftree.hpp.

◆ FTreeNodeHandler

friend struct FTreeNodeHandler

friend

Definition at line 167 of file ftree.hpp.

Type Definition Details:

◆ base

using base = StringTree<MonoAllocator, FInfo, detail::FTreeNodeHandler>

protected

Type alias of this classes' base class.

Definition at line 182 of file ftree.hpp.

Field Details:

◆ listeners

List<MonoAllocator, ListenerRecord> listeners

protected

The list of registered listeners.

Definition at line 210 of file ftree.hpp.

◆ numberFormat

NumberFormat numberFormat

protected

Formatting information used with format methods of associated File instances.

Definition at line 189 of file ftree.hpp.

◆ ogResolver

OwnerAndGroupResolver ogResolver

protected

A caching owner and group resolver. Used with format methods of associated File instances.

Definition at line 193 of file ftree.hpp.

◆ Pool

PoolAllocator Pool

An object pool used for recycling all sorts of allocated objects as well as the hashtable entries. It is chained to the allocator provided with construction.

The pool may be used in accordance with the general rules imposed by camp ALib Monomem. If so, in multithreaded environments, this object has to be locked (in addition to all other custom locks when interfacing this type), when using this pool from custom code.

Definition at line 178 of file ftree.hpp.

Constructor(s) / Destructor Details:

◆ FTree()

FTree ( MonoAllocator & allocator )

Constructor.

Parameters

allocator The allocator to use.

Definition at line 82 of file ftree.cpp.

Here is the call graph for this function:

◆ ~FTree()

~FTree ( )

Destructor.

Definition at line 100 of file ftree.cpp.

Here is the call graph for this function:

Method Details:

◆ AllocateExtendedInfo()

void AllocateExtendedInfo	(	Cursor &	node,
		const lang::system::PathString &	symLinkDest,
		const lang::system::PathString &	symLinkRealPath )

inline

Allocates (or recycles) an appropriate information object fitting to the type of this entry. This method must only be applied to entries of types

DIRECTORY,
SYMBOLIC_LINK or
SYMBOLIC_LINK_DIR. In debug compilations, this is asserted. It is likewise asserted that the sybolic link information strings are empty in case the type is DIRECTORY.

Parameters

node	The node add extended information to.
symLinkDest	In case of symbolic link types, the symbolic link target.
symLinkRealPath	In case of symbolic link types, the symbolic link target as real path.

Definition at line 278 of file ftree.hpp.

Here is the call graph for this function:

◆ DeleteAllCustomData()

template<typename TCustom >

void DeleteAllCustomData ( )

inline

Deletes all custom data objects attached to any File in this tree.
Note that this method is only applicable if all custom data objects set in any node of this tree share the same type TCustom. With debug-compilations this is asserted.

See also: Method File::AttachCustomData.

Template Parameters

TCustom The object type to optionally store in tree nodes.

Definition at line 293 of file ftree.hpp.

Here is the call graph for this function:

◆ FixSums()

void FixSums ( Cursor directory )

static

Recalculates the sums of the given node. This is not done recursively. The fix is needed when scanning an existent directory with potentially more greedy scan parameters.

Parameters

directory The directory to re-calculate the sums for.

Definition at line 239 of file ftree.cpp.

Here is the call graph for this function:

◆ GetNumberFormat()

NumberFormat & GetNumberFormat ( )

inline

Retrieves formatting flags which are used with method File::Format.

Returns: Number formatting information for File objects associated with this file tree.

Definition at line 321 of file ftree.hpp.

◆ GetOGResolver()

OwnerAndGroupResolver & GetOGResolver ( )

inline

Retrieves formatting flags which are used with method File::Format.

Returns: Number formatting information for File objects associated with this file tree.

Definition at line 325 of file ftree.hpp.

◆ HasListeners()

bool HasListeners ( )

inline

Returns: true if listeners are registered with this file tree, false otherwise

Definition at line 356 of file ftree.hpp.

◆ MonitorDistinctFile()

void MonitorDistinctFile	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const File &	file )

inline

Inserts or removes a listener to a specific file.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
file	The file to listen to.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 366 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorFilesByName()

void MonitorFilesByName	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const lang::system::PathString &	fileName )

inline

Inserts or removes a listener for all files that share the given fileName.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
fileName	The name of one or more files to listen to.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 390 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPath()

void MonitorPath	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const FTree::Cursor &	cursor )

inline

Inserts or removes a listener for all files below the subtree specified by the given cursor.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
cursor	The parent node in the tree of files to monitor.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 411 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPathPrefix()

void MonitorPathPrefix	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const lang::system::PathString &	pathPrefix )

inline

Inserts or removes a listener for all files below the subtree specified by the given startPath.

Attention: Note that the parameter pathPrefix has to be a portion of a real path.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
pathPrefix	The path prefix of the subtree of files to monitor. Note that a missing leading separator character will be added.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 439 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPathSubstring()

void MonitorPathSubstring	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const lang::system::PathString &	pathSubstring )

inline

Inserts or removes a listener for all files whose path (excluding the file name) contains the given pathSubstring.

Attention: Note that the parameter pathSubstring has to be a portion of a real path.

Parameters

insertOrRemove	Denotes whether the listener should be inserted or removed. (Only enum elements ContainerOp::Insert or ContainerOp::Remove must be passed.)
listener	The listener to register.
event	The event to listen to.
pathSubstring	The substring to match in the path (including the file name) of the files to monitor.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 464 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorStop()

int MonitorStop ( FTreeListener * listener )

Removes all registrations of the given listener.

Parameters

listener The listener to remove.

Returns: The number of registrations that have been removed.

See also: Chapter 3. Monitoring Changes in an FTree of the Programmer's Manual of camp ALib Files.

Definition at line 177 of file ftree.cpp.

◆ Notify()

void Notify	(	FTreeListener::Event	event,
		File &	file,
		SharedLock *	lock,
		const String &	filePath = NULL_STRING )

Notifies registered listeners on events.

Parameters

event	The event that occurred.
file	The file.
lock	Pointer to an (optional) SharedLock. Has to be given only if multithreaded access is performed. If the filePath is nulled, method AcquireShared will be called. This parameter is available (and to be passed) only if the module ALib Threads is included in the ALib Distribution.
filePath	The full path of the file. Might be nulled if not available to the caller. In this case it is internally created. Defaults to NULL_STRING.

◆ notifyListeners()

void notifyListeners	(	FTreeListener::Event	event,
		File &	file,
		SharedLock *	lock,
		const lang::system::PathString &	filePath )

protected

Notifies registered listeners on events.

Parameters

event	The event that occurred.
file	The file.
filePath	The full path of the file. Might be nulled if not available, yet.
lock	Pointer to an (optional) SharedLock. This parameter is available (and to be passed) only if the module ALib Threads is included in the ALib Distribution.

Definition at line 199 of file ftree.cpp.

Here is the call graph for this function:

◆ registerListener()

void registerListener	(	FTreeListener *	listener,
		lang::ContainerOp	insertOrRemove,
		FTreeListener::Event	event,
		const File *	file,
		const StringTree::Cursor *	subTree,
		const lang::system::PathString &	fileName,
		const lang::system::PathString &	pathPrefix,
		const lang::system::PathString &	pathSubstring )

protected

Implements the various overloaded listener registration methods.

Parameters

listener	The listener to register or dispose.
insertOrRemove	Denotes registration or disposal of a listener.
event	The event to listen to.
file	If given, the exported value of the file to listen to.
subTree	If given, the exported value of the subtree of files to listen to.
fileName	If given, the file's name to listen to.
pathPrefix	If given, the start string of the file path to monitor.
pathSubstring	If given, the substring to match in the path (including the file name) of the files to monitor.

Definition at line 127 of file ftree.cpp.

Here is the call graph for this function:

◆ Root()

File Root ( )

inline

Sort of 'overloads' method StringTree::Root, which otherwise is accessible via operator-> inherited by parent class TSharedMonoVal. In contrast to the inherited method, this version returns an instance of type File.

Returns: A file-cursor pointing to the root node of this file tree.

Definition at line 1007 of file ftree.hpp.

The documentation for this class was generated from the following files:

Description:

StringTree Interface

Class File

Monotonic Behavior

Inner Type Index:

Public Static Method Index:

Public Field Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Additional Inherited Members

Friends And Related Entity Details:

◆ detail::FTreeNodeHandler

◆ files::File

◆ FTreeNodeHandler

Type Definition Details:

◆ base

Field Details:

◆ listeners

◆ numberFormat

◆ ogResolver

◆ Pool

Constructor(s) / Destructor Details:

◆ FTree()

◆ ~FTree()

Method Details:

◆ AllocateExtendedInfo()

◆ DeleteAllCustomData()

◆ FixSums()

◆ GetNumberFormat()

◆ GetOGResolver()

◆ HasListeners()

◆ MonitorDistinctFile()

◆ MonitorFilesByName()

◆ MonitorPath()

◆ MonitorPathPrefix()

◆ MonitorPathSubstring()

◆ MonitorStop()

◆ Notify()

◆ notifyListeners()

◆ registerListener()

◆ Root()