occ::io::ShelxFile Class Reference

Unified reader/writer for SHELX .res/.ins crystallographic files. More...

#include <shelxfile.h>

Public Member Functions
	ShelxFile ()=default
	Default constructor.
std::optional< occ::crystal::Crystal >	read_crystal_from_file (const std::string &filename)
	Read a crystal structure from a SHELX file.
std::optional< occ::crystal::Crystal >	read_crystal_from_string (const std::string &contents)
	Read a crystal structure from a SHELX-formatted string.
bool	write_crystal_to_file (const occ::crystal::Crystal &crystal, const std::string &filename)
	Write a crystal structure to a SHELX file.
std::string	write_crystal_to_string (const occ::crystal::Crystal &crystal)
	Write a crystal structure to a SHELX-formatted string.
void	write_crystal_to_stream (const occ::crystal::Crystal &crystal, std::ostream &stream)
	Write a crystal structure to an output stream.
void	set_title (const std::string &title)
	Set the title/comment for SHELX output.
void	set_wavelength (double wavelength)
	Set the X-ray wavelength for SHELX output.
const std::string &	error_message () const
	Get the last error message.

Static Public Member Functions
static bool	is_likely_shelx_filename (const std::string &filename)
	Check if a filename appears to be a SHELX file.

Detailed Description

Unified reader/writer for SHELX .res/.ins crystallographic files.

The ShelxFile class provides functionality to read and write crystal structures in the SHELX format, which is widely used in crystallography.

SHELX files contain crystallographic data including:

• Unit cell parameters (CELL line)
• Lattice type and centrosymmetry (LATT line)
• Symmetry operations (SYMM lines)
• Scattering factor types (SFAC line)
• Atomic coordinates and site occupancies

The class handles both .res (result) and .ins (instruction) file extensions and provides round-trip compatibility for reading and writing structures.

Example Usage:

occ::io::ShelxFile shelx;
shelx.set_title("My Crystal Structure");
shelx.set_wavelength(1.54178); // Cu Kα
 
// Write crystal to file
if (shelx.write_crystal_to_file(crystal, "structure.res")) {
    std::cout << "Successfully wrote SHELX file" << std::endl;
}
 
// Read crystal from file
auto result = shelx.read_crystal_from_file("structure.res");
if (result.has_value()) {
    auto crystal = result.value();
    // Use crystal...
}

Constructor & Destructor Documentation

ShelxFile()

occ::io::ShelxFile::ShelxFile ( )

default

Default constructor.

Creates a ShelxFile instance with default settings:

• Title: "Crystal structure"
• Wavelength: 1.54178 Å (Cu Kα)

Member Function Documentation

error_message()

const std::string & occ::io::ShelxFile::error_message ( ) const

inline

Get the last error message.

Returns a description of the last parsing or writing error that occurred.

Returns

Error message string, empty if no error

is_likely_shelx_filename()

static bool occ::io::ShelxFile::is_likely_shelx_filename ( const std::string &  filename )

static

Check if a filename appears to be a SHELX file.

Examines the file extension to determine if it's likely a SHELX file.

Parameters

filename

File path to check

Returns

true if extension is .res or .ins

read_crystal_from_file()

std::optional< occ::crystal::Crystal > occ::io::ShelxFile::read_crystal_from_file

(

const std::string &

filename

)

Read a crystal structure from a SHELX file.

Parses a SHELX .res or .ins file and constructs a Crystal object from the contained crystallographic data.

Parameters

filename

Path to the SHELX file to read

Returns

Optional Crystal object, nullopt if parsing failed

Note

Use error_message() to get details if parsing fails

read_crystal_from_string()

std::optional< occ::crystal::Crystal > occ::io::ShelxFile::read_crystal_from_string

(

const std::string &

contents

)

Read a crystal structure from a SHELX-formatted string.

Parses SHELX format data directly from a string buffer.

Parameters

contents

String containing SHELX-formatted data

Returns

Optional Crystal object, nullopt if parsing failed

Note

Use error_message() to get details if parsing fails

set_title()

void occ::io::ShelxFile::set_title ( const std::string &  title )

inline

Set the title/comment for SHELX output.

Sets the title that will be written to the TITL line in SHELX files.

Parameters

title

Title string (will be written after "TITL ")

set_wavelength()

void occ::io::ShelxFile::set_wavelength ( double  wavelength )

inline

Set the X-ray wavelength for SHELX output.

Sets the wavelength that will be written to the CELL line. Common values: 1.54178 Å (Cu Kα), 0.71073 Å (Mo Kα)

Parameters

wavelength

Wavelength in Angstroms (default: 1.54178 Å)

write_crystal_to_file()

bool occ::io::ShelxFile::write_crystal_to_file	(	const occ::crystal::Crystal &	crystal,
		const std::string &	filename
	)

Write a crystal structure to a SHELX file.

Writes the crystal structure in SHELX format to the specified file. The output includes all necessary SHELX keywords and formatting.

Parameters

crystal	Crystal structure to write
filename	Path where the SHELX file should be written

Returns

true if successful, false otherwise

Note

Use error_message() to get details if writing fails

write_crystal_to_stream()

void occ::io::ShelxFile::write_crystal_to_stream	(	const occ::crystal::Crystal &	crystal,
		std::ostream &	stream
	)

Write a crystal structure to an output stream.

Writes the crystal structure in SHELX format to the provided stream.

Parameters

crystal	Crystal structure to write
stream	Output stream to write to

write_crystal_to_string()

std::string occ::io::ShelxFile::write_crystal_to_string

(

const occ::crystal::Crystal &

crystal

)

Write a crystal structure to a SHELX-formatted string.

Converts the crystal structure to SHELX format and returns as string.

Parameters

crystal

Crystal structure to convert

Returns

String containing SHELX-formatted data

---

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

• /home/runner/work/occ/occ/include/occ/io/shelxfile.h