am_string_array.h

ADaM is a data mining and image processing toolkit

*/
string_array *mk_string_array_from_args(char *key, int argc, char** argv);
/* Same as above, but returns NULL if not present. */
string_array *mk_maybe_string_array_from_args(char *key, int argc, char** argv);

/* Doesn't do that kind of complicated interpolation above, just drops off each
   pair into the returned value. */
string_array *mk_string_array_from_argc_argv(int argc,char *argv[]);


/* Parse a boolean from a string array. */
bool bool_from_argarray( char *key, string_array *argarray, bool defval);

/* Parse an int from a string array. */
int int_from_argarray( char *key, string_array *argarray, int defval);

/* Parse a double from a string array. */
double double_from_argarray( char *key, string_array *argarray,
                             double defval);

/* Parse a string from a string array. */
char *mk_string_from_argarray( char *key, string_array *argarray,
			       char *defval);

/* Split argument array into our options and extra options.  This
   allows one project to parse its options, then pass the unparsed
   options to another project's parse function. */
void mk_split_option_array( string_array *keys_with_args,
                            string_array *keys_without_args,
                            string_array *argarray,
                            string_array **my_opts,
                            string_array **extra_opts);


/********* DATFILE PARSING UTILITIES ************/
/* moved in from amdmex.h */

/* int linestyle formats (we recommend AUTO_FORMAT)....

   The following constants determine how lines are read from
   a datafile. COMMA_FORMAT expects commas between each line on
   the datafile. WHITESPACE expects one or more spaces between 
   each item. BAR_FORMAT expects vertical bars (|)

   And AUTO_FORMAT will accept commas, whitespace and bars
   as separators. */
#define COMMA_FORMAT      0
#define WHITESPACE_FORMAT 1
#define BAR_FORMAT        2
#define AUTO_FORMAT       3

/************* NEW LINE PARSING CODE *************/

/* If line_format is WHITESPACE then the line is read SPACE_STYLE
   if line_format is COMMA      then the line is read COMMA_STYLE
   if line_format is BAR        then the line is read BAR_STYLE
   if lineformat is  ANY        then

        count the number of unquoted commas on the line (n_comma)
        and count the number of unquoted bars on the line (n_bar)

        if ( n_comma == 0 && n_bar == 0 ) use SPACE_FORMAT
        if ( n_comma >= n_bar )           use COMMA_FORMAT
        if ( n_bar > n_comma )            use BAR_FORMAT

   The line parser runs through a finite state machine. On
   each character it looks at the character type:

     S Space       - The character is the ' ' char
     C Comma       - The character is the ',' char
     A SingleQuote - The character is the '\'' char
     Q DoubleQuote - The character is the '\"' char
     T Token       - The character is something other than the above
     
   The line parser is building up an array of tokens. It begins with
   an empty array of tokens. It has a current token being built. It begins
   with the current token empty. After each character is read, it performs
   one of the following actions:

     ADD   Add the curent token to the array. Set the current token to empty
     PUSH  Put the current character at the end of the current token
     NIL   Do nothing
     DASH  Put a dash character at the end of the current token
     DP    Put a dash, then the current character at end of token
     UNKN  Add the UNKNOWN_STRING to the array. Clear current token


  COMMA_STYLE parsing:

       All whitespace to immediate left and right of commas is removed.
       All other contiguous blocks of whitespace are replaced with - symbols
         (outside quotes, N contiguous spaces are replaced with one -.
          inside quotes, N contiguous spaces are replaced with N -'s)
       The resulting tokens between commas are used.
       Empty string between commas is turned into UNKNOWN STRING
  
  SPACE_STYLE parsing:

       All whitespace inside quotes are turned to dashes
       All other CONTIGUOUS blocks of whitespace are collapsed to one space
       Then the resulting tokens between whitespaces are used.
*/


/* Return TRUE if and only if all items in sa can be parsed as numbers */
bool are_numbers(string_array *sa);

void fprint_string_array_csv(FILE *s,string_array *x);
  
/* A line is interesting if its not all white space and
the leftmost non whitespace character isnt # */
bool line_string_is_interesting(char *line_string);

bool line_contains_only_character_c(char *line_string,char c);
bool line_contains_only_dashes(char *line_string);

/* Searches the file for the next line that isn't all whitespace and
   that doesn't have # as its first non-whitespace character. 

   If no-such line before file-end, returns NULL */
char *mk_next_interesting_line_string(PFILE *s,int *line_number);

/* As above excepts breaks resulting line into a string array of tokens... */
/* DON'T USE THIS!! It's old and inferior to...

string_array *mk_next_tokens(FILE *s,int *line_number,int line_format);

which is documented later in this file */
string_array *mk_next_interesting_line(PFILE *s,int *line_number);
string_array *mk_parse_data_line(char *string,int line_format);
string_array *mk_next_tokens(PFILE *s,int *line_number,int line_format);
string_array *mk_default_attribute_names(int num_atts);
bool contains_a_number(string_array *sa);
/* not used or defined?
bool line_has_unquoted_comma(char *string); */
void line_count_unquoted(char *string, int *r_num_unquoted_commas, int *r_num_unquoted_bars);
bool all_numeric(string_array *sa);

/* ******************************************* */
/* string_matrix operations. Maybe belongs in its own file */

typedef struct string_matrix
{
  int array_size;
  int rows;
  int cols;
  string_array **sas;
} string_matrix, *string_matrix_ptr;

string_matrix *mk_string_matrix(int rows,int cols);
int string_matrix_rows(string_matrix *sm);
int string_matrix_cols(string_matrix *sm);
char *string_matrix_ref(string_matrix *sm,int row,int col);

/* Makes a COPY of char *value ... identical to string_matrix_set */
void string_matrix_set(string_matrix *sm,int row,int col,char *value);

/* Alias to string_matrix_set */
void sm_set(string_matrix *sm,int row,int col,char *value);

string_array *mk_string_array_from_string_matrix_col(string_matrix *sm,
						     int col);

void fprintf_string_matrix(FILE *s,char *m1,string_matrix *sm,char *m2);
void free_string_matrix(string_matrix *sm);
void string_matrix_add_row(string_matrix *sm);
int max_string_length_in_column(string_matrix *sm,int col);

/* Returns a new string array in which the i'th entry is
   the i'th row of a plain text representation of the contents
   of the string matrix. The columns of the table are separated by
   the strings in "seps". seps[0] always appears before the left-hand
   column. seps[1] before the second column. seps[cols] always
   appears to the right of the final column. The number of
   entries in "seps" must be one more than the number of columns
   in sm. 

   Alternatively, seps may be NULL in which case one space is
   printed between each column. No spaces to left or to right. */
	/* FIXME: That description can probably be written more clearly -- Pat */
string_array *mk_tabular_string_array(string_matrix *sm,string_array *seps);

/* As above but the i'th char in seps in the separator */
string_array *mk_tabular_string_array_simple(string_matrix *sm,
					     char *seps);

void render_string_matrix(FILE *s,char *comment,string_matrix *sm);

/* See comments for mk_tabular_string_array_simple regaring the meaning
   of "seps". */
void render_string_matrix_with_seps(FILE *s,string_matrix *sm,char *seps);

/* See comments for mk_tabular_string_array_simple regaring the meaning
   of "seps". 

   If the first string on a line is a single dash, then this version
   draws a complete line of dashes for the full width of the string
   matrix output. 
*/
void render_string_matrix_with_seps_and_dashes(FILE *s,string_matrix *sm,
					       char *seps);

void string_matrix_real_set(string_matrix *sm,int row,int col,double value);

/* breaks row_string. Error unless the number of space-sparated substrings
   equals number of cols in string matrix. Sets sm(row,i) to i'th substring
   forall i */
void string_matrix_row_from_broken_string(string_matrix *sm, int row, char *row_string);

/* Makes and returns a string array of given size in which
   every entry contains a copy of the string stored in value */
string_array *mk_constant_string_array(int size,char *value);

/* Makes an 'LS' style string matrix. That means it takes the
   string array and puts each element into cells of a string
   matrix. The string matrix has "cols" columns. The order in
   which string_array elements are placed is

      sa[0]      sa[r+0]    ....    sa[(cols-1)r+0]
      sa[1]      sa[r+1]    ....    sa[(cols-1)r+1]
        :                                  :
        :                                  :
        :                                  :
      sa[r-1]    sa[2r-1]   ....    sa[(cols-1)r-1]

    where r is the least r such that r*cols >= string_array_size

   ...and some of the rightmost column might be filled with
      empty cells.
*/
string_matrix *mk_ls_style_string_matrix_given_cols(string_array *name,int cols);

/* Returns the max string length in sa */
int string_array_max_length(string_array *sa);

/* Makes an 'LS' style string matrix cleverly designed so that when
   printed it uses less than "max_chars" characters per line. (it auto-chooses
   and sizes the columns) */
string_matrix *mk_ls_style_string_matrix(string_array *names,int max_chars);

int sm_rows(string_matrix *sm);

void sm_set_string(string_matrix *sm,int row,int col,char *string);

void sm_set_double(string_matrix *sm,int row,int col,double x);

void sm_set_int(string_matrix *sm,int row,int col,double n);

/***************** sosarray ***************/

bool string_less(char *s1,char *s2);
bool string_greater(char *s1,char *s2);
bool string_leq(char *s1,char *s2);
bool string_geq(char *s1,char *s2);

string_array *mk_string_array_from_string(char *s);

/* A sosarray is a regular old string_array, except it is treated as a set of
   integers.

   An string_array is a legal sosarray if it is sorted in increasing order with no
   duplicates.

   The following set of functions consititute a reasonable simple
   package of set-theory operations.

   Note that everything is as efficient as possible for a set package 
   except for adding a single element and deleting a single element, 
   which (because of our representation by means of sorted string_arrays) could
   take time linear in set size. */

bool is_sosarray(string_array *sa);

/* Returns number of elements in sosarray */
int sosarray_size(string_array *sosarr);

/* If sosarr has 0 elements returns 0
   If value > string_array_max(sosarr) returns size
   If value <= string_array_min(sosarr) returns 0
   Else returns index such that
      value <= string_array_ref(sosarr,index) 
      string_array_ref(sosarr,index-1) < value
      
   It returns the value such that string_array_insert(sa,index,value)
   would represent the set with value added to sa (assuming value
   wasn't already in sa). */
int find_sosarray_insert_index(string_array *sosarr,char *string);

/* Adds the element while maintaining legal sosarraykiness.
   (If element already there, no change)
   Time cost: O(size) */
void add_to_sosarray(string_array *sosarr,char *string);

/* Returns -1 if the string does not exist in sosarr.
   Else returns index such that
      string == string_array_ref(sosarr,string) 
  Time cost: O(log(size)) */
int index_in_sosarray(string_array *sosarr,char *string);

/* Returns true iff sosarr contains string
   Time cost: O(log(size)) */
bool is_in_sosarray(string_array *sosarr,char *string);

void sosarray_remove_at_index(string_array *sosarr,int idx);

/* Does nothing if string is not in sosarr.
   If string is in sosarr, the sosarray is updated to
   represent sosarr \ { string } */
void sosarray_remove_string(string_array *sosarr,char *string);
  
/* Returns answer to A subset-of B?
   Returns true if and only if the set of integers in a is
   a subset of the set of integers in b */
bool sosarray_subset(string_array *sosarra,string_array *sosarrb);

bool equal_string_array(string_array *sa1,string_array *sa2);

bool sosarray_equal(string_array *sosarra,string_array *sosarrb);

/* Returns TRUE iff A is a subset of B and A != B */
bool sosarray_strict_subset(string_array *sosarra,string_array *sosarrb);

string_array *mk_sosarray_union(string_array *sosarra,string_array *sosarrb);

/* Returns A \ B.
   This is { x : x in A and x not in B } */
string_array *mk_sosarray_difference(string_array *sosarra,string_array *sosarrb);

string_array *mk_sosarray_intersection(string_array *sosarra,string_array *sosarrb);

/* Returns TRUE iff A intersect B is empty. O(size) time */
bool sosarray_disjoint(string_array *sosarra,string_array *sosarrb);

string_array *mk_sosarray_from_string_array(string_array *sa);

/* Turns a space separated string into a sosarray.
   Example: "3 1 4 1 5 9" ====> { 1 , 3 , 4 , 5 , 9 } */
string_array *mk_sosarray_from_string(char *s);
char *sosarray_first(string_array *sosarr);
char *sosarray_last(string_array *sosarr);

string_array *mk_append_string_arrays(string_array *a,string_array *b);

#endif /* AM_STRING_ARRAY_H */