File.h File Reference

#include <carta-protobuf/enums.pb.h>
#include "FileSystem.h"

Include dependency graph for File.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	FITS_MAGIC_NUMBER   0x504D4953
#define	HDF5_MAGIC_NUMBER   0x46444889
#define	XML_MAGIC_NUMBER   0x6D783F3C
#define	FILE_LIST_FIRST_PROGRESS_AFTER_SECS   5
#define	FILE_LIST_PROGRESS_INTERVAL_SECS   2
#define	ALL_FILES   -1
#define	TEMP_FILE_ID   -100

Functions
bool	CheckFolderPaths (std::string &top_level_string, std::string &starting_string)
	Validates and resolves folder paths, ensuring the starting directory is within the top-level directory.
bool	IsSubdirectory (std::string folder, std::string top_folder)
	Determines whether a given folder is a subdirectory of a specified top-level folder.
CARTA::FileType	GuessImageType (const std::string &path_string, bool check_content)
	Determines the image file type based on its content or extension.
CARTA::FileType	GuessRegionType (const std::string &path_string, bool check_content)
	Determines the region file type based on its content or extension.
CARTA::CatalogFileType	GuessTableType (const std::string &path_string, bool check_content)
	Determines the catalog table file type based on its content or file extension.
uint32_t	GetMagicNumber (const std::string &filename)
	Reads the magic number from the beginning of a file.
bool	IsCompressedFits (const std::string &filename)
	Checks whether a given file is a compressed FITS file.
bool	IsGzMagicNumber (uint32_t magic_number)
	Determines if a given magic number corresponds to a gzip-compressed file.
bool	IsRemoteHttpFile (const std::string &filename)
	Checks whether a given filename represents a remote HTTP or HTTPS URL.
int	GetNumItems (const std::string &path)
	Counts the number of items in a given directory.
fs::path	SearchPath (std::string filename)
	Searches for a file in the system's PATH environment variable.

Macro Definition Documentation

ALL_FILES

#define ALL_FILES   -1

FILE_LIST_FIRST_PROGRESS_AFTER_SECS

#define FILE_LIST_FIRST_PROGRESS_AFTER_SECS   5

FILE_LIST_PROGRESS_INTERVAL_SECS

#define FILE_LIST_PROGRESS_INTERVAL_SECS   2

FITS_MAGIC_NUMBER

#define FITS_MAGIC_NUMBER   0x504D4953

HDF5_MAGIC_NUMBER

#define HDF5_MAGIC_NUMBER   0x46444889

TEMP_FILE_ID

#define TEMP_FILE_ID   -100

XML_MAGIC_NUMBER

#define XML_MAGIC_NUMBER   0x6D783F3C

Function Documentation

CheckFolderPaths()

bool CheckFolderPaths	(	std::string &	top_level_string,
		std::string &	starting_string
	)

Validates and resolves folder paths, ensuring the starting directory is within the top-level directory.

Parameters

[in,out]	top_level_string	Reference to the top-level directory path. It is updated to its resolved absolute path.
[in,out]	starting_string	Reference to the starting directory path. It is updated to its resolved absolute path.

Returns

true if the paths are valid and the starting directory is within the top-level directory, otherwise false.

This function checks and resolves the given top-level and starting directories. If default placeholder values ("base" or "root") are found, they are replaced accordingly. The function verifies that both directories exist and are accessible, and ensures that the starting directory is a valid subdirectory of the top-level directory.

Note

If starting_string is invalid, it is replaced with top_level_string.

If starting_string is not a subdirectory of top_level_string, the function logs a critical error and returns false.

Warning

If both top_level_string and starting_string are set to their default placeholders ("base" and "root"), the function logs a critical error and returns false.

Here is the call graph for this function:

Here is the caller graph for this function:

GetMagicNumber()

uint32_t GetMagicNumber

(

const std::string &

filename

)

Reads the magic number from the beginning of a file.

Parameters

filename

The path to the file.

Returns

The magic number as a uint32_t. If the file cannot be opened or read, returns 0.

This function opens the specified file and reads the first 4 bytes as a uint32_t magic number.

Note

• The function assumes the file's magic number is stored in the first 4 bytes.
• Reads the file in binary mode would be safer to avoid unwanted conversions.
• The byte order (endianness) of the magic number depends on the system architecture.

Warning

• If the file does not exist or is not readable, the function returns 0 without error messages.

Here is the caller graph for this function:

GetNumItems()

int GetNumItems

(

const std::string &

path

)

Counts the number of items in a given directory.

Parameters

[in]

path

The path to the directory whose items are to be counted.

Returns

The number of items in the directory, or -1 if the directory cannot be accessed.

This function iterates over the contents of the specified directory and counts the number of files and subdirectories present. If the directory does not exist or cannot be accessed, the function returns -1.

Note

This function does not distinguish between files and subdirectories; it counts both.

Warning

If the path is invalid or inaccessible, an exception is caught internally, and -1 is returned.

Here is the caller graph for this function:

GuessImageType()

CARTA::FileType GuessImageType	(	const std::string &	path_string,
		bool	check_content
	)

Determines the image file type based on its content or extension.

Parameters

[in]	path_string	The path to the image file to be identified.
[in]	check_content	If true, the function checks the file's magic number; otherwise, it checks the file extension.

Returns

The detected file type as a CARTA::FileType enumeration:

• CARTA::FITS for FITS files.
• CARTA::HDF5 for HDF5 files.
• CARTA::UNKNOWN if the file type cannot be determined.

This function attempts to identify the type of an image file either by checking its magic number (file signature) or examining its file extension. If check_content is set to true, the function inspects the file's magic number to classify it as FITS or HDF5. If check_content is false, it relies on common file extensions.

Note

When check_content is enabled, compressed FITS files (.fits.gz) are identified by their decompressed filename extension.

Warning

Checking the file content requires reading the file's magic number, which may introduce additional I/O overhead.

Here is the call graph for this function:

Here is the caller graph for this function:

GuessRegionType()

CARTA::FileType GuessRegionType	(	const std::string &	path_string,
		bool	check_content
	)

Determines the region file type based on its content or extension.

Parameters

[in]	path_string	The path to the region file to be identified.
[in]	check_content	If true, the function checks the file's header; otherwise, it relies on the file extension.

Returns

The detected file type as a CARTA::FileType enumeration:

• CARTA::CRTF for CASA Region Text Format (CRTF) files.
• CARTA::DS9_REG for DS9 region files.
• CARTA::UNKNOWN if the file type cannot be determined.

This function attempts to identify the type of a region file used in astronomical imaging analysis by either checking its file content or examining its file extension. If check_content is true, it reads the first line of the file to identify known headers (e.g., #CRTF or # Region file format: DS9). Otherwise, it determines the file type based on its extension.

Note

CRTF files typically start with #CRTF, while DS9 region files may include # Region file format: DS9 as an optional header.

Warning

Checking file content requires reading the first line, which may introduce a slight I/O overhead.

Here is the call graph for this function:

Here is the caller graph for this function:

GuessTableType()

CARTA::CatalogFileType GuessTableType	(	const std::string &	path_string,
		bool	check_content
	)

Determines the catalog table file type based on its content or file extension.

Parameters

path_string	The file path as a string.
check_content	If true, the function checks the file's magic number for type detection. If false, it relies on the file extension.

Returns

CARTA::CatalogFileType The detected file type, which can be:

• CARTA::CatalogFileType::FITSTable for FITS table files.
• CARTA::CatalogFileType::VOTable for XML-based VOTable files.
• CARTA::CatalogFileType::Unknown if the type cannot be determined.

This function attempts to classify the type of a catalog table file (e.g., FITS table or VOTable) either by checking its magic number (if check_content is true) or, if content checking is disabled, by inspecting the file extension.

Note

If check_content is enabled, the function may attempt to read the file's magic number. Ensure the file is accessible to avoid potential I/O errors.

Warning

This function does not validate file integrity; it only determines type based on basic signature matching or filename extensions.

Here is the call graph for this function:

Here is the caller graph for this function:

IsCompressedFits()

bool IsCompressedFits

(

const std::string &

filename

)

Checks whether a given file is a compressed FITS file.

Parameters

[in]

filename

The path to the file being checked.

Returns

true if the file is a gzip-compressed FITS file, otherwise false.

This function first determines if the file is gzip-compressed by examining its magic number. If the file is gzip-compressed, it then checks whether the original filename (before compression) has a .fits extension.

Here is the call graph for this function:

Here is the caller graph for this function:

IsGzMagicNumber()

bool IsGzMagicNumber

(

uint32_t

magic_number

)

Determines if a given magic number corresponds to a gzip-compressed file.

Parameters

[in]

magic_number

The 32-bit magic number extracted from the file.

Returns

true if the magic number matches the gzip signature, otherwise false.

This function checks whether the provided 32-bit magic number matches the gzip file signature (0x1f8b). The magic number is formatted as a hexadecimal string and examined to see if it ends with "8b1f".

Note

This function assumes little-endian byte order for checking the magic number.

Here is the caller graph for this function:

IsRemoteHttpFile()

bool IsRemoteHttpFile

(

const std::string &

filename

)

Checks whether a given filename represents a remote HTTP or HTTPS URL.

Parameters

[in]

filename

The string to be checked.

Returns

true if the filename is an HTTP or HTTPS URL, otherwise false.

This function uses a regular expression to determine if the provided filename starts with "http://" or "https://", indicating that it is a remote file accessible via HTTP.

Note

This function does not verify if the URL is accessible or valid beyond its prefix.

Here is the caller graph for this function:

IsSubdirectory()

bool IsSubdirectory	(	std::string	folder,
		std::string	top_folder
	)

Determines whether a given folder is a subdirectory of a specified top-level folder.

Parameters

[in]	folder	The folder path to check, represented as a string.
[in]	top_folder	The top-level folder path to compare against, represented as a string.

Returns

true if folder is a subdirectory of top_folder or the same directory, false otherwise.

This function checks if folder is a subdirectory of top_folder by resolving both paths to their absolute, weakly canonical forms and then traversing up the directory hierarchy.

Warning

If top_folder is empty, the function will always return true.

Here is the caller graph for this function:

SearchPath()

fs::path SearchPath

(

std::string

filename

)

Searches for a file in the system's PATH environment variable.

Parameters

[in]

filename

The name of the file to search for.

Returns

The full path to the located file, or an empty fs::path if not found.

This function retrieves the PATH environment variable, splits it into individual directory paths, and searches for the specified file within those directories. If the file is found, its full path is returned. If not found or if an error occurs, an empty fs::path is returned.

Note

This function assumes that path entries in PATH are separated by colons (:), which is standard on UNIX-like systems.

Warning

If the PATH environment variable is not set, this function may behave unexpectedly.

Here is the call graph for this function:

Here is the caller graph for this function: