MemoryFile Class Reference

Detailed Description

A virtual file, stored in memory.

#include <drake/common/memory_file.h>

Public Member Functions
	MemoryFile ()
	Default constructor with no contents, checksum, or filename hint. More...
	MemoryFile (std::string contents, std::string extension, std::string filename_hint)
	Constructs a new file from the given contents. More...
	~MemoryFile ()
const std::string &	contents () const
	Returns the file's contents. More...
const std::string &	extension () const
	Returns the extension (as passed to the constructor). More...
const Sha256 &	sha256 () const
	Returns the checksum of this instance's contents(). More...
const std::string &	filename_hint () const
	Returns the notional "filename" for this file`. More...
std::string	to_string (int contents_limit=100) const
	Returns a string representation. More...
template<typename Archive >
void	Serialize (Archive *a)
	Passes this object to an Archive. More...
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
	MemoryFile (const MemoryFile &)=default
MemoryFile &	operator= (const MemoryFile &)=default
	MemoryFile (MemoryFile &&)=default
MemoryFile &	operator= (MemoryFile &&)=default

Static Public Member Functions
static MemoryFile	Make (const std::filesystem::path &path)
	Creates an instance of MemoryFile from the file located at the given path. More...

Constructor & Destructor Documentation

MemoryFile() [1/4]

MemoryFile ( const MemoryFile &  )

default

MemoryFile() [2/4]

MemoryFile ( MemoryFile &&  )

default

MemoryFile() [3/4]

MemoryFile

(

)

Default constructor with no contents, checksum, or filename hint.

In this case, the checksum will be the checksum of the empty contents.

MemoryFile() [4/4]

MemoryFile	(	std::string	contents,
		std::string	extension,
		std::string	filename_hint
	)

Constructs a new file from the given contents.

Parameters

contents	The contents of a file.
extension	The extension typically associated with the file contents. The case is unimportant, but it must either be empty or of the form .foo.
filename_hint	A label for the file. The label is used for warning and error messages. Otherwise, the label has no other functional purpose. It need not be a valid file name, but must consist of a single line (no newlines).

Warning

An empty extension may be problematic. Many consumers of MemoryFile key on the extension to determine if the file is suitable for a purpose. Always provide an accurate, representative extension when possible.

Exceptions

std::exception	if filename_hint contains newlines.
std::exception	if extension is not empty and the first character isn't '.'.

~MemoryFile()

~MemoryFile

(

)

Member Function Documentation

contents()

const std::string& contents

(

)

const

Returns the file's contents.

extension()

const std::string& extension

(

)

const

Returns the extension (as passed to the constructor).

When not empty, it will always be reported with a leading period and all lower case characters.

filename_hint()

const std::string& filename_hint

(

)

const

Returns the notional "filename" for this file`.

Make()

static MemoryFile Make ( const std::filesystem::path &  path )

static

Creates an instance of MemoryFile from the file located at the given path.

The filename_hint() will be the stringified path. Making a MemoryFile computes the hash of its contents. If all you want is the contents, use drake::ReadFile() or drake::ReadFileOrThrow() instead.

Exceptions

std::exception

if the file at path cannot be read.

operator=() [1/2]

MemoryFile& operator= ( MemoryFile &&  )

default

operator=() [2/2]

MemoryFile& operator= ( const MemoryFile &  )

default

Serialize()

void Serialize

(

Archive *

a

)

Passes this object to an Archive.

Refer to YAML Serialization for background.

When used in yaml, it is important to specify all fields. Applications may depend on the extension value to determine what to do with the file contents. Omitting extension would make it unusable in those cases.

Omitting filename_hint is less dangerous; error messages would lack a helpful identifier, but things would otherwise function.

The value of contents should be a base64-encoded string of the file contents. Yaml's !!binary tag is required to declare the value is such a string. Serializing the MemoryFile will produce such a string. Writing a yaml file by hand will be more challenging.

For this yaml:

contents: !!binary VGhpcyBpcyBhbiBleGFtcGxlIG9mIG1
        lbW9yeSBmaWxlIHRlc3QgY29udGVudHMu
extension: .txt
filename_hint: payload.txt

we would produce a MemoryFile with contents equal to:

This is an example of memory file test contents.

sha256()

const Sha256& sha256

(

)

const

Returns the checksum of this instance's contents().

to_string()

std::string to_string

(

int

contents_limit = 100

)

const

Returns a string representation.

Note: the file contents will be limited to contents_limit number of characters. To include the full contents, pass any number less than or equal to zero.

---

The documentation for this class was generated from the following file:

• drake/common/memory_file.h