File name container. More...

Collaboration diagram for Burger::Filename:

[legend]

Classes
struct	ExpandCache_t
	Structure to contain a directory cache entry. More...

Public Member Functions
	Filename () noexcept
	Default constructor.

	Filename (const char *pFilename) noexcept
	Initialize the pathname to the input string.

	Filename (Filename const &rInput) noexcept
	Initialize the pathname from another pathname.

Filename &	operator= (Filename const &rInput) noexcept
	Copy a Burger::Filename.

	Filename (Filename &&rInput) noexcept
	Move a Burger::Filename.

Filename &	operator= (Filename &&rInput) noexcept
	Move a Burger::Filename.

	~Filename ()
	Release any memory allocated.

const char *	c_str (void) const noexcept
	Retrieve a pointer to the Burgerlib filename.

char *	c_str (void) noexcept
	Retrieve a pointer to the filename.

eError	assign (const char *pInput) noexcept
	Sets the pathname to the input string.

eError	assign (const uint16_t *pInput) noexcept
	Sets the pathname to a UTF-16 input string.

void	clear (void) noexcept
	Set the filename to an empty string.

eError	join (const char *pInput) noexcept
	Append a filename to the end of a path.

eError	join (const char *pInput, uintptr_t uInputLength) noexcept
	Append a filename to the end of a path.

eError	get_basename (char *pOutput, uintptr_t uOutputLength) const noexcept
	Obtain the filename in a path.

eError	get_basename (String *pOutput) const noexcept
	Extract the base name from a pathname.

eError	get_file_extension (char *pOutput, uintptr_t uOutputLength) const noexcept
	Obtain the filename extension.

eError	set_file_extension (const char *pExtension) noexcept
	Set the filename extension.

eError	dirname (void) noexcept
	Extract the directory from a pathname.

eError	get_dirname (char *pOutput, uintptr_t uOutputLength) const noexcept
	Extract the directory from a pathname.

eError	get_dirname (String *pOutput) const noexcept
	Extract the directory from a pathname.

uint_t	is_drive_number (void) const noexcept
	Determine if a filename starts with a "drive number".

uint_t	is_abs (void) const noexcept
	Determine if a filename is a fully qualified pathname.

uint_t	is_filename_only (void) const noexcept
	Determine if a filename has no prefix and is not fully qualified.

uint_t	has_prefix_number (void) const noexcept
	Determine if a filename has a prefix.

eError	abs_path (const char *pInput) noexcept
	Expand a filename by using prefix mapping.

eError	abs_path (void) noexcept
	Expand a filename by using prefix mapping.

const char *	get_native (void) noexcept
	Expand a filename from the BurgerLib format to the native OS format..

eError	set_native (const char *pInput) noexcept
	Expand a filename from the native format to Burgerlib.

eError	set_native (const uint16_t *pInput) noexcept
	Convert a native filename to Burgerlib format using UTF16 encoding.

eError	set_system_working_directory (void) noexcept
	Set the filename to the current working directory.

eError	set_application_directory (void) noexcept
	Set the filename to the application's directory.

eError	set_boot_volume (void) noexcept
	Set the filename to the boot volume directory.

eError	set_system_prefs_directory (void) noexcept
	Set the filename to the local machine preferences directory.

eError	set_user_prefs_directory (void) noexcept
	Set the filename to the user's preferences directory.

eError	set_native (const char *pInput, long lDirID=0, short sVRefNum=0) noexcept
	Convert a MacOS path to a Burgerlib path.

eError	get_FSSpec (FSSpec *pFSSpec) noexcept
	Create an FSSpec from the filename.

FSRef *	get_FSRef (void) noexcept
	Create an FSRef from the filename.

long	get_DirID (void) const noexcept
	Return the Directory ID stored in the class.

short	get_VRefNum (void) const noexcept
	Return the Volume Reference number stored in the class.

void	set_DirID (long lDirID) noexcept
	Set the Directory ID in the class.

void	set_VRefNum (short sVRefNum) noexcept
	Set Volume Reference number in the class.

eError	set_native (long lDirID, short sVolRefNum) noexcept
	Convert a Mac DirID and a Volume reference into a Burgerlib path.

eError	set_native_internal (void) noexcept
	Convert Directory to Burgerlib with FSSpec.

eError	get_native_internal (const char *pInput, long lDirID, short sVolRefNum) noexcept
	Create an FSSpec from a Burgerlib path.

eError	set_native_Carbon (void) noexcept
	Convert Directory to Burgerlib with FSRef.

eError	get_native_Carbon (const char *pInput, long lDirID, short sVolRefNum) noexcept
	Create an FSRef from a Burgerlib path.

Static Public Member Functions
static void	init_directory_cache (void)
	Initialize the directory cache.

static void	purge_directory_cache (void)
	Dispose of my directory cache.

static Filename *	New (void) noexcept
	Allocate a new Filename.

static Filename *	New (const char *pFilename) noexcept
	Allocate a new Filename with a Burgerlib "C" string.

static Filename *	New (Filename const &rInput) noexcept
	Allocate a copy of a Filename.

Protected Member Functions
eError	end_with_colon (void) noexcept
	Ensure the filename ends with a colon.

Private Attributes
String	m_Filename
	Pointer to the burgerlib filename.

String	m_NativeFilename
	Pointer to the native filename.

uint_t	m_bNativeValid
	TRUE if the native path is valid.

uint8_t	m_FSRef [80]
	Opaque FSRef used by (MacOS 9 only)

long	m_lDirID
	Directory reference (MacOS 9 Only)

short	m_sVRefNum
	Volume reference used by copy and rename (MacOS 9 Only)

Static Private Attributes
static const uint_t	kDirectoryCacheSize = 8
	Number of cache entries (MacOS 9 only)

static ExpandCache_t	m_DirectoryCache [kDirectoryCacheSize]
	Directory cache (MAC Classic/Carbon Only)

Detailed Description

File name container.

This container class is a high speed conversion method to convert a BurgerLib formatted filename into a filename suitable for use with the native file system.

Some operating systems require more information than just the filename. Due to this, it's highly recommended that a Burgerlib path is generated, then a call to get_native() is invoked to do the proper conversion and generate the extra data. Currently, only the MacOS Carbon and Classic targets require this extra data, however for future compatibility or performance upgrades, don't assume that creating a filename by hand will be a cross platform solution.

When writing code intended for a single platform, it's encouraged to load and store the extra data. Also, you can use the set_native() call to convert a native filename into BurgerLib format without having to do anything special.

See also: struct Burger::FileManager or class Burger::DirectorySearch

Constructor & Destructor Documentation

◆ Filename() [1/4]

Burger::Filename::Filename ( )

inlinenoexcept

Default constructor.

Simple inline initializer, Designed for high speed and does not call any other function

See also: Burger::Filename::assign(const char *) or Burger::Filename::~Filename()

◆ Filename() [2/4]

Burger::Filename::Filename ( const char * pFilename )

noexcept

Initialize the pathname to the input string.

Given a string passed by pInput, set the contained string to match. In a majority of cases, no memory is allocated. If in the rare case the string is of a large length, it will allocate a buffer and store the string within the allocated memory and ignore the internal buffer..

Note: This function does not alter the string in any way. It is stored in the internal buffer as is. It also will not modify any platform specific variables.

Parameters

pFilename Pointer to a valid "C" string or nullptr to force the class to empty.

See also: clear() and assign(const char *)

◆ Filename() [3/4]

Burger::Filename::Filename ( Filename const & rInput )

noexcept

Initialize the pathname from another pathname.

Given a Burger::Filename passed by reference, set the contained string to match. In a majority of cases, no memory is allocated. If in the rare case the string is of a large length, it will allocate a buffer and store the string within the allocated memory and ignore the internal buffer..

Note: This function does not alter the string in any way. It is stored in the internal buffer as is. It also will not modify any platform specific variables.

Parameters

rInput Reference to another Filename to copy from

See also: clear() and assign(const char *)

◆ Filename() [4/4]

Burger::Filename::Filename ( Filename && rInput )

noexcept

Move a Burger::Filename.

Parameters

rInput Reference to a Filename to move from

See also: assign(const char *)

◆ ~Filename()

Burger::Filename::~Filename ( )

Release any memory allocated.

If in the course of setting a pathname to an excessive length, release any extra allocated memory. In most cases, this does nothing.

Note: Can call Burger::Free() in some cases

Member Function Documentation

◆ abs_path() [1/2]

Burger::eError BURGER_API Burger::Filename::abs_path ( const char * pInput )

noexcept

Expand a filename by using prefix mapping.

Using the rules for a Burgerlib type pathname, expand a path into a FULL pathname native to the Burgerlib file system.

Directory delimiters are colons only.

If the path starts with a colon, then it is a full pathname starting with a volume name. If the path starts with ".D2:" then it is a full pathname starting with a drive number. If the path starts with a "$:","*:" or "@:" then use special prefix numbers 32-34 If the path starts with 0: through 31: then use prefix 0-31. Otherwise prefix the pathname with the contents of prefix 8 ("Default")

If the path after the prefix is removed is a period then POP the number of directories from the pathname for each period present after the first. Example "..:PrevDir:File:" will go down one directory and up the directory PrevDir

All returned pathnames will have a trailing colon

Parameters

pInput Pointer to a pathname string

◆ abs_path() [2/2]

Burger::eError BURGER_API Burger::Filename::abs_path ( void )

noexcept

Expand a filename by using prefix mapping.

Using the rules for a Burgerlib type pathname, expand a path into a FULL pathname native to the Burgerlib file system.

Directory delimiters are colons only.

If the path starts with a colon, then it is a full pathname starting with a volume name. If the path starts with ".D2:" then it is a full pathname starting with a drive number. If the path starts with a "$:","*:" or "@:" then use special prefix numbers 32-34 If the path starts with 0: through 31: then use prefix 0-31. Otherwise prefix the pathname with the contents of prefix 8 ("Default")

If the path after the prefix is removed is a period then POP the number of directories from the pathname for each period present after the first. Example "..:PrevDir:File:" will go down one directory and up the directory PrevDir

All returned pathnames will have a trailing colon

◆ assign() [1/2]

Burger::eError BURGER_API Burger::Filename::assign ( const char * pInput )

noexcept

Sets the pathname to the input string.

Given a string passed by pInput, set the contained string to match. In a majority of cases, no memory is allocated. If in the rare case the string is of a large length, it will allocate a buffer and store the string within the allocated memory and ignore the internal buffer..

Note: This function does not alter the string in any way. It is stored in the internal buffer as is. It also will not modify any platform specific variables.

Parameters

pInput Pointer to a valid "C" string or NULL to force the class to empty.

See also: Burger::Filename::Clear()

◆ assign() [2/2]

Burger::eError BURGER_API Burger::Filename::assign ( const uint16_t * pInput )

noexcept

Sets the pathname to a UTF-16 input string.

Given a UTF-16 string passed by pInput, set the contained string to match. In a majority of cases, no memory is allocated. If in the rare case the string is of a large length, it will allocate a buffer and store the string within the allocated memory and ignore the internal buffer.

Note: This function does not alter the string in any way. It is stored in the internal buffer as is. It also will not modify any platform specific variables.

Parameters

pInput Pointer to a valid "C" string or NULL to force the class to empty.

See also: Clear() or Set(const char *)

◆ c_str() [1/2]

const char * Burger::Filename::c_str ( void ) const

inlinenoexcept

Retrieve a pointer to the Burgerlib filename.

Return a pointer to a valid const "C" string,

String may be an empty string if it wasn't set via a previous call. This function will never return a NULL pointer.

Returns: A pointer to an unmodifiable "C" string. Make no attempt to write to it.

See also: Filename::Set(const char *) or Filename::GetPtr(void)

◆ c_str() [2/2]

char * Burger::Filename::c_str ( void )

inlinenoexcept

Retrieve a pointer to the filename.

Return a pointer to a valid "C" string,

String may be an empty string if it wasn't set via a previous call. This function will never return a NULL pointer.

Returns: A pointer to an modifiable "C" string. Make no attempt to write into the string since it may interfere with the operation of the class.

See also: Set(const char *) or Filename::GetPtr(void) const

◆ clear()

void BURGER_API Burger::Filename::clear ( void )

noexcept

Set the filename to an empty string.

If in the course of setting a pathname to an excessive length, release any extra allocated memory. In most cases, this simply resets the cached buffer to an empty string.

◆ dirname()

Burger::eError BURGER_API Burger::Filename::dirname ( void )

noexcept

Extract the directory from a pathname.

Given a pathname, remove the filename from the end of the path, leaving only the directory name remaining.

Note: If there is only the label name remaining, return the label name.

◆ end_with_colon()

Burger::eError BURGER_API Burger::Filename::end_with_colon ( void )

protectednoexcept

Ensure the filename ends with a colon.

If the filename is not empty, check if the last character is a colon. If it is not, one will be appended.

Returns: Zero if no error, non-zero if out of memory.

See also: join(const char *)

◆ get_basename() [1/2]

Burger::eError BURGER_API Burger::Filename::get_basename	(	char *	pOutput,
		uintptr_t	uOutputLength ) const

noexcept

Obtain the filename in a path.

Given a pathname, return the filename at the end of the path. The output is guaranteed to have a terminating zero unless uOutputLength is zero.

Note: If the filename is too big to fit in the output buffer, it will be truncated.

Parameters

pOutput	Buffer to receive the filename at the end of the path
uOutputLength	Size of the buffer to obtain the filename.

◆ get_basename() [2/2]

Burger::eError BURGER_API Burger::Filename::get_basename ( String * pOutput ) const

noexcept

Extract the base name from a pathname.

Given a pathname, remove the directory from the beginning of the path, leaving only the file name remaining. The resulting filename will not have leading or trailing colons

Parameters

pOutput Pointer to a valid Burger::String instance to receive the new string

◆ get_DirID()

long Burger::Filename::get_DirID ( void ) const

inlinenoexcept

Return the Directory ID stored in the class.

Returns: The Directory ID for this filename

See also: Burger::Filename::set_DirID(long) or Burger::Filename::get_VRefNum(void) const

Note: Only available on MacOS and only valid after a call to Burger::Filename::get_native()

◆ get_dirname() [1/2]

Burger::eError BURGER_API Burger::Filename::get_dirname	(	char *	pOutput,
		uintptr_t	uOutputLength ) const

noexcept

Extract the directory from a pathname.

Given a pathname, remove the filename from the end of the path, leaving only the directory name remaining.

Parameters

pOutput	Buffer to receive the filename at the end of the path
uOutputLength	Size of the buffer to obtain the filename.

◆ get_dirname() [2/2]

Burger::eError BURGER_API Burger::Filename::get_dirname ( String * pOutput ) const

noexcept

Extract the directory from a pathname.

Given a pathname, remove the filename from the end of the path, leaving only the directory name remaining.

Parameters

pOutput Pointer to a valid Burger::String instance to receive the new string

◆ get_file_extension()

Burger::eError BURGER_API Burger::Filename::get_file_extension	(	char *	pOutput,
		uintptr_t	uOutputLength ) const

noexcept

Obtain the filename extension.

Given a pathname, return the file extension for the filename at the end of the path

Note: If the filename extension is too big to fit in the output buffer, it will be truncated.

Parameters

pOutput	Buffer to receive the filename at the end of the path
uOutputLength	Size of the buffer to obtain the filename.

◆ get_FSRef()

FSRef *BURGER_API BURGER_API Burger::Filename::get_FSRef ( void )

noexcept

Create an FSRef from the filename.

Convert the Filename into an FSRef record and return a pointer to it. If the computer cannot create an FSRef, then it's likely that the application is running on MacOS previous to 9.0.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Returns: Pointer to an FSRef or nullptr if not supported.

See also: get_FSSpec(FSSpec*)

◆ get_FSSpec()

Burger::eError BURGER_API Burger::Filename::get_FSSpec ( FSSpec * pFSSpec )

noexcept

Create an FSSpec from the filename.

Given a FSSpec record, fill it in for all the data needed from this filename so that MacOS can use the FSSpec to manipulate files.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Parameters

pFSSpec Pointer to an empty FSSpec

Returns: Zero if no error.

See also: get_FSRef()

◆ get_native()

const char * Burger::Filename::get_native ( void )

noexcept

Expand a filename from the BurgerLib format to the native OS format..

For generic code, convert a BurgerLib path into one suitable for the current operating system. This function is mostly used when custom code for a specific platform is being written and the native path is required.

Note: If this function is invoked on a MacOS target, a Volume Reference number and Directory ID are generated and can be accessed via calls to Burger::Filename::get_DirID(void) const and Burger::Filename::get_VRefNum(void) const

◆ get_native_Carbon()

Burger::eError BURGER_API Burger::Filename::get_native_Carbon	(	const char *	pInput,
		long	lDirID,
		short	sVolRefNum )

noexcept

Create an FSRef from a Burgerlib path.

Given a volume and root directory, traverse a Burgerlib style pathname and create the values needed to create an FSSpec that best represents the pathname.

If the FSRef can be parsed all the way down to the final entry, m_NativeFilename will be set to an empty string. If not, it means the file or directory at the end of the chain does not exist and will need to be created or otherwise handled due to it not being present on the file system.

The Directory ID and volume reference number will be properly set if the pathname is legitimate. If the pathname is to an existing directory, the directory ID will be of the directory itself. If the path is to a file, the directory id is for the directory that contains the file.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Parameters

pInput	Pointer to the "C" of the pathname WITHOUT the root volume or drive id. Only the directories to traverse.
lDirID	32-bit directory ID supplied by MacOS
sVolRefNum	16-bit volume reference number

Returns: Zero if no error, non zero if there was an error

◆ get_native_internal()

Burger::eError BURGER_API Burger::Filename::get_native_internal	(	const char *	pInput,
		long	lDirID,
		short	sVolRefNum )

noexcept

Create an FSSpec from a Burgerlib path.

Given a volume and root directory, traverse a Burgerlib style pathname and create the values needed to create an FSSpec that best represents the pathname.

If the FSSpec can be parsed all the way down to the final entry, m_NativeFilename will be set to an empty string. If not, it means the file or directory at the end of the chain does not exist and will need to be created or otherwise handled due to it not being present on the file system.

m_NativeFilename always contains the name of the file, since FSSpec records only need to parse parent ID and volume ID information.

The Directory ID and volume reference number will be properly set if the pathname is legitimate. If the pathname is to an existing directory, the directory ID will be of the directory itself. If the path is to a file, the directory id is for the directory that contains the file.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Parameters

pInput	Pointer to the "C" of the pathname WITHOUT the root volume or drive id. Only the directories to traverse.
lDirID	32-bit directory ID supplied by MacOS
sVolRefNum	16-bit volume reference number

Returns: Zero if no error, non zero if there was an error

◆ get_VRefNum()

short Burger::Filename::get_VRefNum ( void ) const

inlinenoexcept

Return the Volume Reference number stored in the class.

Returns: The Volume Reference number for this filename.

See also: set_VRefNum(short) or get_DirID(void) const

Note: Only available on MacOS and only valid after a call to get_native()

◆ has_prefix_number()

uint_t BURGER_API Burger::Filename::has_prefix_number ( void ) const

noexcept

Determine if a filename has a prefix.

Is the pathname starts with "8:" or "*:" or any other valid prefix values, then it's considered prefixed and it will have that directory prefixed when converting it to a fully qualified pathname.

Returns: FileManager::kPrefixInvalid if there is no prefix or the prefix number if it does.

See also: is_filename_only()

◆ init_directory_cache()

void BURGER_API Burger::Filename::init_directory_cache ( void )

static

Initialize the directory cache.

This function is called by FileManager::initialize(void). It's not meant to be called by applications.

Note: Only available on MacOS

See also: purge_directory_cache(void) or ExpandCache_t

◆ is_abs()

uint_t BURGER_API Burger::Filename::is_abs ( void ) const

noexcept

Determine if a filename is a fully qualified pathname.

Burgerlib pathnames can be prefixed, partially or fully qualified. A fully qualified pathname means that the entire pathname exists and a prefix will not be prefixed and there would be no need to "Expand" the pathname before converting it to a native format.

There are two ways a pathname is fully qualified, firstly if the pathname starts with a ":", it's assumed that the first name is the name of the volume. If it's ".D2:", then the number between the "D" and the ":" is the volume number (Or mapped to a drive letter in the case of Windows or MSDOS)

Returns: TRUE if the pathname is fully qualified, FALSE if not.

See also: is_filename_only()

◆ is_drive_number()

uint_t BURGER_API Burger::Filename::is_drive_number ( void ) const

noexcept

Determine if a filename starts with a "drive number".

A Burgerlib pathname can use drive letters. They are in the form of ".D2:" as a volume name where the period and D denote the path is a device and the number is the device number in the chain. While technically there is no limit to devices, it's considered an error to have a device number higher than 99.

This function will check if the Burgerlib pathname is a device and return the device number if so. If not, UINT32_MAX will be returned as an error.

Returns: Volume number if the path starts with a device number, UINT32_MAX if not.

See also: is_abs()

◆ is_filename_only()

uint_t BURGER_API Burger::Filename::is_filename_only ( void ) const

noexcept

Determine if a filename has no prefix and is not fully qualified.

There are two ways a pathname not qualified, firstly if the pathname is a full pathname, it's qualified. If the pathname has a prefix start, it's qualified.

Filenames of this nature will be automatically assumed to be offset from directory Burger::FileManager::kPrefixCurrent (the current working directory)

Returns: TRUE if the pathname is not qualified, FALSE if not.

See also: is_abs() const

◆ join() [1/2]

Burger::eError BURGER_API Burger::Filename::join ( const char * pInput )

noexcept

Append a filename to the end of a path.

Given a filename, append the filename to the end of the path and add a trailing colon. A colon will be inserted between the existing path and the filename being appended.

Parameters

pInput Pointer to "C" string of the filename to append to the path.

Returns: Zero if no error, non-zero if out of memory.

◆ join() [2/2]

Burger::eError BURGER_API Burger::Filename::join	(	const char *	pInput,
		uintptr_t	uInputLength )

noexcept

Append a filename to the end of a path.

Given a filename, append the filename to the end of the path and add a trailing colon. A colon will be inserted between the existing path and the filename being appended.

Parameters

pInput	Pointer to buffer with the filename to append to the path.
uInputLength	Length of the buffer to append

Returns: Zero if no error, non-zero if out of memory.

◆ New() [1/3]

Burger::Filename *BURGER_API Burger::Filename::New ( const char * pFilename )

staticnoexcept

Allocate a new Filename with a Burgerlib "C" string.

Allocate memory using the Burgerlib memory manager and initialize it to a default Filename class instance.

Delete with a call to Delete()

Parameters

pFilename Pointer to a "C" string formatted as a Burgerlib pathname

See also: Delete(const T *)

◆ New() [2/3]

Burger::Filename *BURGER_API Burger::Filename::New ( Filename const & rInput )

staticnoexcept

Allocate a copy of a Filename.

Allocate memory using the Burgerlib memory manager and initialize it as a copy of another Filename class instance.

Delete with a call to Delete()

Parameters

rInput Reference to a Filename to copy from

See also: Delete(const T *)

◆ New() [3/3]

Burger::Filename *BURGER_API Burger::Filename::New ( void )

staticnoexcept

Allocate a new Filename.

Allocate memory using the Burgerlib memory manager and initialize it to a default Filename class instance.

Delete with a call to Delete()

See also: Delete(const T *)

◆ operator=() [1/2]

Burger::Filename & Burger::Filename::operator= ( Filename && rInput )

noexcept

Move a Burger::Filename.

Parameters

rInput Reference to a Filename to move from

See also: assign(const char *)

◆ operator=() [2/2]

Burger::Filename & Burger::Filename::operator= ( Filename const & rInput )

noexcept

Copy a Burger::Filename.

Parameters

rInput Reference to a Filename to copy from

See also: assign()

◆ purge_directory_cache()

void BURGER_API Burger::Filename::purge_directory_cache ( void )

static

Dispose of my directory cache.

This function is called by FileManager::shut_down(void) or any internal function that can modify the MacOS directory structure. It's not meant to be called by applications.

Note: Only available on MacOS

See also: init_directory_cache(void) or ExpandCache_t

◆ set_application_directory()

Burger::eError BURGER_API Burger::Filename::set_application_directory ( void )

noexcept

Set the filename to the application's directory.

Determine the directory where the application resides and set the filename to that directory. The path is converted into UTF8 character encoding and stored in Burgerlib filename format.

On platforms where a current working directory doesn't make sense, like a ROM based system, the filename is cleared out.

◆ set_boot_volume()

Burger::eError BURGER_API Burger::Filename::set_boot_volume ( void )

noexcept

Set the filename to the boot volume directory.

Determine the directory of the drive volume that the operating system was loaded from. The path is converted into UTF8 character encoding and stored in Burgerlib filename format.

On platforms where a current working directory doesn't make sense, like a ROM based system, the filename is cleared out.

◆ set_DirID()

void Burger::Filename::set_DirID ( long lDirID )

inlinenoexcept

Set the Directory ID in the class.

See also: Burger::Filename::get_DirID(void) const or Burger::Filename::set_VRefNum(short)

Note: Only available on MacOS

◆ set_file_extension()

Burger::eError BURGER_API Burger::Filename::set_file_extension ( const char * pExtension )

noexcept

Set the filename extension.

Given a filename extension, set the filename to this extension

Parameters

pExtension Pointer to a "C" string that contains the new filename extension

See also: Burger::Filename::GetFileExtension(char *,uintptr_t) const

◆ set_native() [1/4]

Burger::eError BURGER_API Burger::Filename::set_native ( const char * pInput )

noexcept

Expand a filename from the native format to Burgerlib.

For generic code, obtain a filename (Usually from a command line) and convert it to a BurgerLib path. This function is an inline redirection to the proper low level function that will perform the actual conversion.

Parameters

pInput Pointer to a pathname string

Note: Due to MacOS requiring extra information such as a directory ID and volume number, ensure that the current volume and working directory are pointing to the directory the file is located. The MacOS call HSetVol() and HGetVol() can assist in those cases. It's preferred to use the Burger::ConsoleApp class's built in file name management functions since they take this quirk into account.

See also: set_native(const uint16_t *)

◆ set_native() [2/4]

Burger::eError BURGER_API Burger::Filename::set_native	(	const char *	pInput,
		long	lDirID = 0,
		short	sVRefNum = 0 )

noexcept

Convert a MacOS path to a Burgerlib path.

Given a "C" string to the pathname, a Directory ID and a Volume Reference number, create a full pathname in Burgerlib format.

This function is commonly used when creating a file selection dialog and the input needs to converted into a format that is compatible with most Burgerlib file functions.

Parameters

pInput	Pointer to a "C" string of a MacOS formatted filename
lDirID	Directory ID for the filename
sVRefNum	Volume ID for the filename

Note: Only available on MacOS

◆ set_native() [3/4]

Burger::eError BURGER_API Burger::Filename::set_native ( const uint16_t * pInput )

noexcept

Convert a native filename to Burgerlib format using UTF16 encoding.

Copy the native pathname string into the internal native pathname buffer after converting the string to UTF-8. It's mostly used on Windows platforms since it's native character encoding is UTF16.

Note: This function does not exist on MacOS classic since MacOS classic only uses MacRomanUS 8 bit character encodings and a volume number and directory ID, so UTF16 support is not needed.

Parameters

pInput Pointer to a pathname string

See also: set_native(const char *) or set_native(const char *,long,short)

◆ set_native() [4/4]

Burger::eError BURGER_API Burger::Filename::set_native	(	long	lDirID,
		short	sVolRefNum )

noexcept

Convert a Mac DirID and a Volume reference into a Burgerlib path.

Given a 32 bit directory ID and a 16 bit volume number, determine the full Burgerlib pathname that is its equivalent.

What is returned is either nullptr for an error condition, pOutput if the user supplied buffer was large enough to contain the requested data or a newly allocated pointer to a larger buffer to hold the requested data.

Note: If the returned pointer is not the pointer passed in via pOutput, dispose of it with a called to Burger::Free(const void *) when done.; This is only available on Mac OS 7.5-9.9.2 or Carbon

Parameters

lDirID	32-bit directory ID supplied by MacOS
sVolRefNum	16-bit volume reference number supplied by MacOS

Returns: Zero if no error, non zero if there was an error

◆ set_native_Carbon()

Burger::eError BURGER_API Burger::Filename::set_native_Carbon ( void )

noexcept

Convert Directory to Burgerlib with FSRef.

Internal routine that converts a directory ID and a volume number into a Burgerlib path.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Returns: Zero if no error, non zero if there was an error

◆ set_native_internal()

Burger::eError BURGER_API Burger::Filename::set_native_internal ( void )

noexcept

Convert Directory to Burgerlib with FSSpec.

Internal routine that converts a directory ID and a volume number into a Burgerlib path.

Note: This is only available on Mac OS 7.5-9.9.2 or Carbon

Returns: Zero if no error, non zero if there was an error

◆ set_system_prefs_directory()

Burger::eError BURGER_API Burger::Filename::set_system_prefs_directory ( void )

noexcept

Set the filename to the local machine preferences directory.

Determine the directory where the user's preferences that are local to the machine is located. The path is converted into UTF8 character encoding and stored in Burgerlib filename format.

On platforms where a current working directory doesn't make sense, like a ROM based system, the filename is cleared out.

◆ set_system_working_directory()

Burger::eError BURGER_API Burger::Filename::set_system_working_directory ( void )

noexcept

Set the filename to the current working directory.

Query the operating system for the current working directory and set the filename to that directory. The path is converted into UTF8 character encoding and stored in Burgerlib filename format

On platforms where a current working directory doesn't make sense, like a ROM based system, the filename is cleared out.

Returns: kErrorNone if successful, kErrorPathNotFound if invalid, or kErrorNotSupportedOnThisPlatform if not implemented on the platform.

◆ set_user_prefs_directory()

Burger::eError BURGER_API Burger::Filename::set_user_prefs_directory ( void )

noexcept

Set the filename to the user's preferences directory.

Determine the directory where the user's preferences that could be shared among all machines the user has an account with is located. The path is converted into UTF8 character encoding and stored in Burgerlib filename format.

On platforms where a current working directory doesn't make sense, like a ROM based system, the filename is cleared out.

◆ set_VRefNum()

void Burger::Filename::set_VRefNum ( short sVRefNum )

inlinenoexcept

Set Volume Reference number in the class.

See also: Burger::Filename::get_VRefNum(void) const or Burger::Filename::set_DirID(long)

Note: Only available on MacOS

Member Data Documentation

◆ kDirectoryCacheSize

const uint_t Burger::Filename::kDirectoryCacheSize = 8

staticprivate

Number of cache entries (MacOS 9 only)

◆ m_bNativeValid

uint_t Burger::Filename::m_bNativeValid

private

TRUE if the native path is valid.

◆ m_DirectoryCache

Burger::Filename::ExpandCache_t Burger::Filename::m_DirectoryCache

staticprivate

Directory cache (MAC Classic/Carbon Only)

◆ m_Filename

String Burger::Filename::m_Filename

private

Pointer to the burgerlib filename.

◆ m_FSRef

uint8_t Burger::Filename::m_FSRef[80]

private

Opaque FSRef used by (MacOS 9 only)

◆ m_lDirID

long Burger::Filename::m_lDirID

private

Directory reference (MacOS 9 Only)

◆ m_NativeFilename

String Burger::Filename::m_NativeFilename

private

Pointer to the native filename.

◆ m_sVRefNum

short Burger::Filename::m_sVRefNum

private

Volume reference used by copy and rename (MacOS 9 Only)

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Filename() [1/4]

◆ Filename() [2/4]

◆ Filename() [3/4]

◆ Filename() [4/4]

◆ ~Filename()

Member Function Documentation

◆ abs_path() [1/2]

◆ abs_path() [2/2]

◆ assign() [1/2]

◆ assign() [2/2]

◆ c_str() [1/2]

◆ c_str() [2/2]

◆ clear()

◆ dirname()

◆ end_with_colon()

◆ get_basename() [1/2]

◆ get_basename() [2/2]

◆ get_DirID()

◆ get_dirname() [1/2]

◆ get_dirname() [2/2]

◆ get_file_extension()

◆ get_FSRef()

◆ get_FSSpec()

◆ get_native()

◆ get_native_Carbon()

◆ get_native_internal()

◆ get_VRefNum()

◆ has_prefix_number()

◆ init_directory_cache()

◆ is_abs()

◆ is_drive_number()

◆ is_filename_only()

◆ join() [1/2]

◆ join() [2/2]

◆ New() [1/3]

◆ New() [2/3]

◆ New() [3/3]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ purge_directory_cache()

◆ set_application_directory()

◆ set_boot_volume()

◆ set_DirID()

◆ set_file_extension()

◆ set_native() [1/4]

◆ set_native() [2/4]

◆ set_native() [3/4]

◆ set_native() [4/4]

◆ set_native_Carbon()

◆ set_native_internal()

◆ set_system_prefs_directory()

◆ set_system_working_directory()

◆ set_user_prefs_directory()

◆ set_VRefNum()

Member Data Documentation

◆ kDirectoryCacheSize

◆ m_bNativeValid

◆ m_DirectoryCache

◆ m_Filename

◆ m_FSRef

◆ m_lDirID

◆ m_NativeFilename

◆ m_sVRefNum