Burger::DirectorySearch Class Reference

Directory contents iteration class. More...

Collaboration diagram for Burger::DirectorySearch:

Public Member Functions
	DirectorySearch () noexcept
	Initialize a DirectorySearch class.
	~DirectorySearch ()
	Closes any open directory.
eError	open (Filename *pDirName) noexcept
	Open a directory for scanning.
eError	open (const char *pDirName) noexcept
	Open a directory for scanning.
const char *	get_next_entry (void) noexcept
	Iterate on a directory and return the next found filename.
eError	get_next_entry (DirectoryEntry_t *pOutput) noexcept
	Iterate on a directory and return the next found filename.
eError	get_next_entry (DirectoryEntry_t *pOutput, const char *pExt) noexcept
	Iterate on a directory and return the next found filename that matches a specific file extension.
void	close (void) noexcept
	Release all memory and close the directory.

Static Public Attributes
static const uintptr_t	kDefaultReserve = 32U
	Initial array size for DirectoryEntry_t records in m_Entries.

Protected Member Functions
eError	direntry_copy (DirectoryEntry_t *pOutput, const DirectoryEntry_t *pInput) noexcept
	Internal function for copying DirectoryEntry_t.

Protected Attributes
SimpleArray< DirectoryEntry_t >	m_Entries
	Directory cache of stored entries.
uintptr_t	m_uIndex
	Index to the m_Entries array for get_next_entry()

Private Member Functions
	DirectorySearch (const DirectorySearch &)=delete
DirectorySearch &	operator= (const DirectorySearch &)=delete
	DirectorySearch (DirectorySearch &&)=delete
DirectorySearch &	operator= (DirectorySearch &&)=delete

Private Attributes
String	m_NativePath
	Linux/Android only, folder path for calling stat()

Detailed Description

Directory contents iteration class.

---

To open and traverse a directory is this classes' main purpose. Given a BurgerLib formatted pathname, open the directory and iterate over it until all the names of the files contained are presented to the application for use.

Using it is very simple...

Burger::DirectorySearch MyDir;
// Open the directory for traversal
uint_t uError = MyDir.open("9:Directory");
if (!uError) {      // No error?
    DirectoryEntry_t Entry;
    while (!MyDir.get_next_entry(&Entry)) {
        printf("Found \"%s\"!\n", Entry.m_pName);
    }
    MyDir.close();
}

Note

All filenames are encoded using UTF8! Do not assume native encoding

See also

FileManager or DirectoryEntry_t

Constructor & Destructor Documentation

DirectorySearch() [1/3]

Burger::DirectorySearch::DirectorySearch ( const DirectorySearch & )

privatedelete

DirectorySearch() [2/3]

Burger::DirectorySearch::DirectorySearch ( DirectorySearch && )

privatedelete

DirectorySearch() [3/3]

Burger::DirectorySearch::DirectorySearch ( )

noexcept

Initialize a DirectorySearch class.

---

Simple initialization function.

See also

open(const char *)

~DirectorySearch()

Burger::DirectorySearch::~DirectorySearch

(

)

Closes any open directory.

---

See also

close(void)

Member Function Documentation

close()

void Burger::DirectorySearch::close ( void )

noexcept

Release all memory and close the directory.

---

Release all resources allocated by the open(Filename*) call.

See also

open(Filename*)

direntry_copy()

Burger::eError Burger::DirectorySearch::direntry_copy ( DirectoryEntry_t * pOutput, const DirectoryEntry_t * pInput )

protectednoexcept

Internal function for copying DirectoryEntry_t.

---

On some platforms, reading a directory only returns a filename list. For performance, only DirectoryEntry_t records are fully parsed on records when they are being used and records skipped will be ignored.

All other platforms, the entry is simply copied.

Returns

Zero on success, non-zero on an error.

See also

get_next_entry(DirectoryEntry_t*)

get_next_entry() [1/3]

Burger::eError Burger::DirectorySearch::get_next_entry ( DirectoryEntry_t * pEntry )

noexcept

Iterate on a directory and return the next found filename.

---

Reads the current directory opened previously by a call to open( const char *) and stores the information into the supplied DirectoryEntry_t buffer.

Returns

Zero on success, non-zero on an error or if the directory wasn't opened or if the end of the directory was reached

See also

close(void) or get_next_entry(DirectoryEntry_t*, const char *)

get_next_entry() [2/3]

Burger::eError Burger::DirectorySearch::get_next_entry ( DirectoryEntry_t * pEntry, const char * pExt )

noexcept

Iterate on a directory and return the next found filename that matches a specific file extension.

---

Reads the current directory opened previously by a call to open(const char *) and initializes all of the internal public variables with information of the file that was found.

This differs from get_next_entry(void) in that only files that end with a specific file extension are returned. This is a case insensitive search.

DirectoryEntry_t Entry;
while (!MyDir.get_next_entry(&Entry, "txt")) {
    printf("Found text file \"%s\"!\n", Entry.m_pName);
}

Note

Only filenames are returned. All directory filenames are skipped, even if their names match the extension.

Parameters

pEntry	Pointer to an uninitialized DirectoryEntry_t
pExt	Pointer to a "C" string of the file extension being scanned for.

Returns

Zero on success, non-zero on an error or if the directory wasn't opened or if the end of the directory was reached

See also

close(void), get_next_entry(DirectoryEntry_t*)

get_next_entry() [3/3]

const char * Burger::DirectorySearch::get_next_entry ( void )

noexcept

Iterate on a directory and return the next found filename.

---

If there is a directory entry in the queue, return the UTF8 encoded filename in the list.

Note

If more information than the filename is needed, use get_next_entry(DirectoryEntry_t*) instead.

Returns

Zero on success, non-zero on an error or if the directory wasn't opened or if the end of the directory was reached

See also

get_next_entry(DirectoryEntry_t*) or get_next_entry(DirectoryEntry_t*, const char*)

open() [1/2]

Burger::eError Burger::DirectorySearch::open ( const char * pDirName )

noexcept

Open a directory for scanning.

---

Parameters

pDirName

Pointer to the "C" string filename in BurgerLib format.

Returns

Zero on success, non-zero on an error or if the directory doesn't exist

See also

close(void) or get_next_entry(void)

open() [2/2]

Burger::eError Burger::DirectorySearch::open ( Burger::Filename * pDirName )

noexcept

Open a directory for scanning.

---

Parameters

pDirName

Pointer to the Filename object

Returns

Zero on success, non-zero on an error or if the directory doesn't exist

See also

close(void) or get_next_entry(void)

operator=() [1/2]

DirectorySearch & Burger::DirectorySearch::operator= ( const DirectorySearch & )

privatedelete

operator=() [2/2]

DirectorySearch & Burger::DirectorySearch::operator= ( DirectorySearch && )

privatedelete

Member Data Documentation

kDefaultReserve

const uintptr_t Burger::DirectorySearch::kDefaultReserve = 32U

static

Initial array size for DirectoryEntry_t records in m_Entries.

m_Entries

SimpleArray<DirectoryEntry_t> Burger::DirectorySearch::m_Entries

protected

Directory cache of stored entries.

m_NativePath

String Burger::DirectorySearch::m_NativePath

private

Linux/Android only, folder path for calling stat()

m_uIndex

uintptr_t Burger::DirectorySearch::m_uIndex

protected

Index to the m_Entries array for get_next_entry()