Description:

This class builds on ALib type StringTree. The contained elements (tree nodes) are of typeFTValue and represent entries in filesystems. Usually the tree is filled using the 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 FileTree exclusively store entries along their "Real Path", hence always resolving symbolic links. A user of this library may deviate from this "data contract".

Class FTFile

The base classes' method Cursor Root() is overloaded by this class and returns an instance of class FTFile 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 FTFile 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 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 FTValue elements.
Furthermore, class FTFile (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 147 of file ftree.hpp.

#include <ftree.hpp>

Inheritance diagram for alib::filetree::FTree:

[legend]

Collaboration diagram for alib::filetree::FTree:

[legend]

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

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

Public Field Index:
PoolAllocator	Pool

Public Method Index:
	FTree (MonoAllocator &allocator)
	~FTree ()
	Destructor.
void	AllocateExtendedInfo (Cursor &node, const PathString &symLinkDest, const PathString &symLinkRealPath)
template<typename TCustom>
void	DeleteAllCustomData ()
NumberFormat &	GetNumberFormat ()
const NumberFormat &	GetNumberFormat () const
const OwnerAndGroupResolver &	GetOGResolver () const
bool	HasListeners ()
void	MonitorDistinctFile (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const FTFile &file)
void	MonitorFilesByName (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const 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 PathString &pathPrefix)
void	MonitorPathSubstring (lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const PathString &pathSubstring)
int	MonitorStop (FTreeListener *listener)
void	Notify (FTreeListener::Event event, FTFile file, const PathString &filePath=NULL_PATH)
FTFile	Root ()
Public Method Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
	StringTree (AllocatorType &allocator, CharacterType pathSeparator)
	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)
	~StringTree ()
void	Clear ()
void	ConstructRootValue (TArgs &&... args)
lang::DbgCriticalSections &	DbgGetDCS () const
void	DbgSetDCSName (const char *name) const
void	DestructRootValue ()
AllocatorType &	GetAllocator () noexcept
ConstCursor	ImportCursor (ConstCursorHandle handle) const
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, FTValue, detail::FTreeNodeHandler>
	Type alias of this classes' base class.
Protected Type Index: inherited from alib::containers::detail::StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
using	CharacterType = typename TNodeHandler::CharacterType
using	ConstCursorBase = TCursorBase<true>
	The constant version of type TCursorBase.
using	CursorBase = TCursorBase<false>
	The mutable version of type TCursorBase.
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:
ListMA< ListenerRecord >	listeners
	The list of registered listeners.
NumberFormat	numberFormat
OwnerAndGroupResolver	ogResolver
Protected Field Index: inherited from alib::containers::detail::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:
void	notifyListeners (FTreeListener::Event event, FTFile &file, const PathString &filePath)
void	registerListener (FTreeListener listener, lang::ContainerOp insertOrRemove, FTreeListener::Event event, const FTFile file, const StringTree::Cursor *subTree, const PathString &fileName, const PathString &pathPrefix, const PathString &pathSubstring)
Protected Method Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
Cursor	createCursor (baseNode &node)
Protected Method Index: inherited from alib::containers::detail::StringTreeBase< TAllocator, T, TNodeHandler, TRecycling >
	StringTreeBase (TAllocator &allocator, CharacterType pathSeparator)
template<typename TSharedRecycler = SharedRecyclerType>
	StringTreeBase (TAllocator &allocator, TSharedRecycler &pRecycler, CharacterType pathSeparator)
template<typename TSharedRecycler = SharedRecyclerType>
	StringTreeBase (TSharedRecycler &pRecycler, CharacterType pathSeparator)
bool	checkChildName (const NameType &name) const
TAllocator &	GetAllocator () noexcept

Additional Inherited Members
Public Type Index: inherited from alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
using	AllocatorType
	Type definition publishing template parameter TAllocator.
using	CharacterType
using	ConstCursor
	The constant version of type `TCursor`.
using	Cursor
	The mutable version of type `TCursor`.
using	HandlerType
	Type definition publishing template parameter TNodeHandler.
using	NameType
using	SharedRecyclerType
using	SubstringType

◆ FTreeNodeHandler

friend struct FTreeNodeHandler

friend

Definition at line 148 of file ftree.hpp.

Type Definition Details:

◆ base

using alib::filetree::FTree::base = StringTree<MonoAllocator, FTValue, detail::FTreeNodeHandler>

protected

Type alias of this classes' base class.

Definition at line 163 of file ftree.hpp.

Field Details:

◆ listeners

ListMA<ListenerRecord> alib::filetree::FTree::listeners

protected

The list of registered listeners.

Definition at line 192 of file ftree.hpp.

◆ numberFormat

NumberFormat alib::filetree::FTree::numberFormat

protected

Formatting information used with format methods of associated FTFile instances.

Definition at line 172 of file ftree.hpp.

◆ ogResolver

OwnerAndGroupResolver alib::filetree::FTree::ogResolver

protected

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

Definition at line 176 of file ftree.hpp.

◆ Pool

PoolAllocator alib::filetree::FTree::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 159 of file ftree.hpp.

Constructor(s) / Destructor Details:

◆ FTree()

alib::filetree::FTree::FTree ( MonoAllocator & allocator )

Constructor.

Parameters

allocator The allocator to use.

Definition at line 71 of file ftree.cpp.

Here is the call graph for this function:

◆ ~FTree()

alib::filetree::FTree::~FTree ( )

Destructor.

Definition at line 88 of file ftree.cpp.

Here is the call graph for this function:

Method Details:

◆ AllocateExtendedInfo()

void alib::filetree::FTree::AllocateExtendedInfo	(	Cursor &	node,
		const PathString &	symLinkDest,
		const 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 250 of file ftree.hpp.

Here is the call graph for this function:

◆ DeleteAllCustomData()

template<typename TCustom>

void alib::filetree::FTree::DeleteAllCustomData ( )

inline

Deletes all custom data objects attached to any FTFile 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 TCustom & AttachCustomData(TArgs&& ...) .

Template Parameters

TCustom The object type to optionally store in tree nodes.

Definition at line 262 of file ftree.hpp.

◆ FixSums()

void alib::filetree::FTree::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 214 of file ftree.cpp.

Here is the call graph for this function:

◆ GetNumberFormat() [1/2]

NumberFormat & alib::filetree::FTree::GetNumberFormat ( )

inline

Retrieves formatting flags which are used with method AString & Format(Substring, AString&, lang::CurrentData, NumberFormat*) const.

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

Definition at line 288 of file ftree.hpp.

◆ GetNumberFormat() [2/2]

const NumberFormat & alib::filetree::FTree::GetNumberFormat ( ) const

inline

Retrieves formatting flags which are used with method AString & Format(Substring, AString&, lang::CurrentData, NumberFormat*) const.

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

Definition at line 292 of file ftree.hpp.

◆ GetOGResolver()

const OwnerAndGroupResolver & alib::filetree::FTree::GetOGResolver ( ) const

inline

Retrieves formatting flags which are used with method AString & Format(Substring, AString&, lang::CurrentData, NumberFormat*) const.

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

Definition at line 296 of file ftree.hpp.

◆ HasListeners()

bool alib::filetree::FTree::HasListeners ( )

inline

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

Definition at line 313 of file ftree.hpp.

◆ MonitorDistinctFile()

void alib::filetree::FTree::MonitorDistinctFile	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const FTFile &	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 `Insert` or `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 FileTree.

Definition at line 323 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorFilesByName()

void alib::filetree::FTree::MonitorFilesByName	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 `Insert` or `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 FileTree.

Definition at line 341 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPath()

void alib::filetree::FTree::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 `Insert` or `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 FileTree.

Definition at line 360 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPathPrefix()

void alib::filetree::FTree::MonitorPathPrefix	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 `Insert` or `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 FileTree.

Definition at line 380 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorPathSubstring()

void alib::filetree::FTree::MonitorPathSubstring	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 `Insert` or `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 FileTree.

Definition at line 401 of file ftree.hpp.

Here is the call graph for this function:

◆ MonitorStop()

int alib::filetree::FTree::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 FileTree.

Definition at line 161 of file ftree.cpp.

◆ Notify()

void alib::filetree::FTree::Notify	(	FTreeListener::Event	event,
		FTFile	file,
		const PathString &	filePath = NULL_PATH )

inline

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 to the caller. In this case it is internally created. Defaults to NULL_STRING.

Definition at line 1004 of file ftree.hpp.

Here is the call graph for this function:

◆ notifyListeners()

void alib::filetree::FTree::notifyListeners	(	FTreeListener::Event	event,
		FTFile &	file,
		const 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.

Definition at line 181 of file ftree.cpp.

Here is the call graph for this function:

◆ registerListener()

void alib::filetree::FTree::registerListener	(	FTreeListener *	listener,
		lang::ContainerOp	insertOrRemove,
		FTreeListener::Event	event,
		const FTFile *	file,
		const StringTree::Cursor *	subTree,
		const PathString &	fileName,
		const PathString &	pathPrefix,
		const 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 113 of file ftree.cpp.

◆ Root()

FTFile alib::filetree::FTree::Root ( )

inline

Sort of 'overloads' method Cursor 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 FTFile.

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

Definition at line 1002 of file ftree.hpp.

Here is the call graph for this function:

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

Description:

StringTree Interface

Class FTFile

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:

◆ FTreeNodeHandler

Type Definition Details:

◆ base

Field Details:

◆ listeners

◆ numberFormat

◆ ogResolver

◆ Pool

Constructor(s) / Destructor Details:

◆ FTree()

◆ ~FTree()

Method Details:

◆ AllocateExtendedInfo()

◆ DeleteAllCustomData()

◆ FixSums()

◆ GetNumberFormat() [1/2]

◆ GetNumberFormat() [2/2]

◆ GetOGResolver()

◆ HasListeners()

◆ MonitorDistinctFile()

◆ MonitorFilesByName()

◆ MonitorPath()

◆ MonitorPathPrefix()

◆ MonitorPathSubstring()

◆ MonitorStop()

◆ Notify()

◆ notifyListeners()

◆ registerListener()

◆ Root()