File name container. More...

#include <fmfile.h>

Public Member Functions
	Filename ()
	Default constructor.
	~Filename ()
	Release any memory allocated.
BURGER_INLINE const char *	GetPtr (void) const
	Retrieve a pointer to the filename.
BURGER_INLINE char *	GetPtr (void)
	Retrieve a pointer to the filename.
void	Set (const char *pInput)
	Sets the pathname to the input string.
void	Clear (void)
	Set the filename to an empty string.
void	Expand (const char *pInput)
	Expand a filename by using prefix mapping.
void	ToWindows (const char *pInput)
	Expand a filename into Windows/MSDOS format.
void	FromWindows (const char *pInput)
	Convert a Windows path to a Burgerlib path.
void	FromMSDOS (const char *pInput)
	Convert an MSDOS path to a Burgerlib path.
void	ToMacOSX (const char *pInput)
	Expand a filename into MacOSX format.
void	FromMacOSX (const char *pInput)
	Convert a MacOSX filename into BurgerLib format.
void	ToMac (const char *pInput)
	Convert a Burgerlib path to a MacOS path.
void	FromMac (const char *pInput, long lDirID, short sVRefNum)
	Convert a MacOS path to a Burgerlib path.
BURGER_INLINE long	GetDirID (void) const
	Return the Directory ID stored in the class.
BURGER_INLINE short	GetVRefNum (void) const
	Return the Volume Reference number stored in the class.
BURGER_INLINE void	SetDirID (long lDirID)
	Set the Directory ID in the class.
BURGER_INLINE void	SetVRefNum (short sVRefNum)
	Set Volume Reference number in the class.
BURGER_INLINE void	FromNative (const char *pInput)
	Expand a filename from the native format to Burgerlib.
BURGER_INLINE void	ToNative (const char *pInput)
	Expand a filename from the BurgerLib format to the native OS format..
Static Public Attributes
static const Word	BUFFERSIZE = 512-(sizeof(char *)+sizeof(long)+sizeof(short))
	Size of the filename buffer (Adjusted to to keep the class size at exactly 512 bytes in length).
Private Attributes
char *	m_pFilename
	Pointer to the filename.
long	m_lDirID
	Directory reference (MacOS Only).
short	m_sVRefNum
	Volume reference used by copy and rename (MacOS Only).
char	m_Filename [BUFFERSIZE]
	Local buffer containing the filename (If it can fit in this buffer).

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 Burger::Filename::ToNative(const char *) 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 compatibilty 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 Burger::Filename::FromNative(const char *) call to convert a native filename into BurgerLib format without having to do anything special.

See also:: struct Burger::FileManager

Constructor & Destructor Documentation

Burger::Filename::Filename ( ) [inline]

Default constructor.

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

See also:: Burger::Filename::Set(const char *) or Burger::Filename::~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 the Burger::GlobalMemoryManager in some cases

Member Function Documentation

void Burger::Filename::Clear ( void )

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.

void Burger::Filename::Expand ( const char * pInput )

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 prepend 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

void Burger::Filename::FromMac	(	const char *	OldPath,
		long	lDirID,
		short	sVRefNum
	)

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:

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

See also:: Burger::Filename::FromMacOSX(const char *)

Note:: Only available on MacOS

void Burger::Filename::FromMacOSX ( const char * pInput )

Convert a MacOSX filename into BurgerLib format.

Using the rules for a Burgerlib type pathname, expand a path from a MacOSX filename into BurgerLib.

The pathname will have an ending colon.

Examples:
If home drive is named "boot" then "/foo/bar.txt" = ":boot:foo:bar.txt"
If the first name is "/Volumes" then "/Volumes/boot/foo/bar.txt" = ":boot:foo:bar.txt"

Parameters:

pInput

Pointer to a pathname string

See also:: Burger::Filename::Set(const char *)

Note:: Only available on MacOSX targets

void Burger::Filename::FromMSDOS ( const char * pInput )

Convert an MSDOS path to a Burgerlib path.

There is no volume name support in DOS

Paths without a leading '\' are prefixed with the current working directory

Paths with a drive letter but no leading \ will use the drive's current working directory

If it's a network path "\\" then dispose of the drive letter and use the pathname.

The DOS version converts these types of paths:

"C:\TEMP\TEMP2" = ".D2:TEMP:TEMP2:"
"TEMP" = "(working directory from 8):TEMP:"
"TEMP\TEMP2" = "(working directory from 8):TEMP:TEMP2:"
"\TEMP" = ".D(Mounted drive number):TEMP:"

See also:: Burger::Filename::FromWindows(const char *)

Note:: Only available on MSDOS

void Burger::Filename::FromNative ( const char * pInput ) [inline]

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

See also:: Burger::Filename::FromWindows(const char *), Burger::Filename::FromMSDOS(const char *), Burger::Filename::FromMacOSX(const char *), Burger::Filename::FromMac(const char *,long,short) or Burger::Filename::ToNative(const char *)

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 accound.

void Burger::Filename::FromWindows ( const char * pInput )

Convert a Windows path to a Burgerlib path.

Paths without a leading '\' are prefixed with the current working directory

Paths with a drive letter but no leading \ will use the drive's current working directory

If it's a network path "\\" then use that as the volume name.

The Windows version converts these types of paths:

"C:\foo\bar2" = ".D2:foo:bar2:"
"foo" = "(working directory from 8):foo:"
"foo\bar2" = "(working directory from 8):foo:bar2:"
"\foo" = ".D(Mounted drive number):foo:"
"\\foo\bar\file.txt" = ":foo:bar:file.txt:"

See also:: Burger::Filename::FromMSDOS(const char *)

Note:: Only available on Windows

Burger::Filename::GetDirID ( void ) const [inline]

Return the Directory ID stored in the class.

Returns:: The Directory ID for this filename

See also:: Burger::Filename::SetDirID(long) or Burger::Filename::GetVRefNum(void) const

Note:: Only available on MacOS and only valid after a call to Burger::Filename::ToMac(const char *)

Burger::Filename::GetPtr ( void ) const [inline]

Retrieve a pointer to the 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:: Burger::Filename::Set(const char *) or Burger::Filename::GetPtr(void)

Burger::Filename::GetPtr ( void ) [inline]

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 beyond the end of the string since the pointer may be to an allocated buffer in the event of a very long pathname.

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

Burger::Filename::GetVRefNum ( void ) const [inline]

Return the Volume Reference number stored in the class.

Returns:: The Volume Reference number for this filename.

See also:: Burger::Filename::SetVRefNum(short) or Burger::Filename::GetDirID(void) const

Note:: Only available on MacOS and only valid after a call to Burger::Filename::ToMac(const char *)

void Burger::Filename::Set ( const char * pInput )

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

Burger::Filename::SetDirID ( long lDirID ) [inline]

Set the Directory ID in the class.

See also:: Burger::Filename::GetDirID(void) const or Burger::Filename::SetVRefNum(short)

Note:: Only available on MacOS

Burger::Filename::SetVRefNum ( short sVRefNum ) [inline]

Set Volume Reference number in the class.

See also:: Burger::Filename::GetVRefNum(void) const or Burger::Filename::SetDirID(long)

Note:: Only available on MacOS

void Burger::Filename::ToMac ( const char * pInput )

Convert a Burgerlib path to a MacOS path.

MacOS filenames have a 256 character limit. To get around this, Burgerlib will traverse the path to find the Volume Reference number and Directory ID to the deepest entry in the path. This way, in most cases, only the filename itself is stored in the filename buffer.

This function initializes the Volume Reference number and Directory ID. Assume that they are valid at the conclusion of this call.

Parameters:

pInput

Pointer to a "C" string of a valid Burgerlib path.

See also:: Burger::Filename::FromMacOSX(const char *)

Note:: Only available on MacOS. HFS only supports filenames that are 31 characters or less for each component, so avoid using extremely long filename components.

void Burger::Filename::ToMacOSX ( const char * pInput )

Expand a filename into MacOSX format.

Using the rules for a Burgerlib type pathname, expand a path into a FULL pathname native to the MacOSX 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 volume name enumated by volumes. 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 prepend 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 NOT have a trailing "/", they will take the form of /foo/bar/file.txt or similar

Examples:
If home drive is named "boot" then ":boot:foo:bar.txt" = "/foo/bar.txt"
If the home drive is not named "boot" then ":boot:foo:bar.txt" = "/Volumes/boot/foo/bar.txt"
"@:game:data.dat" = "/Users/<Current user>/Library/Preferences/game/data.dat"

Parameters:

pInput

Pointer to a pathname string

See also:: Burger::Filename::Set(const char *)

Note:: Only available on MacOSX targets

void Burger::Filename::ToNative ( const char * pInput ) [inline]

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.

Parameters:

pInput

Pointer to a pathname string

See also:: Burger::Filename::ToWindows(const char *), Burger::Filename::ToMacOSX(const char *), Burger::Filename::ToMac(const char *,long,short) or Burger::Filename::FromNative(const char *)

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::GetDirID(void) const and Burger::Filename::GetVRefNum(void) const

void Burger::Filename::ToWindows ( const char * pInput )

Expand a filename into Windows/MSDOS format.

Using the rules for a Burgerlib type pathname, expand a path into a FULL pathname native to the Windows/MSDOS 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 prepend 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 NOT have a trailing "\", they will take the form of c:\foo\bar\file.txt or similar

Examples:
If drive C: is named "boot" then ":boot:foo:bar.txt" = "c:\foo\bar.txt"
If there is no drive named "boot" then ":boot:foo:bar.txt" = "\\boot\foo\bar.txt"
".D2:foo:bar.txt" = "c:\foo\bar.txt"
".D4:foo:bar.txt" = "e:\foo\bar.txt"
"@:game:data.dat" = "c:\users\<Current user>\appdata\roaming\game\data.dat"

Parameters:

pInput

Pointer to a pathname string