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 150 of file ftree.inl.

Inheritance diagram for alib::files::FTree:

[legend]

Collaboration diagram for alib::files::FTree:

[legend]

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

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

Public Field Index:
PoolAllocator	Pool

Public Method Index:
ALIB_DLL	FTree (MonoAllocator &allocator)

ALIB_DLL	~FTree ()
	Destructor.

void	AllocateExtendedInfo (Cursor &node, const system::PathString &symLinkDest, const 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 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 system::PathString &pathPrefix)

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

ALIB_DLL 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 alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >
	StringTree (AllocatorType &allocator, CharacterType pathSeparator)

	StringTree (AllocatorType &allocator, CharacterType pathSeparator)

	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)

	StringTree (CharacterType pathSeparator, TSharedRecycler &pRecycler)

	~StringTree ()

	~StringTree ()

void	Clear ()

void	Clear ()

void	ConstructRootValue (TArgs &&... args)

void	ConstructRootValue (TArgs &&... args)

void	DbgSetDCSName (const char *name) const

void	DbgSetDCSName (const char *name) const

void	DestructRootValue ()

void	DestructRootValue ()

AllocatorType &	GetAllocator () noexcept

AllocatorType &	GetAllocator () noexcept

ConstCursor	ImportCursor (ConstCursorHandle handle)

ConstCursor	ImportCursor (ConstCursorHandle handle)

Cursor	ImportCursor (CursorHandle handle)

Cursor	ImportCursor (CursorHandle handle)

bool	IsEmpty () const

bool	IsEmpty () const

auto &	NodeTable ()

auto &	NodeTable ()

const auto &	NodeTable () const

const auto &	NodeTable () const

integer	RecyclablesCount () const

integer	RecyclablesCount () const

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

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

void	Reset ()

void	Reset ()

Cursor	Root ()

Cursor	Root ()

const ConstCursor	Root () const

const ConstCursor	Root () const

constexpr CharacterType	Separator () const noexcept

constexpr CharacterType	Separator () const noexcept

integer	Size () const

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 alib::containers::detail::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 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:
ALIB_DLL void	notifyListeners (FTreeListener::Event event, File &file, SharedLock *lock, const system::PathString &filePath)

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

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

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> requires ( !std::same_as<TSharedRecycler , void> )
	StringTreeBase (TAllocator &allocator, TSharedRecycler &pRecycler, CharacterType pathSeparator)

template<typename TSharedRecycler = SharedRecyclerType> requires (!std::same_as<TSharedRecycler, void>)
	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<TConst>.

using	ConstRecursiveIterator
	The constant version of type TRecursiveIterator.

using	Cursor
	The mutable version of type TCursor<TConst>.

using	HandlerType
	Type definition publishing template parameter TNodeHandler.

using	NameType

using	RecursiveIterator
	The mutable version of type TRecursiveIterator.

using	SharedRecyclerType

using	SubstringType

Friends And Related Entity Details:

◆ detail::FTreeNodeHandler

friend struct detail::FTreeNodeHandler

friend

Friendship declaration.

Definition at line 169 of file ftree.inl.

◆ files::File

friend class files::File

friend

Friendship declaration.

Definition at line 170 of file ftree.inl.

◆ FTreeNodeHandler

friend struct FTreeNodeHandler

friend

Definition at line 152 of file ftree.inl.

Type Definition Details:

◆ base

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

protected

Type alias of this classes' base class.

Definition at line 167 of file ftree.inl.

Field Details:

◆ listeners

List<MonoAllocator, ListenerRecord> alib::files::FTree::listeners

protected

The list of registered listeners.

Definition at line 195 of file ftree.inl.

◆ numberFormat

NumberFormat alib::files::FTree::numberFormat

protected

Formatting information used with format methods of associated File instances.

Definition at line 174 of file ftree.inl.

◆ ogResolver

OwnerAndGroupResolver alib::files::FTree::ogResolver

protected

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

Definition at line 178 of file ftree.inl.

◆ Pool

PoolAllocator alib::files::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 163 of file ftree.inl.

Constructor(s) / Destructor Details:

◆ FTree()

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

Constructor.

Parameters

allocator The allocator to use.

Definition at line 115 of file ftree.cpp.

Here is the call graph for this function:

◆ ~FTree()

alib::files::FTree::~FTree ( )

Destructor.

Definition at line 133 of file ftree.cpp.

Here is the call graph for this function:

Method Details:

◆ AllocateExtendedInfo()

void alib::files::FTree::AllocateExtendedInfo	(	Cursor &	node,
		const system::PathString &	symLinkDest,
		const 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 263 of file ftree.inl.

Here is the call graph for this function:

◆ DeleteAllCustomData()

template<typename TCustom>

void alib::files::FTree::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 278 of file ftree.inl.

◆ FixSums()

void alib::files::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 272 of file ftree.cpp.

Here is the call graph for this function:

◆ GetNumberFormat()

NumberFormat & alib::files::FTree::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 309 of file ftree.inl.

◆ GetOGResolver()

OwnerAndGroupResolver & alib::files::FTree::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 313 of file ftree.inl.

◆ HasListeners()

bool alib::files::FTree::HasListeners ( )

inline

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

Definition at line 344 of file ftree.inl.

◆ MonitorDistinctFile()

void alib::files::FTree::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 354 of file ftree.inl.

Here is the call graph for this function:

◆ MonitorFilesByName()

void alib::files::FTree::MonitorFilesByName	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 378 of file ftree.inl.

Here is the call graph for this function:

◆ MonitorPath()

void alib::files::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 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 399 of file ftree.inl.

Here is the call graph for this function:

◆ MonitorPathPrefix()

void alib::files::FTree::MonitorPathPrefix	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 427 of file ftree.inl.

Here is the call graph for this function:

◆ MonitorPathSubstring()

void alib::files::FTree::MonitorPathSubstring	(	lang::ContainerOp	insertOrRemove,
		FTreeListener *	listener,
		FTreeListener::Event	event,
		const 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 452 of file ftree.inl.

Here is the call graph for this function:

◆ MonitorStop()

int alib::files::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 Files.

Definition at line 210 of file ftree.cpp.

◆ Notify()

void alib::files::FTree::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 Build.
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.

Here is the call graph for this function:

◆ notifyListeners()

void alib::files::FTree::notifyListeners	(	FTreeListener::Event	event,
		File &	file,
		SharedLock *	lock,
		const 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 Build.

Definition at line 232 of file ftree.cpp.

Here is the call graph for this function:

◆ registerListener()

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

Here is the call graph for this function:

◆ Root()

File alib::files::FTree::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 997 of file ftree.inl.

Here is the call graph for this function:

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()