/Users/bernard/b20/bsoft/src/rwparam/rwstar.cpp(3)

NAME
/Users/bernard/b20/bsoft/src/rwparam/rwstar.cpp - Parse and interpret STAR format files.

SYNOPSIS

#include 'rwstar.h'
#include 'linked_list.h'
#include 'file_util.h'
#include 'utilities.h'
#include <iostream>
#include <stdarg.h>

  Functions
char * clean_line (char *string)
string clean_line (string s)
int no_square_brackets (Bstar *star)
bool tag_compare (Bstring item_tag, Bstring tag)
Bstar * init_star ()
Creates a STAR data base.
int kill_star (Bstar *star)
Destroys a STAR data base.
int kill_block (Bstar_block *block)
Destroys a STAR data block.
int kill_item (Bstar_item *item)
Destroys an item in a data block in a STAR data base.
int read_star (const char *filename, Bstar *star)
Reads paramaters and data into a STAR data base from a list of files.
int read_star (Bstring &filename, Bstar *star)
int read_star (Bstring *file_list, Bstar *star)
Bstar_block * read_block (ifstream *fstar, char *aptr, Bstring &filename)
Reads paramaters and data into a STAR data block from an open file.
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.
Bstar_item * read_loop_items (ifstream *fstar)
Reads a loop structure with multiple items into a STAR data block from an open file.
int write_star (const char *filename, Bstar *star)
Writes a STAR data base to one or more STAR format files.
int write_star (Bstring &filename, Bstar *star)
int write_block (ofstream *fstar, Bstar_block *block, int linelength)
Writes paramaters and data from a STAR data block into an open file.
int star_update_comment (Bstar *star, int n, char **strings)
Puts a set of strings and time in the main comment of the STAR data base.
long star_list_comments (Bstar *star, long len)
Lists the command lines in the STAR header.
int star_set_string_lengths (Bstar *star)
Sets the maximum string lengths for each item in each block.
int item_change_tag (Bstar *star, const char *tag, const char *newtag)
Replaces one tag with another in the STAR data base.
int show_tags (Bstar *star)
Prints the list of tags in the STAR data base.
int item_index (Bstar_block *block, const char *tag)
Gets the STAR item associated with a tag in a STAR data block.
Bstar_block * block_find_with_tag (Bstar *star, const char *tag)
Gets the first block associated with a tag in a STAR data base.
Bstar_item * item_find (Bstar_block *block, const char *tag)
Gets the STAR item associated with a tag in a STAR data block.
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.
long item_get_number (Bstar *star, const char *tag)
Gets the number of values associated with a tag in a STAR data base.
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.
char * item_get_string (Bstar_block *block, const char *tag)
Gets a string value associated with a tag in a STAR data block.
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.
int item_get_integer (Bstar_block *block, const char *tag)
Gets an integer value associated with a tag in a STAR data block.
float item_get_float (Bstar_block *block, const char *tag)
Gets a floating point value associated with a tag in a STAR data block.
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.
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.
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.
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.
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.
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.
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.
int item_list (Bstar *star, Bstring &tag)
Lists all items associated with a given tag from the STAR data base.
int item_delete_all (Bstar *star, const char *tag)
Deletes all items associated with a given tag from the STAR data base.
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.
int block_delete (Bstar *star, Bstring &tag)
Deletes all blocks with a given tag from the STAR data base.
int item_integer_scale_shift (Bstar *star, Bstring &tag, int iscale, int ishift)
Scales and shifts all items associated with a given tag from the STAR data base.
int item_float_scale_shift (Bstar *star, Bstring &tag, float scale, float shift)
Scales and shifts all items associated with a given tag from the STAR data base.
int loop_set_identifier (Bstar_block *block, int loop, int n,...)
Assigns a loop identification number to items.
int item_get_format (Bstar_item *item, char *format)
Gets the format from the item.

  Variables
int verbose

Detailed Description

Parse and interpret STAR format files.

Author:
    Bernard Heymann

Date:
    Created: 19990605

    Modified: 20190819

Definition in file rwstar.cpp.

Function Documentation

  int block_delete (Bstar * 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.

Definition at line 1662 of file rwstar.cpp.

  Bstar_block* block_find_with_tag (Bstar * 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.

Definition at line 1050 of file rwstar.cpp.

  char* clean_line (char * string)

Definition at line 23 of file rwstar.cpp.

  string clean_line (string s)

Definition at line 49 of file rwstar.cpp.

  Bstar* init_star ()

Creates a STAR data base.

Returns:
    Bstar* 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.

Definition at line 111 of file rwstar.cpp.

  int item_change_tag (Bstar * 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.

Definition at line 966 of file rwstar.cpp.

  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.

Definition at line 1220 of file rwstar.cpp.

  int item_delete_all (Bstar * 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.

Definition at line 1603 of file rwstar.cpp.

  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.

Definition at line 1626 of file rwstar.cpp.

  Bstar_item* item_find (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.

Definition at line 1083 of file rwstar.cpp.

  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.

Definition at line 1105 of file rwstar.cpp.

  int item_float_scale_shift (Bstar * 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.

Definition at line 1751 of file rwstar.cpp.

  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.

Definition at line 1273 of file rwstar.cpp.

  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.

Definition at line 1837 of file rwstar.cpp.

  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.

Definition at line 1245 of file rwstar.cpp.

  long item_get_number (Bstar * 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.

Definition at line 1134 of file rwstar.cpp.

  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.

Definition at line 1163 of file rwstar.cpp.

  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.

Definition at line 1189 of file rwstar.cpp.

  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.

Definition at line 1029 of file rwstar.cpp.

  int item_integer_scale_shift (Bstar * 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.

Definition at line 1709 of file rwstar.cpp.

  int item_list (Bstar * 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.

Definition at line 1571 of file rwstar.cpp.

  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.

Definition at line 1528 of file rwstar.cpp.

  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.

Definition at line 1401 of file rwstar.cpp.

  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.

Definition at line 1486 of file rwstar.cpp.

  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.

Definition at line 1368 of file rwstar.cpp.

  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.

Definition at line 1436 of file rwstar.cpp.

  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.

Definition at line 1300 of file rwstar.cpp.

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

Definition at line 1306 of file rwstar.cpp.

  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.

Definition at line 1337 of file rwstar.cpp.

  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.

Definition at line 163 of file rwstar.cpp.

  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.

Definition at line 197 of file rwstar.cpp.

  int kill_star (Bstar * 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.

Definition at line 132 of file rwstar.cpp.

  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.

Definition at line 1803 of file rwstar.cpp.

  int no_square_brackets (Bstar * star)

Definition at line 73 of file rwstar.cpp.

  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.

Definition at line 356 of file rwstar.cpp.

  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.

Definition at line 528 of file rwstar.cpp.

  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.

Definition at line 427 of file rwstar.cpp.

  int read_star (const char * filename, Bstar * 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.

Definition at line 224 of file rwstar.cpp.

  int read_star (Bstring & filename, Bstar * star)

Definition at line 239 of file rwstar.cpp.

  int read_star (Bstring * file_list, Bstar * star)

Definition at line 245 of file rwstar.cpp.

  int show_tags (Bstar * star)

Prints the list of tags in the STAR data base.

Parameters:
    *star the STAR database

Returns:
    int number of tags.

Definition at line 991 of file rwstar.cpp.

  long star_list_comments (Bstar * 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.

Definition at line 907 of file rwstar.cpp.

  int star_set_string_lengths (Bstar * 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.

Definition at line 938 of file rwstar.cpp.

  int star_update_comment (Bstar * 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.

Definition at line 880 of file rwstar.cpp.

  bool tag_compare (Bstring item_tag, Bstring tag)

Definition at line 91 of file rwstar.cpp.

  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.

Definition at line 750 of file rwstar.cpp.

  int write_star (const char * filename, Bstar * 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.

Definition at line 666 of file rwstar.cpp.

  int write_star (Bstring & filename, Bstar * star)

Definition at line 672 of file rwstar.cpp.

Variable Documentation

  int verbose

Author

Generated automatically by Doxygen for Bsoft from the source code.