ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
ftree.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_files of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib { namespace files {
9
10 class FTree;
11template<typename TLock> struct TSharedFTree;
12 class File;
13
14 /// This namespace implements internals of namespace #alib::files.
15 namespace detail {
16
17struct FTreeNodeHandler;
18
19/// A shortcut to the base class of the base class of class \alib{files;FTree}.
21 FInfo,
23 Recycling::Private>;
24
25/// Specialized \ref alib_ns_containers_stringtree_referencedoc "TNodeHandler" for class
26/// \alib{files;FTree} which recycles extended information objects of type
27/// \alib{files;FInfo::EIDirectory}, \alib{files;FInfo::EISymLinkFile}, and
28/// \alib{files;FInfo::EISymLinkDir} with node deletion.
29///
30/// In respect to the node name allocation, this type behaves like
31/// default handler \alib{containers;StringTreeNamesDynamic}.
32/// In debug compilations, statistics
33/// variables \alib{containers;DBG_STATS_STRINGTREE_NAMES} and
34/// \alib{containers;DBG_STATS_STRINGTREE_NAME_OVERFLOWS} are increased, just like the original
35/// does.
37{
38 /// The character type that the \b StringTree uses for child name and path strings.
39 /// This is taken from the C++ standard library.
41
42 /// The string-type of a node's name. This is a simple static string, allocated with the
43 /// pool allocator.
45
46 /// Copies the node's name to the local string.
47 ///
48 /// @param tree The instance of struct \alib{containers;detail::StringTreeBase} that invokes
49 /// this method. Any member may be accessed, including
50 /// \alib{containers::detail::StringTreeBase;nodeTable} which contains the
51 /// \alib{MonoAllocator} that the tree uses for the allocation of nodes.
52 /// @param node The node that was just created. Allows access to the key and
53 /// custom value data. While the parent and sibling nodes are likewise accessible,
54 /// it is strictly forbidden to modify those.
55 static
56 inline
57 void InitializeNode( TTree& tree, TTree::Node& node );
58
59 /// This implementation frees any dynamically allocated memory of the node's name and in
60 /// addition recycles any extended information object attached to the \alib{files;FInfo}
61 /// object.
62 /// @param tree The instance of struct \alib{containers;detail::StringTreeBase} that invokes
63 /// this method. Any member may be accessed, including
64 /// \alib{containers::detail::StringTreeBase;nodeTable} which contains the
65 /// \alib{MonoAllocator} that the tree uses for the allocation of nodes.
66 /// @param node The node that is to be removed. Allows access to the key and
67 /// custom value data. While the parent and sibling nodes are likewise accessible,
68 /// it is strictly forbidden to modify those.
69 static
70 inline
71 void FreeNode( TTree& tree, TTree::Node& node );
72
73 /// Implements \alib{files;FTree::AllocateExtendedInfo}.
74 /// \param node The node add extended information to.
75 /// \param symLinkDest In case of symbolic link types, the symbolic link target.
76 /// \param symLinkRealPath In case of symbolic link types, the symbolic link target as real path.
78 static
80 const system::PathString& symLinkDest,
81 const system::PathString& symLinkRealPath );
82}; // struct FTreeNodeHandler
83
84} // namespace alib::files[::detail]
85
86
87// =================================================================================================
88/// Abstract virtual interface type to implement types observing changes in instances of class
89/// \alib{files;FTree}.
90/// @see
91/// Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
92// =================================================================================================
94{
95 /// The type of change that imposes the notification of a listener.
96 enum class Event
97 {
98 CreateNode, ///< A file or directory entry was created.
99 DeleteNode, ///< A file or directory entry was deleted.
100 };
101
102 /// Virtual destructor.
103 virtual ~FTreeListener() {}
104
105 /// The virtual notification method.
106 /// @param file The file or directory that was modified.
107 /// @param event The type of modification.
108 virtual void Notify( File& file, Event event ) = 0;
109
110}; // struct FTreeListener
111
112
113//==================================================================================================
114/// This class builds on \alib type \alib{containers;StringTree}.
115/// The contained elements (tree nodes) are of type\alib{files;FInfo} and represent entries in
116/// filesystems.
117/// Usually the tree is filled using function \alib{files;ScanFiles}.
118///
119/// ### StringTree Interface ###
120/// Public base class \alib{containers;StringTree} provides all interfaces necessary to create and
121/// delete entries, iterate and recursively walk the file tree. Please consult its documentation
122/// for further information.
123///
124/// \note As \alib{files;ScanFiles;documented with function ScanFiles}, entities of this
125/// module \alib_files_nl exclusively store entries along their <em>"Real Path"</em>, hence
126/// always resolving symbolic links. A user of this library may deviate from this
127/// "data contract".
128///
129/// ### Class File ###
130/// The base classes' method \alib{containers;StringTree::Root} is overloaded by this class
131/// and returns an instance of class \alib{files;File} instead of an instance of class
132/// alib{containers;StringTree::Cursor}.
133/// This class can be turned into a cursor using \alib{files::File;AsCursor} and then used to
134/// navigate through the tree. Then, the cursor can be cast back (or assigned) to a \b File
135/// instance.
136///
137/// ### Monotonic Behavior ###
138/// The class fulfills \ref alib_contmono_intro_strictweak "weak monotonic allocation requirements",
139/// which is achieved by recycling not only the nodes (what base type \b StringTree does by default)
140/// but also any extended node information. This is implemented with the <b>StringTree</b>
141/// handler-type \alib{files;detail::FTreeNodeHandler} on the one hand, and on the other hand,
142/// with the implementation of the method #AllocateExtendedInfo, which has to be exclusively used
143/// to attach information structs on \b FInfo elements.<br>
144/// Furthermore, class \b File (the nodes of the tree) provides method
145/// \alib{files::File;AttachCustomData}, which likewise uses the internal pool-allocator.
146///
147/// In summary, this allows an indefinite sequence of file-scan and result filtering (deletions)
148/// with using more memory than the highest resulting fill state in such sequence requires.
149//==================================================================================================
150class FTree : public StringTree<MonoAllocator, FInfo, detail::FTreeNodeHandler>
151{
152 friend struct FTreeNodeHandler;
153
154 public:
155 /// An object pool used for recycling all sorts of allocated objects as well as the
156 /// hashtable entries.
157 /// It is \ref alib_contmono_chaining "chained" to the allocator provided with construction.
158 ///
159 /// The pool may be used in accordance with the general rules imposed by camp \alib_monomem.
160 /// If so, in multithreaded environments, this object has to be locked (in addition
161 /// to all other custom locks when interfacing this type), when using this pool from custom
162 /// code.
164
165 protected:
166 /// Type alias of this classes' base class.
168
169 friend struct detail::FTreeNodeHandler; ///< Friendship declaration.
170 friend class files::File; ///< Friendship declaration.
171
172 /// Formatting information used with \alib{files;File::Format;format methods} of associated
173 /// \b File instances.
175
176 /// A caching owner and group resolver. Used with \alib{files;File::Format;format methods}
177 /// of associated \b File instances.
179
180 /// Record used to manage registered listeners.
182 {
183 FTreeListener* listener; ///< The listener to register or dispose.
184 FTreeListener::Event event; ///< The event to listen to.
185 ConstCursorHandle file; ///< If given, the files to listen to.
186 ConstCursorHandle subTree; ///< If given, the path of files to listen to.
187 system::PathStringPA fileName; ///< If given, the file's name to listen to.
188 system::PathStringPA pathPrefix; ///< If given, the start string of the file path
189 ///< to monitor.
190 system::PathStringPA pathSubstring; ///< If given, the substring to match in the path
191 ///< (including the file name) of files to monitor.
192 };
193
194 /// The list of registered listeners.
196
197 /// Implements the various overloaded listener registration methods.
198 /// @param listener The listener to register or dispose.
199 /// @param insertOrRemove Denotes registration or disposal of a listener.
200 /// @param event The event to listen to.
201 /// @param file If given, the exported value of the file to listen to.
202 /// @param subTree If given, the exported value of the subtree of files to listen to.
203 /// @param fileName If given, the file's name to listen to.
204 /// @param pathPrefix If given, the start string of the file path to monitor.
205 /// @param pathSubstring If given, the substring to match in the path (including the file name)
206 /// of the files to monitor.
208 lang::ContainerOp insertOrRemove,
210 const File* file,
211 const StringTree::Cursor* subTree,
212 const system::PathString& fileName,
213 const system::PathString& pathPrefix,
214 const system::PathString& pathSubstring );
215
216 #if DOXYGEN
217 /// Notifies registered listeners on events.
218 /// @param event The event that occurred.
219 /// @param file The file.
220 /// @param filePath The full path of the file. Might be nulled if not available, yet.
221 /// @param lock Pointer to an (optional) \alib{threads;SharedLock}.<br>
222 /// This parameter is available (and to be passed) only if the module
223 /// \alib_threads is included in the \alibbuild.
225 File& file,
226 SharedLock* lock,
227 const system::PathString& filePath );
228 #else
230 File& file
231 IF_ALIB_THREADS( , SharedLock* lock) ,
232 const system::PathString& filePath );
233 #endif
234
235 public:
236 /// Constructor.
237 /// @param allocator The allocator to use.
239 FTree( MonoAllocator& allocator );
240
241 /// Destructor.
243 ~FTree();
244
245 /// Sort of 'overloads' method \alib{monomem;StringTree::Root}, which otherwise is accessible
246 /// via <b>operator-></b> inherited by parent class \alib{monomem;TSharedMonoVal}.
247 /// In contrast to the inherited method, this version returns an instance of type \b File.
248 /// @return A file-cursor pointing to the root node of this file tree.
249 inline
250 File Root();
251
252 /// Allocates (or recycles) an appropriate information object fitting to the type of this entry.
253 /// This method must only be applied to entries of types
254 /// - \alib{files::FInfo::Types;DIRECTORY},
255 /// - \alib{files::FInfo::Types;SYMBOLIC_LINK} or
256 /// - \alib{files::FInfo::Types;SYMBOLIC_LINK_DIR}.
257 /// In debug compilations, this is asserted. It is likewise asserted that the sybolic link
258 /// information strings are empty in case the type is \alib{files::FInfo::Types;DIRECTORY}.
259 ///
260 /// \param node The node add extended information to.
261 /// \param symLinkDest In case of symbolic link types, the symbolic link target.
262 /// \param symLinkRealPath In case of symbolic link types, the symbolic link target as real path.
264 const system::PathString& symLinkDest,
265 const system::PathString& symLinkRealPath)
266 {
267 detail::FTreeNodeHandler::AllocateExtendedInfo( node, symLinkDest, symLinkRealPath);
268 }
269
270 /// Deletes all custom data objects attached to any \b File in this tree.<br>
271 /// Note that this method is only applicable if all custom data objects set in any node
272 /// of this tree share the same type \p{TCustom}.
273 /// With debug-compilations this is asserted.
274 ///
275 /// @see Method \alib{files;File::AttachCustomData}.
276 /// @tparam TCustom The object type to optionally store in tree nodes.
277 template<typename TCustom>
279 {
280 for( auto& node : nodeTable )
281 {
282 if( node.data.custom )
283 {
284 ALIB_ASSERT_ERROR( &typeid(TCustom) == node.data.dbgCustomType, "FILES",
285 "CustomData to delete does not match attached type.\n"
286 "Deletion has to be performed individually by this software.\n"
287 "This method must only be used if all tree nodes have the same custom data "
288 "attached\n"
289 " Attached type: <{}>\n"
290 " Given type: <{}>" , &typeid(TCustom), node.data.dbgCustomType )
291
292 reinterpret_cast<TCustom*>( node.data.custom ) -> ~TCustom();
293 Pool.free( node.data.custom, sizeof(TCustom) );
294 node.data.custom= nullptr;
295 ALIB_DBG( node.data.dbgCustomType= nullptr; )
296 }
297 }
298 }
299
300 /// Recalculates the sums of the given node. This is \b not done recursively. The fix is needed
301 /// when scanning an existent directory with potentially more greedy scan parameters.
302 /// @param directory The directory to re-calculate the sums for.
304 static
305 void FixSums(Cursor directory);
306
307 /// Retrieves formatting flags which are used with method \alib{files;File::Format}.
308 /// @return Number formatting information for \b File objects associated with this file tree.
310
311 /// Retrieves formatting flags which are used with method \alib{files;File::Format}.
312 /// @return Number formatting information for \b File objects associated with this file tree.
314
315 // =============================== Listener Registration ===================================
316
317
318 #if DOXYGEN
319 /// Notifies registered listeners on events.
320 /// @param event The event that occurred.
321 /// @param file The file.
322 /// @param lock Pointer to an (optional) \alib{threads;SharedLock}.
323 /// Has to be given only if multithreaded access is performed.
324 /// If the \p{filePath} is nulled, method
325 /// \alib{threads::SharedLock;AcquireShared} will be called.<br>
326 /// This parameter is available (and to be passed) only if the module
327 /// \alib_threads is included in the \alibbuild.
328 /// @param filePath The full path of the file. Might be nulled if not available to the caller.
329 /// In this case it is internally created.<br>
330 /// Defaults to \alib{NULL_STRING}.
332 File& file ,
333 SharedLock* lock ,
334 const String& filePath= NULL_STRING );
335 #else
336 void Notify( FTreeListener::Event event,
337 File& file
338IF_ALIB_THREADS( , SharedLock* lock) ,
339 const system::PathString& filePath= system::NULL_PATH )
340 { if (HasListeners()) notifyListeners(event, file IF_ALIB_THREADS(,lock), filePath); }
341 #endif
342
343 /// @return \c true if listeners are registered with this file tree, \c false otherwise
344 bool HasListeners() { return listeners.size() > 0; }
345
346 /// Inserts or removes a listener to a specific file.
347 /// @param insertOrRemove Denotes whether the listener should be inserted or removed.
348 /// (Only enum elements \b ContainerOp::Insert or \b ContainerOp::Remove
349 /// must be passed.)
350 /// @param listener The listener to register.
351 /// @param event The event to listen to.
352 /// @param file The file to listen to.
353 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
355 FTreeListener* listener,
357 const File& file )
358 {
360 "Event::Creation will never be invoked with this listener-registration-type." )
361 registerListener( listener,
362 insertOrRemove,
363 event,
364 &file, nullptr,
368 }
369
370 /// Inserts or removes a listener for all files that share the given \p{fileName}.
371 /// @param insertOrRemove Denotes whether the listener should be inserted or removed.
372 /// (Only enum elements \b ContainerOp::Insert or \b ContainerOp::Remove
373 /// must be passed.)
374 /// @param listener The listener to register.
375 /// @param event The event to listen to.
376 /// @param fileName The name of one or more files to listen to.
377 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
379 FTreeListener* listener,
381 const system::PathString& fileName )
382 {
383 ALIB_ASSERT_ERROR( fileName.IsNotEmpty(), "VARIABLES", "Empty file name given." )
384 registerListener( listener, insertOrRemove, event,
385 nullptr, nullptr, fileName,
387 }
388
389
390 /// Inserts or removes a listener for all files below the subtree specified by the
391 /// given \p{cursor}.
392 /// @param insertOrRemove Denotes whether the listener should be inserted or removed.
393 /// (Only enum elements \b ContainerOp::Insert or \b ContainerOp::Remove
394 /// must be passed.)
395 /// @param listener The listener to register.
396 /// @param event The event to listen to.
397 /// @param cursor The parent node in the tree of files to monitor.
398 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
399 void MonitorPath( lang::ContainerOp insertOrRemove,
400 FTreeListener* listener,
402 const FTree::Cursor& cursor )
403 {
404 registerListener( listener,
405 insertOrRemove,
406 event,
407 nullptr, &cursor,
411 }
412
413
414
415 /// Inserts or removes a listener for all files below the subtree specified by the
416 /// given \p{startPath}.
417 /// \attention Note that the parameter \p{pathPrefix} has to be a portion of a
418 /// \alib{system;Path::MakeReal;real path}.
419 /// @param insertOrRemove Denotes whether the listener should be inserted or removed.
420 /// (Only enum elements \b ContainerOp::Insert or \b ContainerOp::Remove
421 /// must be passed.)
422 /// @param listener The listener to register.
423 /// @param event The event to listen to.
424 /// @param pathPrefix The path prefix of the subtree of files to monitor. Note that a
425 /// missing leading separator character will be added.
426 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
428 FTreeListener* listener,
430 const system::PathString& pathPrefix )
431 {
432 ALIB_ASSERT_ERROR( pathPrefix.IsNotEmpty(), "VARIABLES", "Empty path prefix given." )
433 registerListener( listener,
434 insertOrRemove,
435 event,
436 nullptr, nullptr,
438 }
439
440 /// Inserts or removes a listener for all files whose path (excluding the file name) contains
441 /// the given \p{pathSubstring}.
442 /// \attention Note that the parameter \p{pathSubstring} has to be a portion of a
443 /// \alib{system;Path::MakeReal;real path}.
444 /// @param insertOrRemove Denotes whether the listener should be inserted or removed.
445 /// (Only enum elements \b ContainerOp::Insert or \b ContainerOp::Remove
446 /// must be passed.)
447 /// @param listener The listener to register.
448 /// @param event The event to listen to.
449 /// @param pathSubstring The substring to match in the path (including the file name)
450 /// of the files to monitor.
451 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
453 FTreeListener* listener,
455 const system::PathString& pathSubstring )
456 {
457 ALIB_ASSERT_ERROR( pathSubstring.IsNotEmpty(), "VARIABLES", "Empty path substring given." )
458 registerListener( listener,
459 insertOrRemove,
460 event,
461 nullptr, nullptr,
463 pathSubstring );
464 }
465
466 /// Removes all registrations of the given listener.
467 /// @param listener The listener to remove.
468 /// @return The number of registrations that have been removed.
469 /// @see Chapter \ref alib_files_monitoring of the Programmer's Manual of camp \alib_files_nl.
471 int MonitorStop( FTreeListener* listener );
472}; // FTree
473
474
475/// Utility type which implements \alib{monomem;TSharedMonoVal} with class \alib{files;FTree}.
476/// The result of combining both is an automatic pointer to a \b %FTree that is "self-contained"
477/// in the first buffer of a \alib{MonoAllocator} together with the allocator itself.
478/// The tree is deleted and all associated memory is freed when the last copy of the pointer
479/// goes out of scope.
480///
481/// Along with the \b FTree, this shared object includes a \alib{threads;SharedLock}.
482/// See chapter \ref alib_contmono_smv_locking of the Programmer's Manual of module \alib_monomem
483/// for further information on how to protect the contents of this type against
484/// thread-racing-conditions.
485///
486/// @tparam TLock The lock type passed to the template parameter of parent type
487/// \alib{monomem;TSharedMonoVal} with the same name.<br>
488/// With the inclusion of module \alib_threads in the \alibbuild, the type-alias
489/// #alib::SharedFTree chooses type \alib{threads;SharedLock}.<br>
490/// Otherwise, in case \alib is compiled without threading support, the alias chooses
491/// <c>void</c>.<br>
492/// If it is assured that no racing-conditions occur with shared instances in
493/// multithreaded software, the using code may pass <c>void</c> here as well.
494template<typename TLock>
495struct TSharedFTree : monomem::TSharedMonoVal<FTree, HeapAllocator, TLock>
496{
497 /// Exposed shortcut to the base type.
499
500 /// Constructs an empty instance, hence a cleared automatic pointer.
501 TSharedFTree() = default;
502
503 /// Constructs an empty instance from \c std::nullptr.
504 /// This constructor is necessary to allow assignment of \c nullptr to values of this type,
505 /// which clears the automatic pointer.
506 TSharedFTree(std::nullptr_t) noexcept {}
507
508 /// Constructor.
509 /// Calls the constructor of parent \b TSharedMonoVal and then invokes
510 /// \alib{monomem;TSharedMonoVal::ConstructT} passing the mono allocator that the
511 /// parent creates this instance in.<br>
512 /// Furthermore calls DbgCriticalSections to enable assertions to locked usage.
513 /// @param initialBufferSizeInKB The initial size of memory buffers.
514 /// Passed to the allocator given with parent class
515 /// \alib{monomem;TSharedMonoVal}.
516 /// @param bufferGrowthInPercent Optional growth factor in percent, applied to the buffer size
517 /// with each next buffer allocation.
518 /// Passed to the allocator given with parent class
519 /// \alib{monomem;TSharedMonoVal}.
520 /// Should be set to \c 200, to double the size with each
521 /// allocation.
522 /// Defaults to \c 200.
523 TSharedFTree( size_t initialBufferSizeInKB,
524 unsigned int bufferGrowthInPercent = 200 )
525 : Base(initialBufferSizeInKB, bufferGrowthInPercent)
526 {
529 ALIB_DBG(Base::GetAllocator().DbgName= "SharedFTree";)
530 }
531
532 /// Defaulted copy-assignment operator.
533 /// @return A reference to <c>this</c>.
535
536 /// Destructor.
537 /// Calls #DbgCriticalSections to stop checking the integrated \p{TLock}.
539
540 #if DOXYGEN
541 /// Enables or disables critical section checks between the contained \p{T} and the likewise
542 /// contained \p{TLock}.<br>
543 /// In case \p{TLock} equals <c>void</c> or if symbol \ref ALIB_DEBUG_CRITICAL_SECTIONS is not
544 /// set, this method is empty (and its use is optimized out).
545 /// @param onOff The switch.
547 #else
548 template<typename TRequires= typename Base::LockType>
549 requires( !std::same_as<TRequires, void> )
551 {
552 #if ALIB_DEBUG_CRITICAL_SECTIONS
553 if ( !Base::IsNulled() )
554 {
555 if( onOff == lang::Switch::On ) {
556 Base::Self().NodeTable().dcs .DCSLock= &Base::GetLock();
559 }
560 else {
561 Base::Self().NodeTable().dcs .DCSLock= nullptr;
562 Base::GetAllocator().DbgCriticalSectionsPH.Get()->DCSLock= nullptr;
563 Base::Self().Pool .DCSLock= nullptr;
564 }
565 }
566 #else
567 (void) onOff;
568 #endif
569 }
570
571 template<typename TRequires= typename Base::LockType>
572 requires std::same_as<TRequires, void>
574 #endif
575
576 /// Clears all scanned or otherwise inserted data and re-initializes this object to its
577 /// constructor defaults and resets the \b MonoAllocator of the parent class.<br>
578 ///
579 /// All shared instances remain valid (while, of course, their content is likewise reset).
580 void Reset()
581 {
582 // just invoke parent's reset method passing the mono allocator to the constructor.
586 }
587
588}; // struct TSharedFTree
589
590// =================================================================================================
591// ===================== Implementation of the node mainer =====================
592// =================================================================================================
593#if !DOXYGEN
595
596void detail::FTreeNodeHandler::InitializeNode( TTree& tree, TTree::Node& node )
597{
598 node.name.storage.Allocate( static_cast<FTree&>(tree).Pool, node.name.key );
599}
600
601void detail::FTreeNodeHandler::FreeNode( TTree& tree, TTree::Node& node )
602{
603 // delete node name
604 auto& pool= static_cast<FTree&>(tree).Pool;
605
606 if ( node.name.storage.Length() )
607 pool.free( const_cast<TTree::CharacterType*>(node.name.storage.Buffer()),
608 size_t(node.name.storage.Length()) * sizeof(TTree::CharacterType) );
609
610 // recycle extended info structs
611 FInfo& value= node.data;
612 auto extendedInfo= value.GetExtendedInfo();
613 if( extendedInfo == nullptr )
614 return;
615
616 if( value.IsSymbolicLink() )
617 {
618 // delete old values
619 FInfo::EISymLinkFile& ei= *static_cast<FInfo::EISymLinkFile*>(extendedInfo);
620
621 if( ei.RealTarget.Buffer() != ei.Target.Buffer()
622 && ei.RealTarget.Buffer() != nullptr )
623 pool().Free( ei.RealTarget.Buffer(), ei.RealTarget.Length() + 1 );
624
625 if( ei.Target.Buffer() != nullptr )
626 pool().Free( ei.Target.Buffer(), ei.Target.Length() + 1 );
627
628 if( value.Type() == FInfo::Types::SYMBOLIC_LINK )
629 pool().Delete( static_cast<FInfo::EISymLinkFile*>(extendedInfo) );
630 else
631 pool().Delete( static_cast<FInfo::EISymLinkDir*>(extendedInfo) );
632
633 // clear to be able to check double use in debug mode
634 ALIB_DBG( value.SetExtendedInfo(nullptr) );
635 return;
636 }
637
639 "FILES", "Given node is not a directory or symbolic link but still has extendedInfo set." )
640
641 pool().Delete( reinterpret_cast<FInfo::EIDirectory*>(extendedInfo) );
642
643 // clear to be able to check double use in debug mode
644 ALIB_DBG( value.SetExtendedInfo(nullptr) );
645}
646#include "ALib.Lang.CIMethods.H"
647#endif
648
649
650//==================================================================================================
651/// This class represents nodes in \alib{files;FTree} instances.
652/// While class \b FTree is just a rather small wrapper around its base class
653/// \alib{containers;StringTree}, this class \b File is a wrapper around class
654/// \alib{containers;StringTree::Cursor}.
655/// With that, instances of this class are very lightweight and contain only two pointers: One
656/// pointing to the \b %FTree that an instance originates from, the second pointing to the
657/// node in the tree.
658///
659/// It is important to understand that this class has three interfaces.
660/// 1. The direct interface as exposed with this class.
661/// 2. Using <c>operator-></c> the attached data instance of type \alib{files;FInfo} is accessed.
662/// 3. The method #AsCursor casts an instance to the (otherwise protected) type \b Cursor of the
663/// underlying string tree.
664///
665/// To get a thorough understanding of why this split exists and what purpose which of the
666/// three interfaces serve, a basic understanding of container type class
667/// \alib{containers;StringTree} is very helpful.
668/// A similar design principle is implemented with class \alib{variables;Variable} of module
669/// \alib_variables. A technical explanation to why base class <b>FTree::Cursor</b> is protected
670/// there in the same fashion is \alib{variables;Variable::AsCursor;given here}.
671///
672/// @see
673/// - For a quick tutorial about using \alib files, consult the tutorial-style
674/// \ref alib_mod_files "Programmer's Manual" of camp \alib_files_nl.
675/// - For this class, a \ref alibtools_debug_helpers_gdb "pretty printer" for the
676/// GNU debugger is provided.
677/// - Instances of this type are \ref alib_strings_assembly_ttostring "appendable" to
678/// class \b %AString. If done, the full path and file name is written to the target string.
679//==================================================================================================
680class File : protected FTree::Cursor
681{
682 public:
683 /// The base cursor type of the internal \b StringTree. This type is used to perform
684 /// cursor operations on \b FTree instances.
686
687 /// The constant version of type #Cursor.
689
690
691 /// Returns a \c reference to the file tree that this file resides in.
692 /// @return The associated file tree instance.
694 { return static_cast<FTree&>(Tree()); }
695
696 File() = default;
697
698 /// Constructor taking a file tree. After construction, this file will point to the root
699 /// node <c>"/"</c> of the tree.
700 /// @param pTree The tree to associate this file instance with.
701 File( FTree& pTree )
702 : Cursor( pTree.Root() ) {}
703
704 /// Constructs an instance of this type from its base type.
705 /// This constructor is for advanced use when direct operations with class \b StringTree and
706 /// its cursor and iterator types are performed.
707 /// @param cursor The \b StringTree cursor representing a file.
708 File( const Cursor& cursor )
709 : Cursor(cursor) {}
710
711 /// Sets this \b Cursor to point to the same file (node in the \alib{files;FTree}) as the given
712 /// \p{other}.
713 /// @param other The node to let this file instance point to.
714 /// @return A reference to \c this.
715 File& operator=( const Cursor& other )
716 {
717 Cursor::operator=( other );
718 return *this;
719 }
720
721 /// Provides \c const access to members of contained \alib{files;FInfo} record. Note that
722 /// access to a mutable version of the type is available with method #GetMutableFInfo.
723 /// @return A non-writable pointer to the embedded \b FInfo data.
724 const FInfo* operator->() const { return Cursor::operator->(); }
725
726 /// Provides \c access to members of contained \alib{files;FInfo} record. Note that
727 /// \c const access is available with method #operator->.<br>
728 /// Changes to the values should be done with caution. Usually the values are only set when
729 /// scanning files or using certain interface methods of this class.
730 /// @return A \b writable pointer to the embedded \b FInfo data.
731 FInfo& GetMutableFInfo() { return Value(); }
732
733 /// This is an explicit <c>cast operator</c> to the protected base class.
734 /// \note For details on the code design which makes this method necessary, consult the
735 /// documentation of the same concept found with method \alib{variables;Variable::AsCursor}.
736 /// @return This instance cast 'down' to its protected base class.
737 Cursor& AsCursor() { return static_cast<Cursor&>(*this); }
738
739 /// \c const version of the <c>cast operator</c> to the protected base class.
740 /// @return This instance cast 'down' to its protected base class.
741 const Cursor& AsCursor() const { return static_cast<const Cursor&>(*this); }
742
743
745 /// Publish protected method
746 /// \doxlinkproblem{classalib_1_1containers_1_1StringTree_1_1TCursor.html;a58dad13c22c77ff79290aa72770b06ce;StringTree::TCursor::Name}.
747 /// @return A constant reference to the name of the represented node.
748 using Cursor::Name;
750
751 /// Returns the substring from the beginning of \b %Name() up to (and not including) the last
752 /// period <c>'.'</c> character which is not located at the start of the name.
753 /// With that, edge cases are treated as follows:
754 /// - A filename like "filename.ext.txt" -> "filename.ext"
755 /// - A filename like ".profile" results to identity ".profile".
756 /// @return The filename excluding the #Extension.
758 {
759 system::PathString result= Name();
760 auto dotPos= result.LastIndexOf('.');
761 return dotPos < 2 ? result
762 : result.Substring( 0, dotPos );
763 }
764
765 /// Returns the file extension, which is the substring behind the last period <c>'.'</c>
766 /// character which is not located at the start of the name.
767 /// (A filename like ".profile" is not treated to have an extension).
768 /// @return The extension found in the filename. An empty string if none is found.
770 {
771 auto dotPos= Name().LastIndexOf('.');
772 return dotPos < 2 ? system::EMPTY_PATH
773 : Name().Substring( dotPos + 1 );
774 }
775
776 /// Returns the path to this file. This excludes this files' name as well as a trailing
777 /// separation character. If this file represents the root folder of the file tree,
778 /// nothing is written to \p{target}.
779 ///
780 /// @see To receive the full path of this file, including this %files' name, use
781 /// #AsCursor and invoke
782 /// \doxlinkproblem{classalib_1_1containers_1_1StringTree_1_1TCursor.html;a095127b50447399e888b0d382e82014d;Cursor::AssemblePath}.
783
784 /// @param target The string buffer to append the path to.
785 /// @param targetData Denotes whether \p{target} should be cleared before
786 /// appending the path. Defaults to \b CurrentData::Clear.
787 /// @return The given \b AString to allow concatenated operations.
790 {
791 if( targetData == lang::CurrentData::Clear )
792 target.Reset();
793 if( !AsCursor().IsRoot() )
794 AsCursor().Parent().AssemblePath(target, lang::CurrentData::Keep);
795 return target;
796 }
797
798 /// Retrieves the file's owner's name.
799 /// @return The name of the owner of the file.
800 const NString& GetOwnerName() const { return GetFTree().GetOGResolver().GetOwnerName(Value());}
801
802 /// Retrieves the file's group name.
803 /// @return The name of the group of the file.
804 const NString& GetGroupName() const { return GetFTree().GetOGResolver().GetGroupName(Value());}
805
806 /// Tests if custom data is attached to this file.
807 /// @see Methods #AttachCustomData, #GetCustomData, #DeleteCustomData, and
808 /// \alib{files;FTree::DeleteAllCustomData}.
809 /// @return <c>true</c> if custom data is attached to this file, <c>false</c> otherwise.
810 bool HasCustomData() const
811 {
812 return Value().custom != nullptr;
813 }
814
815 /// Retrieves a custom data object.
816 /// With debug-compilations it is asserted that #HasCustomData() returns <c>true</c>
817 /// and that \p{TCustom} is the same as set.
818 /// @tparam TCustom The type of custom data requested. In case no data was previously attached,
819 /// yet, the constructor of this type is called on the new allocated memory.
820 /// @see Methods #AttachCustomData, #HasCustomData, #DeleteCustomData, and
821 /// \alib{files;FTree::DeleteAllCustomData}.
822 /// @return The custom data record.
823 template<typename TCustom>
824 TCustom& GetCustomData()
825 {
826 ALIB_ASSERT_ERROR( Value().custom != nullptr, "FILES", "No custom data set." )
827 ALIB_ASSERT_ERROR( &typeid(TCustom) == Value().dbgCustomType, "FILES",
828 "Requested custom object type mismatch.\n"
829 " Attached type: <{}>\n"
830 " Given type: <{}>" , &typeid(TCustom), Value().dbgCustomType )
831
832 return *reinterpret_cast<TCustom*>( Value().custom );
833 }
834
835 /// Allocates a custom object attached to this file using the
836 /// \alib{monomem;TPoolAllocator;PoolAllocator} of the \b FTree.
837 ///
838 /// @see Methods #GetCustomData, #HasCustomData, #DeleteCustomData, and
839 /// \alib{files;FTree::DeleteAllCustomData}.
840 /// @tparam TCustom The type of custom data associated to the \b FTree that this file belongs
841 /// to.
842 /// @tparam TArgs Types of the variadic arguments \p{args} that construct \p{TCustom}.
843 /// @param args Variadic arguments forwarded to the constructor of \p{TCustom}.
844 /// @return The custom data record.
845 template<typename TCustom, typename... TArgs>
846 TCustom& AttachCustomData(TArgs&&... args)
847 {
848 ALIB_ASSERT_ERROR( Value().custom == nullptr, "FILES", "Custom data already set." )
849
850 auto* custom= GetFTree().Pool().template New<TCustom>( std::forward<TArgs>(args)... );
851 Value().custom= custom;
852ALIB_DBG(Value().dbgCustomType= &typeid(TCustom); )
853 return *custom;
854 }
855
856 /// Destructs and deletes the custom data attached to this file.
857 /// With debug-compilations it is asserted that #HasCustomData() returns <c>true</c>
858 /// and that \p{TCustom} is the same as set.
859 /// @see Methods #AttachCustomData, #GetCustomData, #HasCustomData, and
860 /// \alib{files;FTree::DeleteAllCustomData}.
861 /// @tparam TCustom The object type to optionally store in tree nodes.
862 template<typename TCustom>
864 {
866 GetFTree().Pool.free( Value().custom, sizeof(TCustom) );
867 Value().custom= nullptr;
868 }
869
870 /// Writes the permission flags to the given \p{target} string in the
871 /// same format as GNU/Linux command <em>'ls -l'</em> does.
872 /// @param target The target string to write into.
873 /// @return The given target to allow concatenated calls.
874 AString& FormatAccessRights(AString& target) const;
875
876
877 // =============================================================================================
878 /// Writes formatted information on this file to given string buffer \p{target}.
879 /// Within the pattern string \p{format}, different symbols are interpreted as tokens.
880 /// Spaces between tokens are written as given.
881 /// Strings within the format text that should not be interpreted as tokens may be given
882 /// in single quotes.
883 /// Two consecutive single quotes will be replaced to one single quote.<br>
884 ///
885 /// Tokens are defined in lower case letters.
886 /// If given with upper case letters, the generated string is converted to upper case letters.
887 ///
888 /// This method supports the following tokens:
889 ///
890 /// <center>Token</center> | <center>Description</center>
891 /// - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
892 /// a |Invokes #FormatAccessRights.</TD> </TR>
893 /// dm{DATEFORMAT}|The \alib{files::FInfo;MDate;modification date} of this file. This token is optionally followed by a "DATEFORMAT" string given in curly braces. For specification information, see \alib{format;CalendarDateTime::Format}.</TD> </TR>
894 /// db{DATEFORMAT}|Same as 'dm', but uses the \alib{files::FInfo;BDate;creation date} of this file.</TD> </TR>
895 /// dc{DATEFORMAT}|Same as 'dm', but uses the \alib{files::FInfo;CDate;change date} of this file.</TD> </TR>
896 /// da{DATEFORMAT}|Same as 'dm', but uses the \alib{files::FInfo;ADate;date of last access} to this file.</TD> </TR>
897 /// fx |Prints <c>'m'</c> if \alib{files::FInfo;IsCrossingFS} returns \c true, <c>'-'</c> otherwise.
898 /// fa |Prints <c>'a'</c> if \alib{files::FInfo;IsArtificialFS} returns \c true, <c>'-'</c> otherwise.
899 /// gi[{width[,alignment]}] |The ID of the user group of the file.
900 /// gn[{width[,alignment]}] |The name of the user group of the file.
901 /// h |The \alib{files::FInfo;QtyHardLinks;number of hard links} pointing to this file.</TD> </TR>
902 /// l |In case of Symbolic links, prints " -> linktarget". if the linktarget is a relative path, then the absolute path is appended in round brackets.</TD> </TR>
903 /// na |The name of the file.</TD> </TR>
904 /// ns |The \alib{files::File;Stem;stem} of the file.</TD> </TR>
905 /// ne |The \alib{files::File;Extension;extension} of the file.</TD> </TR>
906 /// np |The \alib{files::File;Path;path} to the file, excluding the file name and a trailing separation character.</TD> </TR>
907 /// oi[{width[,alignment]}] |The ID of the owner of the file.
908 /// on[{width[,alignment]}] |The name of the owner of the file.
909 /// q |The scan \alib{files::FInfo;Quality;quality} as resourced with enum \alib{files::FInfo;Qualities}.</TD> </TR>
910 /// rd |Recursively counted subfolders.</TD> </TR>
911 /// rf |Recursively counted files.</TD> </TR>
912 /// re |Recursively counted access errors.</TD> </TR>
913 /// rb |Recursively counted broken links.</TD> </TR>
914 /// qqq |The scan \alib{files::FInfo;Quality;quality}, encoded in three characters. The conversion is resourced with enum \alib{files::FInfo;Qualities3Letters}.</TD> </TR>
915 /// s[{unit}] |The size of the file. See the explanation below.</TD> </TR>
916 /// t |The \alib{files::FInfo;Type;type}, encoded in a single character. The conversion is resourced with enum \alib{files::FInfo;TypeNames1Letter}.</TD> </TR>
917 /// tt |The \alib{files::FInfo;Type;type}, encoded in two characters. The conversion is resourced with enum \alib{files::FInfo;TypeNames2Letters}.</TD> </TR>
918 /// ttt |The \alib{files::FInfo;Type;type}, encoded in three characters. The conversion is resourced with enum \alib{files::FInfo;TypeNames3Letters}.</TD> </TR>
919 /// tttt |The \alib{files::FInfo;Type;type}, as a full word. The conversion is resourced with enum \alib{files::FInfo;Types}.</TD> </TR>
920 ///
921 /// \par Fields and Alignment
922 /// Any of the tokens above may be followd by <b>{width[,Alignment]}</b>. In words:
923 /// a pair of curly braces that contains an integral value specifying a field width
924 /// and, optionally and seperated by a comma, an \alib{lang;Alignment,alignment} specifier.
925 /// If so, a corresponding field, using spaces as padding character, is printed.
926 ///
927 /// \par Printing sizes:
928 /// Token <c>"s[(unit)]"</c> is used to print file sizes.
929 /// The optional unit string in curly braces may have one the following values:
930 /// - <c>IEC</c>: Chooses \alib{format;ByteSizeIEC;IEC standard} with automatic
931 /// detection of an approiate magnitude. The unit of the magnitude found (<c>"B"</c>,
932 /// <c>"KiB"</c>, <c>"MiB"</c>, <c>"GiB"</c>,...) is added to the output.
933 /// This is the default, if the optional unit-partis omited.
934 /// - <c>SI</c>: Chooses \alib{format;ByteSizeSI;SI standard} with automatic
935 /// detection of an approiate magnitude. The unit of the magnitude found (<c>"B"</c>,
936 /// <c>"kB"</c>, <c>"MB"</c>, <c>"GB"</c>,...) is added to the output.
937 /// - One of the more than 20 possible entity names of either IEC or SI standard.
938 /// In this case, the unit is \b not included after the number, because this way it can be
939 /// optionally added to the format string by using a pair of single quotes <c>'</c>.
940 /// \par
941 /// With the two automatic modes <c>IEC</c> and <c>SI</c>, namespace function
942 /// \alib{format::FormatByteSize} is used.<br>
943 ///
944 /// \par
945 /// For formatting the file size numbers, this method retrieves formatting hints with
946 /// \alib{files;FTree::GetNumberFormat}. With that, the details of the format can
947 /// be specified "per FTree". Manipulations of this object before invoking this methods,
948 /// allows specifying output widths, group characters, decimal separation character, and so
949 /// forth.
950 ///
951 ///
952 /// \par Printing owner and group:
953 /// For printing owner and group names, those have to be queried from the OS.
954 /// To increase performance, the resolver utility instance received with
955 /// \alib{files;FTree::GetOGResolver} is used. The use of this instance has to be protected
956 /// against racing conditions in multithreaded applications. This means if two threads
957 /// invoke this method on \b %File object that belong to the same \b %FTree, a locking
958 /// mechanism has to be used, to avoid undefined behavior. (For example by using class
959 /// \alib{threads;Lock}.)
960 ///
961 /// \par Sample
962 /// As a sample, the following format string mimics the output of GNU/Linux console command
963 /// <em>ls -l</em>:
964 ///
965 /// "ta h on gn s dm nal"
966 ///
967 /// @see This method is invoked by \alib{files;FFormat_File}, which is an implementation of
968 /// box-function \alib{format;FFormat}. With hat, objects of this type can be used
969 /// as arguments for \alib{format;FormatterPythonStyle}.
970 /// The format specifier passed to this method has to be placed behind the colon
971 /// in the placeholder field, as in <c>"{:FORMATSPEC}"</c>.
972 /// If no format string is given in the placeholder, the string
973 /// <b>"ta h on gn s dm nal"</b> is used, which is resourced in camp
974 /// \alib{FILES} under key <b>"FFMT"</b>.
975 ///
976 ///
977 /// @param format The format pattern string.
978 /// @param target A reference to an AString that gets the result of the format processing
979 /// appended.
980 /// @param targetData If \c CurrentData::Keep (the default) the string is appended to \p{target}.
981 /// if \c CurrentData::Clear, \p{target} is cleared.
982 /// @param numberFormat The number format specification to use. Defaults to \c nullptr which
983 /// chooses \alib{format;NumberFormat::Computational}.
984 /// @returns \p{target} (for convenience).
985 // =============================================================================================
987 AString& Format( Substring format,
988 AString& target,
990 NumberFormat* numberFormat = nullptr ) const;
991
992}; // class File
993
994// =================================================================================================
995// ================== Implementation of inlines of class FTree =====================
996// =================================================================================================
997File FTree::Root() { return File( base::Root() ); }
998
999// =================================================================================================
1000// ============================= Box-function FFormat_File =============================
1001// =================================================================================================
1002/// This implementation of boxing function \b FFormat for objects of type \b File, simply
1003/// invokes the method \alib{files;File::Format} and thus, using the format specification is given
1004/// with that method.
1005///
1006/// Note that the \alib{strings;TNumberFormat;NumberFormat} instance used for formatting file sizes
1007/// and similar, does not use the instance given with parameter \p{nf}. Instead, the instance
1008/// retrieved with \alib{files;FTree::GetNumberFormat} is used. This feature enables to
1009/// determine the number format separately for file data output, independent of the settings the
1010/// formater uses.
1011///
1012/// If the parameter \p{formatSpec} is empty, the string <b>"ta h on gn s dm nal"</b> is used,
1013/// which is resourced in camp \alib{FILES} under the key <b>"FFMT"</b>.
1014///
1015/// @param box The box containing the file object.
1016/// @param formatSpec The format string.
1017/// @param nf The number format specification to use.
1018/// @param target The target string to write to.
1019void FFormat_File( const Box& box, const String& formatSpec, NumberFormat& nf, AString& target );
1020
1021} // namespace alib[::files]
1022
1023/// Type alias in namespace \b alib.
1025
1026#if !ALIB_SINGLE_THREADED || DOXYGEN
1027DOX_MARKER([DOX_MANUAL_ALIASES_FTREE])
1028/// Type alias in namespace \b alib.
1029using SharedFTree= files::TSharedFTree<SharedLock>;
1030DOX_MARKER([DOX_MANUAL_ALIASES_FTREE])
1031#else
1033#endif
1034
1035/// Type alias in namespace \b alib.
1037
1038} // namespace [alib]
1039
1040
1041// #################################################################################################
1042// struct AppendableTraits<Cursor>
1043// #################################################################################################
1044
1045// Faking all template specializations of namespace strings for doxygen into namespace
1046// strings::APPENDABLES to keep the documentation of namespace string clean!
1047namespace alib::strings {
1048#if DOXYGEN
1049namespace APPENDABLES {
1050#endif
1051
1052/// Specialization of functor \alib{strings;AppendableTraits} for type \alib{files;File}.
1054{
1055 /// Writes the file's complete path (including the filename) to the given AString.
1056 /// @param target The \b NAString that \b Append was invoked on.
1057 /// @param file The file.
1059};
1060
1061/// Specialization of functor \alib{strings;AppendableTraits} for type \alib{files;File}.
1063{
1064 /// Writes the file's complete path (including the filename) to the given AString.
1065 /// @param target The \b WAString that \b Append was invoked on.
1066 /// @param file The file.
1068};
1069
1070#if DOXYGEN
1071} // namespace alib::strings[APPENDABLES]
1072#endif
1073} // namespace [alib::strings]
1074
1075
1076
1078
1079
1080
1081
1082//--------------------------------------- Debug Dump ---------------------------------------
1083#if ALIB_DEBUG
1084ALIB_EXPORT namespace alib::files {
1085
1086 /// The format string used with namespace function \alib{files;DbgDump}.<br>
1087 /// Defaults to <c>"{:ta h{2,r} on{10,r} gn{10,r} s(IEC){10,r} dm qqq FxFa (rd{3r}' D' rf{3r}' F' re{2r}' EA' rb{2r}'BL) 'nf l}\n"</c><br>
1088 /// This global variable is only available with debug-compilations.
1089 extern String DBG_DUMP_FORMAT;
1090
1091 /// Dumps the given branch of this object's tree.<br>
1092 /// This function is only available with debug-compilations.
1093 /// @param target The target string buffer.
1094 /// @param tree The tree to dump.
1095 /// @param includedTypes Optional filter for types. Defaults to 'all'.
1096 /// @param startNode The start node. If this is not
1097 /// \doxlinkproblem{classalib_1_1monomem_1_1StringTree_1_1TCursor.html;ac532c4b500b1a85ea22217f2c65a70ed;a valid node;alib::monomem::StringTree::TCursor::IsValid},
1098 /// the root node is chosen. Defaults to an invalid cursor.
1099 /// @param depth The maximum depth of recursion. Defaults to unlimited depth.
1100 /// @return The given \p{target} to allow concatenated operations.
1101 ALIB_DLL
1103 FTree& tree ,
1105 FTree::Cursor startNode = FTree::Cursor(),
1106 unsigned int depth = (std::numeric_limits<unsigned int>::max)() );
1107
1108
1109
1110} // namespace [alib::files]
1111#endif
StringTree(AllocatorType &allocator, CharacterType pathSeparator)
The entry type which is embedded in each tree node.
Definition finfo.inl:15
constexpr ExtendedEntryInfo * GetExtendedInfo() const
Definition finfo.inl:418
@ DIRECTORY
Directory/folder.
Definition finfo.inl:26
ALIB_DLL FTree(MonoAllocator &allocator)
Definition ftree.cpp:115
PoolAllocator Pool
Definition ftree.inl:163
ALIB_DLL void notifyListeners(FTreeListener::Event event, File &file, SharedLock *lock, const system::PathString &filePath)
Definition ftree.cpp:232
NumberFormat numberFormat
Definition ftree.inl:174
void AllocateExtendedInfo(Cursor &node, const system::PathString &symLinkDest, const system::PathString &symLinkRealPath)
Definition ftree.inl:263
OwnerAndGroupResolver ogResolver
Definition ftree.inl:178
bool HasListeners()
Definition ftree.inl:344
void MonitorFilesByName(lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const system::PathString &fileName)
Definition ftree.inl:378
void DeleteAllCustomData()
Definition ftree.inl:278
ALIB_DLL int MonitorStop(FTreeListener *listener)
Definition ftree.cpp:210
friend class files::File
Friendship declaration.
Definition ftree.inl:170
void MonitorPath(lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const FTree::Cursor &cursor)
Definition ftree.inl:399
OwnerAndGroupResolver & GetOGResolver()
Definition ftree.inl:313
NumberFormat & GetNumberFormat()
Definition ftree.inl:309
void MonitorPathSubstring(lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const system::PathString &pathSubstring)
Definition ftree.inl:452
void MonitorPathPrefix(lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const system::PathString &pathPrefix)
Definition ftree.inl:427
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)
Definition ftree.cpp:160
ALIB_DLL ~FTree()
Destructor.
Definition ftree.cpp:133
static ALIB_DLL void FixSums(Cursor directory)
Definition ftree.cpp:272
StringTree< MonoAllocator, FInfo, detail::FTreeNodeHandler > base
Type alias of this classes' base class.
Definition ftree.inl:167
List< MonoAllocator, ListenerRecord > listeners
The list of registered listeners.
Definition ftree.inl:195
void Notify(FTreeListener::Event event, File &file, SharedLock *lock, const String &filePath=NULL_STRING)
void MonitorDistinctFile(lang::ContainerOp insertOrRemove, FTreeListener *listener, FTreeListener::Event event, const File &file)
Definition ftree.inl:354
Path & AssemblePath(Path &target, lang::CurrentData targetData=lang::CurrentData::Clear) const
Definition ftree.inl:788
const FInfo * operator->() const
Definition ftree.inl:724
TCustom & GetCustomData()
Definition ftree.inl:824
FTree & GetFTree() const
Definition ftree.inl:693
FInfo & GetMutableFInfo()
Definition ftree.inl:731
TCustom & AttachCustomData(TArgs &&... args)
Definition ftree.inl:846
FTree::Cursor Cursor
Definition ftree.inl:685
const NString & GetOwnerName() const
Definition ftree.inl:800
bool HasCustomData() const
Definition ftree.inl:810
FTree::ConstCursor ConstCursor
The constant version of type Cursor.
Definition ftree.inl:688
File & operator=(const Cursor &other)
Definition ftree.inl:715
system::PathString Extension() const
Definition ftree.inl:769
const NString & GetGroupName() const
Definition ftree.inl:804
File(FTree &pTree)
Definition ftree.inl:701
ALIB_WARNINGS_RESTORE system::PathString Stem() const
Definition ftree.inl:757
Cursor & AsCursor()
Definition ftree.inl:737
File(const Cursor &cursor)
Definition ftree.inl:708
const Cursor & AsCursor() const
Definition ftree.inl:741
void DeleteCustomData()
Definition ftree.inl:863
lang::Placeholder< lang::DbgCriticalSections > DbgCriticalSectionsPH
bool IsNulled() const noexcept
AllocatorType & GetAllocator() noexcept
constexpr bool IsNotEmpty() const
Definition string.inl:371
integer LastIndexOf(TChar needle, integer startIndex=MAX_LEN) const
Definition string.inl:967
TString< TChar > Substring(integer regionStart, integer regionLength=MAX_LEN) const
Definition string.inl:386
#define ALIB_DLL
Definition alib.inl:496
#define IF_ALIB_THREADS(...)
Definition alib.inl:401
#define ALIB_WARNINGS_RESTORE
Definition alib.inl:705
#define ALIB_ASSERT_WARNING(cond, domain,...)
Definition alib.inl:1050
#define ALIB_WARNINGS_IGNORE_DOCS
Definition alib.inl:688
#define ALIB_BOXING_VTABLE_DECLARE(TMapped, Identifier)
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_DBG(...)
Definition alib.inl:836
#define ALIB_ASSERT_ERROR(cond, domain,...)
Definition alib.inl:1049
This namespace implements internals of namespace alib::files.
Definition ftree.cpp:59
alib::containers::detail::StringTreeBase< MonoAllocator, FInfo, FTreeNodeHandler, Recycling::Private > TTree
A shortcut to the base class of the base class of class FTree.
Definition ftree.inl:20
void FFormat_File(const alib::Box &box, const alib::String &formatSpec, alib::NumberFormat &nf, alib::AString &target)
Definition file.cpp:424
ALIB_DLL AString & DbgDump(AString &target, FTree &tree, EnumBitSet< FInfo::Types > includedTypes=EnumBitSet< FInfo::Types >(true), FTree::Cursor startNode=FTree::Cursor(), unsigned int depth=(std::numeric_limits< unsigned int >::max)())
String DBG_DUMP_FORMAT
ContainerOp
Denotes standard container operations.
Switch
Denotes if sth. is switched on or off.
@ On
Switch it on, switched on, etc.
@ Off
Switch it off, switched off, etc.
@ Keep
Chooses not no clear existing data.
@ Clear
Chooses to clear existing data.
void Destruct(T &object)
Definition tmp.inl:83
strings::TString< PathCharType > PathString
The string-type used with this ALib Module.
Definition path.inl:33
constexpr PathString NULL_PATH
A nulled path string.
Definition path.inl:51
strings::TAString< PathCharType, PoolAllocator > PathStringPA
A pool-allocated string representing a path.
Definition path.inl:46
constexpr PathString EMPTY_PATH
An empty path string.
Definition path.inl:54
std::filesystem::path::value_type PathCharType
Definition path.inl:12
files::FInfo FInfo
Type alias in namespace alib.
Definition finfo.inl:601
threads::SharedLock SharedLock
Type alias in namespace alib.
constexpr String NULL_STRING
A nulled string of the default character type.
Definition string.inl:2463
files::TSharedFTree< SharedLock > SharedFTree
Type alias in namespace alib.
Definition ftree.inl:1029
files::File File
Type alias in namespace alib.
Definition ftree.inl:1036
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
lang::TBitSet< TEnum, enumops::IterableTraits< TEnum >::End, enumops::IterableTraits< TEnum >::Begin > EnumBitSet
files::FTree FTree
Type alias in namespace alib.
Definition ftree.inl:1024
characters::wchar wchar
Type alias in namespace alib.
monomem::TPoolAllocator< MonoAllocator > PoolAllocator
strings::TString< nchar > NString
Type alias in namespace alib.
Definition string.inl:2390
strings::TNumberFormat< character > NumberFormat
Type alias in namespace alib.
monomem::TMonoAllocator< lang::HeapAllocator > MonoAllocator
system::Path Path
Type alias in namespace alib.
Definition path.inl:392
characters::nchar nchar
Type alias in namespace alib.
boxing::Box Box
Type alias in namespace alib.
Definition box.inl:1216
strings::TString< character > String
Type alias in namespace alib.
Definition string.inl:2381
strings::TSubstring< character > Substring
Type alias in namespace alib.
containers::List< TAllocator, T, TRecycling > List
Type alias in namespace alib.
Definition list.inl:746
HashTable< TAllocator, typename NodeKey::ValueDescriptor, typename NodeKey::Hash, typename NodeKey::EqualTo, lang::Caching::Enabled, TRecycling > nodeTable
virtual void Notify(File &file, Event event)=0
virtual ~FTreeListener()
Virtual destructor.
Definition ftree.inl:103
Event
The type of change that imposes the notification of a listener.
Definition ftree.inl:97
@ DeleteNode
A file or directory entry was deleted.
Definition ftree.inl:99
@ CreateNode
A file or directory entry was created.
Definition ftree.inl:98
Record used to manage registered listeners.
Definition ftree.inl:182
FTreeListener::Event event
The event to listen to.
Definition ftree.inl:184
system::PathStringPA fileName
If given, the file's name to listen to.
Definition ftree.inl:187
ConstCursorHandle file
If given, the files to listen to.
Definition ftree.inl:185
ConstCursorHandle subTree
If given, the path of files to listen to.
Definition ftree.inl:186
system::PathStringPA pathSubstring
(including the file name) of files to monitor.
Definition ftree.inl:190
FTreeListener * listener
The listener to register or dispose.
Definition ftree.inl:183
system::PathStringPA pathPrefix
to monitor.
Definition ftree.inl:188
TSharedFTree(size_t initialBufferSizeInKB, unsigned int bufferGrowthInPercent=200)
Definition ftree.inl:523
void DbgCriticalSections(lang::Switch onOff)
TSharedFTree()=default
Constructs an empty instance, hence a cleared automatic pointer.
TSharedFTree & operator=(const TSharedFTree &)=default
TSharedFTree(std::nullptr_t) noexcept
Definition ftree.inl:506
monomem::TSharedMonoVal< FTree, HeapAllocator, TLock > Base
Exposed shortcut to the base type.
Definition ftree.inl:498
static void FreeNode(TTree &tree, TTree::Node &node)
system::PathCharType CharacterType
Definition ftree.inl:40
static ALIB_DLL void AllocateExtendedInfo(StringTree< MonoAllocator, FInfo, detail::FTreeNodeHandler >::Cursor &node, const system::PathString &symLinkDest, const system::PathString &symLinkRealPath)
Definition ftree.cpp:62
static void InitializeNode(TTree &tree, TTree::Node &node)
system::PathString NameStringType
Definition ftree.inl:44
ALIB_DLL void operator()(TAString< nchar, lang::HeapAllocator > &target, const files::File &file)
ALIB_DLL void operator()(TAString< wchar, lang::HeapAllocator > &target, const files::File &file)