VCV Rack API v2
Functions
rack::system Namespace Reference

Cross-platform functions for OS, file path, and filesystem routines. More...

Functions

std::string join (const std::string &path1, const std::string &path2="")
 Joins two paths with a directory separator. More...
 
template<typename... Paths>
std::string join (const std::string &path1, const std::string &path2, Paths... paths)
 Join an arbitrary number of paths, from left to right. More...
 
std::vector< std::string > getEntries (const std::string &dirPath, int depth=0)
 Returns all entries (directories, files, symbolic links, etc) in a directory. More...
 
bool exists (const std::string &path)
 
bool isFile (const std::string &path)
 Returns whether the given path is a file. More...
 
bool isDirectory (const std::string &path)
 Returns whether the given path is a directory. More...
 
uint64_t getFileSize (const std::string &path)
 
bool rename (const std::string &srcPath, const std::string &destPath)
 Moves a file or directory. More...
 
bool copy (const std::string &srcPath, const std::string &destPath)
 Copies a file or directory recursively. More...
 
bool createDirectory (const std::string &path)
 Creates a directory. More...
 
bool createDirectories (const std::string &path)
 Creates all directories up to the path. More...
 
bool createSymbolicLink (const std::string &target, const std::string &link)
 
bool remove (const std::string &path)
 Deletes a file or empty directory. More...
 
int removeRecursively (const std::string &path)
 Deletes a file or directory recursively. More...
 
std::string getWorkingDirectory ()
 
void setWorkingDirectory (const std::string &path)
 
std::string getTempDirectory ()
 
std::string getAbsolute (const std::string &path)
 Returns the absolute path beginning with "/". More...
 
std::string getCanonical (const std::string &path)
 Returns the canonical (unique) path, following symlinks and "." and ".." fake directories. More...
 
std::string getDirectory (const std::string &path)
 Extracts the parent directory of the path. More...
 
std::string getFilename (const std::string &path)
 Extracts the filename of the path. More...
 
std::string getStem (const std::string &path)
 Extracts the portion of a filename without the extension. More...
 
std::string getExtension (const std::string &path)
 Extracts the extension of a filename, including the dot. More...
 
std::vector< uint8_t > readFile (const std::string &path)
 Reads an entire file into a memory buffer. More...
 
uint8_t * readFile (const std::string &path, size_t *size)
 
void writeFile (const std::string &path, const std::vector< uint8_t > &data)
 Writes a memory buffer to a file, overwriting if already exists. More...
 
void archiveDirectory (const std::string &archivePath, const std::string &dirPath, int compressionLevel=1)
 Compresses the contents of a directory (recursively) to an archive. More...
 
std::vector< uint8_t > archiveDirectory (const std::string &dirPath, int compressionLevel=1)
 
void unarchiveToDirectory (const std::string &archivePath, const std::string &dirPath)
 Extracts an archive into a directory. More...
 
void unarchiveToDirectory (const std::vector< uint8_t > &archiveData, const std::string &dirPath)
 
int getLogicalCoreCount ()
 Returns the number of logical simultaneous multithreading (SMT) (e.g. More...
 
void setThreadName (const std::string &name)
 Sets a name of the current thread for debuggers and OS-specific process viewers. More...
 
std::string getStackTrace ()
 Returns the caller's human-readable stack trace with "\n"-separated lines. More...
 
double getTime ()
 Returns the number of seconds since application launch. More...
 
double getUnixTime ()
 Returns time since 1970-01-01 00:00:00 UTC in seconds. More...
 
double getThreadTime ()
 
std::string getOperatingSystemInfo ()
 
void openBrowser (const std::string &url)
 Opens a URL in a browser. More...
 
void openDirectory (const std::string &path)
 Opens Windows Explorer, Finder, etc at a directory location. More...
 
void runProcessDetached (const std::string &path)
 Runs an executable without blocking. More...
 
PRIVATE void init ()
 

Detailed Description

Cross-platform functions for OS, file path, and filesystem routines.

Function Documentation

◆ join() [1/2]

std::string rack::system::join ( const std::string &  path1,
const std::string &  path2 = "" 
)

Joins two paths with a directory separator.

If path2 is an empty string, returns path1.

◆ join() [2/2]

template<typename... Paths>
std::string rack::system::join ( const std::string &  path1,
const std::string &  path2,
Paths...  paths 
)

Join an arbitrary number of paths, from left to right.

◆ getEntries()

std::vector< std::string > rack::system::getEntries ( const std::string &  dirPath,
int  depth = 0 
)

Returns all entries (directories, files, symbolic links, etc) in a directory.

depth is the number of directories to recurse. 0 depth does not recurse. -1 depth recurses infinitely.

◆ exists()

bool rack::system::exists ( const std::string &  path)

◆ isFile()

bool rack::system::isFile ( const std::string &  path)

Returns whether the given path is a file.

◆ isDirectory()

bool rack::system::isDirectory ( const std::string &  path)

Returns whether the given path is a directory.

◆ getFileSize()

uint64_t rack::system::getFileSize ( const std::string &  path)

◆ rename()

bool rack::system::rename ( const std::string &  srcPath,
const std::string &  destPath 
)

Moves a file or directory.

Does not overwrite the destination. If this behavior is needed, use remove() or removeRecursively() before moving. Returns whether the rename was successful.

◆ copy()

bool rack::system::copy ( const std::string &  srcPath,
const std::string &  destPath 
)

Copies a file or directory recursively.

Overwrites destination if already exists. Returns whether the copy was successful.

◆ createDirectory()

bool rack::system::createDirectory ( const std::string &  path)

Creates a directory.

The parent directory must exist. Returns whether the creation was successful.

◆ createDirectories()

bool rack::system::createDirectories ( const std::string &  path)

Creates all directories up to the path.

Returns whether the creation was successful.

◆ createSymbolicLink()

bool rack::system::createSymbolicLink ( const std::string &  target,
const std::string &  link 
)

◆ remove()

bool rack::system::remove ( const std::string &  path)

Deletes a file or empty directory.

Returns whether the deletion was successful.

◆ removeRecursively()

int rack::system::removeRecursively ( const std::string &  path)

Deletes a file or directory recursively.

Returns the number of files and directories that were deleted.

◆ getWorkingDirectory()

std::string rack::system::getWorkingDirectory ( )

◆ setWorkingDirectory()

void rack::system::setWorkingDirectory ( const std::string &  path)

◆ getTempDirectory()

std::string rack::system::getTempDirectory ( )

◆ getAbsolute()

std::string rack::system::getAbsolute ( const std::string &  path)

Returns the absolute path beginning with "/".

◆ getCanonical()

std::string rack::system::getCanonical ( const std::string &  path)

Returns the canonical (unique) path, following symlinks and "." and ".." fake directories.

The path must exist on the filesystem. Examples: getCanonical("/foo/./bar/.") // "/foo/bar"

◆ getDirectory()

std::string rack::system::getDirectory ( const std::string &  path)

Extracts the parent directory of the path.

Examples: getDirectory("/var/tmp/example.txt") // "/var/tmp" getDirectory("/") // "" getDirectory("/var/tmp/.") // "/var/tmp"

◆ getFilename()

std::string rack::system::getFilename ( const std::string &  path)

Extracts the filename of the path.

Examples: getFilename("/foo/bar.txt") // "bar.txt" getFilename("/foo/.bar") // ".bar" getFilename("/foo/bar/") // "." getFilename("/foo/.") // "." getFilename("/foo/..") // ".." getFilename(".") // "." getFilename("..") // ".." getFilename("/") // "/"

◆ getStem()

std::string rack::system::getStem ( const std::string &  path)

Extracts the portion of a filename without the extension.

Examples: getStem("/foo/bar.txt") // "bar" getStem("/foo/.bar") // "" getStem("/foo/foo.tar.ztd") // "foo.tar"

◆ getExtension()

std::string rack::system::getExtension ( const std::string &  path)

Extracts the extension of a filename, including the dot.

Examples: getExtension("/foo/bar.txt") // ".txt" getExtension("/foo/bar.") // "." getExtension("/foo/bar") // "" getExtension("/foo/bar.txt/bar.cc") // ".cc" getExtension("/foo/bar.txt/bar.") // "." getExtension("/foo/bar.txt/bar") // "" getExtension("/foo/.") // "" getExtension("/foo/..") // "" getExtension("/foo/.hidden") // ".hidden"

◆ readFile() [1/2]

std::vector< uint8_t > rack::system::readFile ( const std::string &  path)

Reads an entire file into a memory buffer.

Throws on error.

◆ readFile() [2/2]

uint8_t * rack::system::readFile ( const std::string &  path,
size_t *  size 
)

◆ writeFile()

void rack::system::writeFile ( const std::string &  path,
const std::vector< uint8_t > &  data 
)

Writes a memory buffer to a file, overwriting if already exists.

Throws on error.

◆ archiveDirectory() [1/2]

void rack::system::archiveDirectory ( const std::string &  archivePath,
const std::string &  dirPath,
int  compressionLevel = 1 
)

Compresses the contents of a directory (recursively) to an archive.

Uses the Unix Standard TAR + Zstandard format (.tar.zst). An equivalent shell command is 

tar -c -C dirPath . | zstd -1 -o archivePath

or 

ZSTD_CLEVEL=1 tar -cf archivePath --zstd -C dirPath .

Throws on error.

◆ archiveDirectory() [2/2]

std::vector< uint8_t > rack::system::archiveDirectory ( const std::string &  dirPath,
int  compressionLevel = 1 
)

◆ unarchiveToDirectory() [1/2]

void rack::system::unarchiveToDirectory ( const std::string &  archivePath,
const std::string &  dirPath 
)

Extracts an archive into a directory.

An equivalent shell command is 

zstd -d < archivePath | tar -x -C dirPath

or 

tar -xf archivePath --zstd -C dirPath

Throws on error.

◆ unarchiveToDirectory() [2/2]

void rack::system::unarchiveToDirectory ( const std::vector< uint8_t > &  archiveData,
const std::string &  dirPath 
)

◆ getLogicalCoreCount()

int rack::system::getLogicalCoreCount ( )

Returns the number of logical simultaneous multithreading (SMT) (e.g.

Intel Hyperthreaded) threads on the CPU.

◆ setThreadName()

void rack::system::setThreadName ( const std::string &  name)

Sets a name of the current thread for debuggers and OS-specific process viewers.

◆ getStackTrace()

std::string rack::system::getStackTrace ( )

Returns the caller's human-readable stack trace with "\n"-separated lines.

◆ getTime()

double rack::system::getTime ( )

Returns the number of seconds since application launch.

Gives the most precise (fine-grained) time differences available on the OS for benchmarking purposes, while being fast to compute.

◆ getUnixTime()

double rack::system::getUnixTime ( )

Returns time since 1970-01-01 00:00:00 UTC in seconds.

◆ getThreadTime()

double rack::system::getThreadTime ( )

◆ getOperatingSystemInfo()

std::string rack::system::getOperatingSystemInfo ( )

◆ openBrowser()

void rack::system::openBrowser ( const std::string &  url)

Opens a URL in a browser.

Shell injection is possible, so make sure the URL is trusted or hard coded. Does nothing if string is blank. Does not block.

◆ openDirectory()

void rack::system::openDirectory ( const std::string &  path)

Opens Windows Explorer, Finder, etc at a directory location.

Does nothing if string is blank. Does not block.

◆ runProcessDetached()

void rack::system::runProcessDetached ( const std::string &  path)

Runs an executable without blocking.

The launched process will continue running if the current process is closed.

◆ init()

PRIVATE void rack::system::init ( )