/**
 * string-utils.h
 *   Assorted string utilities.
 */

#ifndef __STRING_UTILS_H__
#define __STRING_UTILS_H__

// +---------+--------------------------------------------------------
// | Headers |
// +---------+

#include <stdio.h>	// For FILE


// +-----------+------------------------------------------------------
// | Functions |
// +-----------+

/**
 * Procedure:
 *   string_compare
 * Parameters:
 *   str1, a string
 *   str2, a string
 * Purpose:
 *   Compare str1 and str2
 * Produces:
 *   comparison, an integer
 * Philosophy:
 *   Just like strcmp, but works for NULLs, too.
 */
int string_compare (char *str1, char *str2);

/**
 * Procedure:
 *   string_equal
 * Parameters:
 *   s1, a string
 *   s2, a string
 * Purpose:
 *   Determines whether s1 and s2 are the same string
 * Produces:
 *   is_equal, an integer (representing a Boolean)
 * Preconditions:
 *   No additional
 * Postconditions:
 *   If s1 would be considered equal to s2, then is_equal is 1.
 *   Otherwise, is_equal is 0.
 * Philosophy:
 *   Slightly safter than using strcmp, because string_equal supports
 *   NULL pointers.
 */
int string_equal (char *s1, char *s2);

/**
 * Procedure:
 *   string_fprint
 * Parameters:
 *   fp, a FILE *
 *   str, a string
 * Purpose:
 *   Print str to fp in a 'nice' way.
 * Produces:
 *   [A value similar to fprintf.]
 * Philosophy:
 *   Puts quotation marks around the string, deals with NULL.
 */
int string_fprint (FILE *fp, char *str);

#endif // __STRING_UTILS_H__