A header file for STAR format files. More...

#include "Bstring.h"

Classes
struct	Bstar_item

class	Bstar_block
	Structure for a data block with multiple items in a STAR database. More...

struct	Bstar_old

Macros
#define	LINELENGTH 80

#define	_STAR_OLD_

Enumerations
enum	StarType { CommentItem = 0 , StringItem = 1 , NumberItem = 2 }

Functions
Bstar_old *	init_star ()
	Creates a STAR data base. More...

int	kill_star (Bstar_old *star)
	Destroys a STAR data base. More...

int	kill_block (Bstar_block *block)
	Destroys a STAR data block. More...

int	kill_item (Bstar_item *item)
	Destroys an item in a data block in a STAR data base. More...

int	read_star (const char filename, Bstar_old star)
	Reads paramaters and data into a STAR data base from a list of files. More...

int	read_star (Bstring &filename, Bstar_old *star)

int	read_star (Bstring file_list, Bstar_old star)

Bstar_block *	read_block (ifstream fstar, char aptr, Bstring &filename)
	Reads paramaters and data into a STAR data block from an open file. More...

Bstar_item *	read_single_item (ifstream fstar, char aline)
	Reads a single-valued item or comment line into a STAR data block from an open file. More...

Bstar_item *	read_loop_items (ifstream *fstar)
	Reads a loop structure with multiple items into a STAR data block from an open file. More...

int	write_star (const char filename, Bstar_old star)
	Writes a STAR data base to one or more STAR format files. More...

int	write_star (Bstring &filename, Bstar_old *star)

int	write_block (ofstream fstar, Bstar_block block, int linelength)
	Writes paramaters and data from a STAR data block into an open file. More...

int	star_update_comment (Bstar_old star, int n, char *strings)
	Puts a set of strings and time in the main comment of the STAR data base. More...

long	star_list_comments (Bstar_old *star, long len)
	Lists the command lines in the STAR header. More...

int	star_set_string_lengths (Bstar_old *star)
	Sets the maximum string lengths for each item in each block. More...

int	item_change_tag (Bstar_old star, const char tag, const char *newtag)
	Replaces one tag with another in the STAR data base. More...

int	show_tags (Bstar_old *star)
	Prints the list of tags in the STAR data base. More...

int	item_index (Bstar_block block, const char tag)
	Gets the STAR item associated with a tag in a STAR data block. More...

Bstar_block *	block_find_with_tag (Bstar_old star, const char tag)
	Gets the first block associated with a tag in a STAR data base. More...

Bstar_item *	item_find (Bstar_block *block, Bstring tag)
	Gets the STAR item associated with a tag in a STAR data block. More...

Bstar_item *	item_find_or_make (Bstar_block block, const char tag)
	Gets the STAR item associated with a tag in a STAR data block. More...

long	item_get_number (Bstar_old star, const char tag)
	Gets the number of values associated with a tag in a STAR data base. More...

long	item_get_number_for_block (Bstar_block block, const char tag)
	Gets the number of values associated with a tag in a STAR data block. More...

char *	item_get_string (Bstar_block block, const char tag)
	Gets a string value associated with a tag in a STAR data block. More...

int	item_copy_string (char string, Bstar_block block, const char *tag)
	Copies a string value associated with a tag in a STAR data block. More...

int	item_get_integer (Bstar_block block, const char tag)
	Gets an integer value associated with a tag in a STAR data block. More...

float	item_get_float (Bstar_block block, const char tag)
	Gets a floating point value associated with a tag in a STAR data block. More...

int	item_put_string (Bstar_block block, const char tag, char *string)
	Writes a string into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_string (Bstar_block block, const char tag, Bstring &string)

int	item_put_string_list (Bstar_block block, const char tag, Bstring *list)
	Writes a list of strings into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_integer (Bstar_block block, const char tag, int value, const char *format)
	Writes a integer into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_float (Bstar_block block, const char tag, float value, const char *format)
	Writes a floating point value into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_list (Bstar_block block, const char tag, char list, size_t offset, const char format)
	Writes a list of string or numeric values into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_float_array (Bstar_block block, const char tag, int number, float value, const char format)
	Writes a list of floating point numbers into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_put_angle_list (Bstar_block block, const char tag, char list, size_t offset, const char format)
	Writes a list of angular values in degrees into a data item associated with a specific data block and tag in a STAR data base. More...

int	item_list (Bstar_old *star, Bstring &tag)
	Lists all items associated with a given tag from the STAR data base. More...

int	item_delete_all (Bstar_old star, const char tag)
	Deletes all items associated with a given tag from the STAR data base. More...

int	item_delete_from_block (Bstar_block block, const char tag)
	Deletes an item associated with a given tag from a block in the STAR data base. More...

int	block_delete (Bstar_old *star, Bstring &tag)
	Deletes all blocks with a given tag from the STAR data base. More...

int	item_integer_scale_shift (Bstar_old *star, Bstring &tag, int iscale, int ishift)
	Scales and shifts all items associated with a given tag from the STAR data base. More...

int	item_float_scale_shift (Bstar_old *star, Bstring &tag, float scale, float shift)
	Scales and shifts all items associated with a given tag from the STAR data base. More...

int	loop_set_identifier (Bstar_block *block, int loop, int n,...)
	Assigns a loop identification number to items. More...

int	item_get_format (Bstar_item item, char format)
	Gets the format from the item. More...

Detailed Description

A header file for STAR format files.

Author: Bernard Heymann

Date: Created: 19990605; Modified: 20190819

Macro Definition Documentation

◆ _STAR_OLD_

#define _STAR_OLD_

◆ LINELENGTH

#define LINELENGTH 80

Enumeration Type Documentation

◆ StarType

enum StarType

Enumerator
CommentItem
StringItem
NumberItem

Function Documentation

◆ block_delete()

int block_delete	(	Bstar_old *	star,
		Bstring &	tag
	)

Deletes all blocks with a given tag from the STAR data base.

Parameters

*star	the STAR database.
&tag	tag for blocks to be deleted.

Returns

int number of blocks deleted.

The blocks containing a given tag are deleted and the
block pointers are rearranged to fill in the gap.

◆ block_find_with_tag()

Bstar_block * block_find_with_tag	(	Bstar_old *	star,
		const char *	tag
	)

Gets the first block associated with a tag in a STAR data base.

Parameters

*star	the STAR data base.
*tag	a STAR tag string.

Returns: Bstar_block* the block, NULL if not found.

◆ init_star()

Bstar_old * init_star ( )

Creates a STAR data base.

Returns

Bstar_old* the new STAR data base.

A STAR structure is allocated.
This function should be called before reading a STAR file, or before
composing a STAR database for writing.

◆ item_change_tag()

int item_change_tag	(	Bstar_old *	star,
		const char *	tag,
		const char *	newtag
	)

Replaces one tag with another in the STAR data base.

Parameters

*star	the STAR database.
*tag	old tag.
*newtag	new tag.

Returns

int 0.

The item with a given tag has the tag replaced with a new one.
If an item with the new tag exists, it is deleted first.

◆ item_copy_string()

int item_copy_string	(	char *	string,
		Bstar_block *	block,
		const char *	tag
	)

Copies a string value associated with a tag in a STAR data block.

Parameters

*string	destination string - must exist on stack or allocated.
*block	block in the STAR database.
*tag	a STAR tag string.

Returns

int 0.

The STAR data blocks is traversed to obtain the string
value associated with a STAR tag defined in a header file.

◆ item_delete_all()

int item_delete_all	(	Bstar_old *	star,
		const char *	tag
	)

Deletes all items associated with a given tag from the STAR data base.

Parameters

*star	the STAR database.
*tag	tag for items to be deleted.

Returns

int 0.

The item with a given tag is deleted in all blocks it is found
and the item pointers are rearranged to fill in the gap.

◆ item_delete_from_block()

int item_delete_from_block	(	Bstar_block *	block,
		const char *	tag
	)

Deletes an item associated with a given tag from a block in the STAR data base.

Parameters

*block	block in the STAR database.
*tag	tag for items to be deleted.

Returns

int 0.

The item with a given tag is deleted in the specified block it is found
and the item pointers are rearranged to fill in the gap.

◆ item_find()

Bstar_item * item_find	(	Bstar_block *	block,
		Bstring	tag
	)

Gets the STAR item associated with a tag in a STAR data block.

Parameters

*block	a STAR data block.
*tag	a STAR tag string.

Returns

Bstar_item* the STAR item, NULL if the tag doesn't exist.

The items in the STAR data block are traversed to find the item
associated with a STAR tag defined in a header file.

◆ item_find_or_make()

Bstar_item * item_find_or_make	(	Bstar_block *	block,
		const char *	tag
	)

Gets the STAR item associated with a tag in a STAR data block.

Parameters

*block	a STAR data block.
*tag	a STAR tag string.

Returns

Bstar_item* the STAR item, NULL if the tag doesn't exist.

The items in the STAR data block are traversed to find the item
associated with a STAR tag defined in a header file.

◆ item_float_scale_shift()

int item_float_scale_shift	(	Bstar_old *	star,
		Bstring &	tag,
		float	scale,
		float	shift
	)

Scales and shifts all items associated with a given tag from the STAR data base.

Parameters

*star	the STAR database.
&tag	tag for items to be modified.
scale	multiplier.
shift	value added.

Returns

int total number of values changed.

The item must be numeric and is modified as:
    new_value = old_value*scale + shift.

◆ item_get_float()

float item_get_float	(	Bstar_block *	block,
		const char *	tag
	)

Gets a floating point value associated with a tag in a STAR data block.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.

Returns

float the floating point value, 0 if the tag doesn't exist.

The STAR data block is traversed to obtain the floating point
value associated with a STAR tag defined in a header file.

◆ item_get_format()

int item_get_format	(	Bstar_item *	item,
		char *	format
	)

Gets the format from the item.

Parameters

*item	STAR item.
*format	pointer to pre-allocated format string (modified).

Returns

int data type: 0=string, 1=integer, 2=float.

Returns the format in the given format string.

◆ item_get_integer()

int item_get_integer	(	Bstar_block *	block,
		const char *	tag
	)

Gets an integer value associated with a tag in a STAR data block.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.

Returns

int the integer value, 0 if the tag doesn't exist.

The STAR data block is traversed to obtain the first integer
value associated with a STAR tag defined in a header file.

◆ item_get_number()

long item_get_number	(	Bstar_old *	star,
		const char *	tag
	)

Gets the number of values associated with a tag in a STAR data base.

Parameters

*star	the STAR data base.
*tag	a STAR tag string.

Returns

long the number of values.

All STAR data blocks are traversed to count the number of
values associated with a STAR tag defined in a header file.

◆ item_get_number_for_block()

long item_get_number_for_block	(	Bstar_block *	block,
		const char *	tag
	)

Gets the number of values associated with a tag in a STAR data block.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.

Returns

long the number of values.

The STAR data block is traversed to count the number of
values associated with a STAR tag defined in a header file.

◆ item_get_string()

char * item_get_string	(	Bstar_block *	block,
		const char *	tag
	)

Gets a string value associated with a tag in a STAR data block.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.

Returns

char* the string value, NULL if the tag doesn't exist.

The STAR data block is traversed to obtain the string
value associated with a STAR tag defined in a header file.

◆ item_index()

int item_index	(	Bstar_block *	block,
		const char *	tag
	)

Gets the STAR item associated with a tag in a STAR data block.

Parameters

*block	a STAR data block.
*tag	a STAR tag string.

Returns

int the STAR item index, -1 if the tag doesn't exist.

The items in the STAR data block are traversed to find the item
associated with a STAR tag defined in a header file.

◆ item_integer_scale_shift()

int item_integer_scale_shift	(	Bstar_old *	star,
		Bstring &	tag,
		int	iscale,
		int	ishift
	)

Scales and shifts all items associated with a given tag from the STAR data base.

Parameters

*star	the STAR database.
&tag	tag for items to be modified.
iscale	multiplier.
ishift	value added.

Returns

int total number of values changed.

The item must be integer and is modified as:
    new_value = old_value*scale + shift.

◆ item_list()

int item_list	(	Bstar_old *	star,
		Bstring &	tag
	)

Lists all items associated with a given tag from the STAR data base.

Parameters

*star	the STAR database.
&tag	tag for items to be listed.

Returns

int 0.

The item with a given tag is listed to standard output as an end-of-line
delimited array.

◆ item_put_angle_list()

int item_put_angle_list	(	Bstar_block *	block,
		const char *	tag,
		char *	list,
		size_t	offset,
		const char *	format
	)

Writes a list of angular values in degrees into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
*list	linked list.
offset	offset of structure element.
*format	string format.

Returns

int error code.

Each angle in radians is first converted to degrees before writing it
into a string.

◆ item_put_float()

int item_put_float	(	Bstar_block *	block,
		const char *	tag,
		float	value,
		const char *	format
	)

Writes a floating point value into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
value	integer value.
*format	string format.

Returns: int error code.

◆ item_put_float_array()

int item_put_float_array	(	Bstar_block *	block,
		const char *	tag,
		int	number,
		float *	value,
		const char *	format
	)

Writes a list of floating point numbers into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
number	the number of values.
*value	a list of floating point values.
*format	string format.

Returns

int 0.

NaN values are taken as missing numbers and indicated by a '.' in the
STAR file.

◆ item_put_integer()

int item_put_integer	(	Bstar_block *	block,
		const char *	tag,
		int	value,
		const char *	format
	)

Writes a integer into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
value	integer value.
*format	string format.

Returns: int error code.

◆ item_put_list()

int item_put_list	(	Bstar_block *	block,
		const char *	tag,
		char *	list,
		size_t	offset,
		const char *	format
	)

Writes a list of string or numeric values into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
*list	linked list.
offset	offset of structure element.
*format	string format.

Returns: int error code.

◆ item_put_string() [1/2]

int item_put_string	(	Bstar_block *	block,
		const char *	tag,
		Bstring &	string
	)

◆ item_put_string() [2/2]

int item_put_string	(	Bstar_block *	block,
		const char *	tag,
		char *	string
	)

Writes a string into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
*string	string value.

Returns: int error code.

◆ item_put_string_list()

int item_put_string_list	(	Bstar_block *	block,
		const char *	tag,
		Bstring *	list
	)

Writes a list of strings into a data item associated with a specific data block and tag in a STAR data base.

Parameters

*block	block in the STAR database.
*tag	a STAR tag string.
*list	list of strings.

Returns: int error code.

◆ kill_block()

int kill_block ( Bstar_block * block )

Destroys a STAR data block.

Parameters

*block pointer to the STAR data block.

Returns

int 0.

A data block in a STAR data base structure and all of the items 
associated with that data block are freed.

◆ kill_item()

int kill_item ( Bstar_item * item )

Destroys an item in a data block in a STAR data base.

Parameters

*item the item.

Returns

int 0.

An item and all of the items referenced are freed.

◆ kill_star()

int kill_star ( Bstar_old * star )

Destroys a STAR data base.

Parameters

*star the STAR data base.

Returns

int 0.

A STAR data base structure and all of the data blocks and items are freed.

◆ loop_set_identifier()

int loop_set_identifier	(	Bstar_block *	block,
		int	loop,
		int	n,
			...
	)

Assigns a loop identification number to items.

Parameters

*block	block in the STAR database.
loop	loop identifier to use.
n	number of patterns to test for.
...	(tag_pattern) tag pattern to match to set the loop identifier.

Returns

int number assigned.

The items in the data block are rearranged so that the item assigned to 
the loop follows the other loop items.

◆ read_block()

Bstar_block * read_block	(	ifstream *	fstar,
		char *	aptr,
		Bstring &	filename
	)

Reads paramaters and data into a STAR data block from an open file.

Parameters

*fstar	an open STAR format file.
*aptr	a pointer to the current line in the file.
&filename	file containing this block.

Returns

Bstar_block* new block read.

A block defines a unit of parameters or a unit of data. Every data 
block is read separately and comments are preserved as far as possible.

◆ read_loop_items()

Bstar_item * read_loop_items ( ifstream * fstar )

Reads a loop structure with multiple items into a STAR data block from an open file.

Parameters

*fstar an open STAR format file.

Returns

Bstar_item* first new item in list.

The loop is read line by line, checking to get every column value in a row.
A row may extend over multiple lines, as long as it contains the number values
specified by the number of tags at the beginning of the loop.
A multiple line string value must be enclosed in ";" as the first character
in the lines before and after the string.
The loop ends with an empty line or when too few values occur in a row.
An empty line at the end of a loop is required.
Note: The loop flag field of the STAR item is equal to the item index
of the first item in the loop.

◆ read_single_item()

Bstar_item * read_single_item	(	ifstream *	fstar,
		char *	aline
	)

Reads a single-valued item or comment line into a STAR data block from an open file.

Parameters

*fstar	an open STAR format file.
*aline	a pointer to the current line in the file.

Returns

Bstar_item* new STAR item.

All tags with single values and outside loops are interpreted here.
A single item is defined where the first non-space character on a
line is an underscore. A comment is defined by a '#' or ';' as the
first character on the line.
Note: The loop flag field of the STAR item is equal to -1.

◆ read_star() [1/3]

int read_star	(	Bstring &	filename,
		Bstar_old *	star
	)

◆ read_star() [2/3]

int read_star	(	Bstring *	file_list,
		Bstar_old *	star
	)

◆ read_star() [3/3]

int read_star	(	const char *	filename,
		Bstar_old *	star
	)

Reads paramaters and data into a STAR data base from a list of files.

Parameters

*filename	a list of file names separated by commas.
*star	an existing STAR data base.

Returns

int error code (<0 means failure).

Every data block is read separately and comments are preserved as far 
as possible.

◆ show_tags()

int show_tags ( Bstar_old * star )

Prints the list of tags in the STAR data base.

Parameters

*star the STAR database

Returns: int number of tags.

◆ star_list_comments()

long star_list_comments	(	Bstar_old *	star,
		long	len
	)

Lists the command lines in the STAR header.

Parameters

*star	the STAR data base.
len	maximum line length, infinite if zero.

Returns: long the number of command lines.

◆ star_set_string_lengths()

int star_set_string_lengths ( Bstar_old * star )

Sets the maximum string lengths for each item in each block.

Parameters

*star the STAR data base.

Returns

int 0.

This is designed to clean up after creating a STAR database.

◆ star_update_comment()

int star_update_comment	(	Bstar_old *	star,
		int	n,
		char **	strings
	)

Puts a set of strings and time in the main comment of the STAR data base.

Parameters

*star	the STAR data base.
n	the number of strings.
**strings	an array of strings.

Returns

int string length of the new comment.

This is designed to pack the command line into a string followed by
a second string for the time.

◆ write_block()

int write_block	(	ofstream *	fstar,
		Bstar_block *	block,
		int	linelength
	)

Writes paramaters and data from a STAR data block into an open file.

Parameters

*fstar	an open STAR format file.
*block	a data block.
linelength	output maximum line length.

Returns

int error code (<0 on error).

A block defines a unit of parameters or a unit of data.

◆ write_star() [1/2]

int write_star	(	Bstring &	filename,
		Bstar_old *	star
	)

◆ write_star() [2/2]

int write_star	(	const char *	filename,
		Bstar_old *	star
	)

Writes a STAR data base to one or more STAR format files.

Parameters

*filename	the base file name (can be NULL if star->split == 9).
*star	the STAR data base.

Returns

int error code (<0 means failure).

The STAR data base structure contains a flag (star->split) to indicate
whether one or multiple files should be written.  In the case of multiple
files, the base name is taken from the input file name, with an underscore
and a number appended. The length of the number is determined by the
star->split variable.

Classes

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ _STAR_OLD_

◆ LINELENGTH

Enumeration Type Documentation

◆ StarType

Function Documentation

◆ block_delete()

◆ block_find_with_tag()

◆ init_star()

◆ item_change_tag()

◆ item_copy_string()

◆ item_delete_all()

◆ item_delete_from_block()

◆ item_find()

◆ item_find_or_make()

◆ item_float_scale_shift()

◆ item_get_float()

◆ item_get_format()

◆ item_get_integer()

◆ item_get_number()

◆ item_get_number_for_block()

◆ item_get_string()

◆ item_index()

◆ item_integer_scale_shift()

◆ item_list()

◆ item_put_angle_list()

◆ item_put_float()

◆ item_put_float_array()

◆ item_put_integer()

◆ item_put_list()

◆ item_put_string() [1/2]

◆ item_put_string() [2/2]

◆ item_put_string_list()

◆ kill_block()

◆ kill_item()

◆ kill_star()

◆ loop_set_identifier()

◆ read_block()

◆ read_loop_items()

◆ read_single_item()

◆ read_star() [1/3]

◆ read_star() [2/3]

◆ read_star() [3/3]

◆ show_tags()

◆ star_list_comments()

◆ star_set_string_lengths()

◆ star_update_comment()

◆ write_block()

◆ write_star() [1/2]

◆ write_star() [2/2]