common/string_util.h

/* Copyright (C) 2013-2016, The Regents of The University of Michigan.
All rights reserved.
This software was developed in the APRIL Robotics Lab under the
direction of Edwin Olson, ebolson@umich.edu. This software may be
available under alternative licensing terms; contact the address above.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the Regents of The University of Michigan.
*/

#pragma once

#include <stdio.h>
#include <stdarg.h>
#include <stdbool.h>
#include <ctype.h>

#include "zarray.h"

#ifdef __cplusplus
extern "C" {
#endif


typedef struct string_buffer string_buffer_t;

typedef struct string_feeder string_feeder_t;
struct string_feeder
{
    char *s;
    size_t len;
    size_t pos;

    int line, col;
};

/**
 * Similar to sprintf(), except that it will malloc() enough space for the
 * formatted string which it returns. It is the caller's responsibility to call
 * free() on the returned string when it is no longer needed.
 */
char *sprintf_alloc(const char *fmt, ...)
#ifndef _MSC_VER
__attribute__ ((format (printf, 1, 2)))
#endif
;

/**
 * Similar to vsprintf(), except that it will malloc() enough space for the
 * formatted string which it returns. It is the caller's responsibility to call
 * free() on the returned string when it is no longer needed.
 */
char *vsprintf_alloc(const char *fmt, va_list args);

/**
 * Concatenates 1 or more strings together and returns the result, which will be a
 * newly allocated string which it is the caller's responsibility to free.
 */
#define str_concat(...) _str_concat_private(__VA_ARGS__, NULL)
char *_str_concat_private(const char *first, ...);


// Returns the index of the first character that differs:
int str_diff_idx(const char * a, const char * b);

/**
 * Splits the supplied string into an array of strings by subdividing it at
 * each occurrence of the supplied delimiter string. The split strings will not
 * contain the delimiter. The original string will remain unchanged.
 * If str is composed of all delimiters, an empty array will be returned.
 *
 * It is the caller's responsibilty to free the returned zarray, as well as
 * the strings contained within it, e.g.:
 *
 *   zarray_t *za = str_split("this is a haystack", " ");
 *      => ["this", "is", "a", "haystack"]
 *   zarray_vmap(za, free);
 *   zarray_destroy(za);
 */
zarray_t *str_split(const char *str, const char *delim);

zarray_t *str_split_spaces(const char *str);

void str_split_destroy(zarray_t *s);

/*
 * Determines if str1 exactly matches str2 (more efficient than strcmp(...) == 0)
 */
static inline bool streq(const char *str1, const char* str2)
{
    int i;
    for (i = 0 ; str1[i] != '\0' ; i++) {
        if (str1[i] != str2[i])
            return false;
    }

    return str2[i] == '\0';
}

/**
 * Determines if str1 exactly matches str2, ignoring case (more efficient than
 * strcasecmp(...) == 0)
 */
static inline bool strcaseeq(const char *str1, const char* str2)
{
    int i;
    for (i = 0 ; str1[i] != '\0' ; i++) {
        if (str1[i] == str2[i])
            continue;
        else if (islower(str1[i]) && (str1[i] - 32) == str2[i])
            continue;
        else if (isupper(str1[i]) && (str1[i] + 32) == str2[i])
            continue;

        return false;
    }

    return str2[i] == '\0';
}

/**
 * Trims whitespace characters (i.e. matching isspace()) from the beginning and/or
 * end of the supplied string. This change affects the supplied string in-place.
 * The supplied/edited string is returned to enable chained reference.
 *
 * Note: do not pass a string literal to this function
 */
char *str_trim(char *str);

/**
 * Trims whitespace characters (i.e. matching isspace()) from the beginning
 * of the supplied string. This change affects the supplied string in-place.
 * The supplied/edited string is returned to enable chained reference.
 *
 * Note: do not pass a string literal to this function
 */
char *str_lstrip(char *str);

/**
 * Trims whitespace characters (i.e. matching isspace()) from the end of the
 * supplied string. This change affects the supplied string in-place.
 * The supplied/edited string is returned to enable chained reference.
 *
 * Note: do not pass a string literal to this function
 */
char *str_rstrip(char *str);

/**
 * Returns true if the end of string 'haystack' matches 'needle', else false.
 *
 * Note: An empty needle ("") will match any source.
 */
bool str_ends_with(const char *haystack, const char *needle);

/**
 * Returns true if the start of string 'haystack' matches 'needle', else false.
 *
 * Note: An empty needle ("") will match any source.
 */
bool str_starts_with(const char *haystack, const char *needle);

/**
 * Returns true if the start of string 'haystack' matches any needle, else false.
 *
 * Note: An empty needle ("") will match any source.
 */
bool str_starts_with_any(const char *haystack, const char **needles, int num_needles);

/**
 * Returns true if the string 'haystack' matches any needle, else false.
 */
bool str_matches_any(const char *haystack, const char **needles, int num_needles);

/**
 * Retrieves a (newly-allocated) substring of the given string, 'str', starting
 * from character index 'startidx' through index 'endidx' - 1 (inclusive).
 * An 'endidx' value -1 is equivalent to strlen(str).
 *
 * It is the caller's responsibility to free the returned string.
 *
 * Examples:
 *   str_substring("string", 1, 3) = "tr"
 *   str_substring("string", 2, -1) = "ring"
 *   str_substring("string", 3, 3) = ""
 *
 * Note: startidx must be >= endidx
 */
char *str_substring(const char *str, size_t startidx, long endidx);

/**
 * Retrieves the zero-based index of the beginning of the supplied substring
 * (needle) within the search string (haystack) if it exists.
 *
 * Returns -1 if the supplied needle is not found within the haystack.
 */
int str_indexof(const char *haystack, const char *needle);

    static inline int str_contains(const char *haystack, const char *needle) {
        return str_indexof(haystack, needle) >= 0;
    }

// same as above, but returns last match
int str_last_indexof(const char *haystack, const char *needle);

/**
 * Replaces all upper-case characters within the supplied string with their
 * lower-case counterparts, modifying the original string's contents.
 *
 * Returns the supplied / modified string.
 */
char *str_tolowercase(char *s);

/**
 * Replaces all lower-case characters within the supplied string with their
 * upper-case counterparts, modifying the original string's contents.
 *
 * Returns the supplied / modified string.
 */
char *str_touppercase(char *s);

/**
 * Replaces all occurrences of 'needle' in the string 'haystack', substituting
 * for them the value of 'replacement', and returns the result as a newly-allocated
 * string. The original strings remain unchanged.
 *
 * It is the caller's responsibility to free the returned string.
 *
 * Examples:
 *   str_replace("string", "ri", "u") = "stung"
 *   str_replace("singing", "ing", "") = "s"
 *   str_replace("string", "foo", "bar") = "string"
 *
 * Note: An empty needle will match only an empty haystack
 */
char *str_replace(const char *haystack, const char *needle, const char *replacement);

    char *str_replace_many(const char *_haystack, ...);
//////////////////////////////////////////////////////
// String Buffer

/**
 * Creates and initializes a string buffer object which can be used with any of
 * the string_buffer_*() functions.
 *
 * It is the caller's responsibility to free the string buffer resources with
 * a call to string_buffer_destroy() when it is no longer needed.
 */
string_buffer_t *string_buffer_create();

/**
 * Frees the resources associated with a string buffer object, including space
 * allocated for any appended characters / strings.
 */
void string_buffer_destroy(string_buffer_t *sb);

/**
 * Appends a single character to the end of the supplied string buffer.
 */
void string_buffer_append(string_buffer_t *sb, char c);

/**
 * Removes a single character from the end of the string and
 * returns it. Does nothing if string is empty and returns NULL
 */
char string_buffer_pop_back(string_buffer_t *sb);

/**
 * Appends the supplied string to the end of the supplied string buffer.
 */
void string_buffer_append_string(string_buffer_t *sb, const char *str);

/**
 * Formats the supplied string and arguments in a manner akin to printf(), and
 * appends the resulting string to the end of the supplied string buffer.
 */
void string_buffer_appendf(string_buffer_t *sb, const char *fmt, ...)
#ifndef _MSC_VER
__attribute__ ((format (printf, 2, 3)))
#endif
;

/**
 * Determines whether the character contents held by the supplied string buffer
 * ends with the supplied string.
 *
 * Returns true if the string buffer's contents ends with 'str', else false.
 */
bool string_buffer_ends_with(string_buffer_t *sb, const char *str);

/**
 * Returns the string-length of the contents of the string buffer (not counting \0).
 * Equivalent to calling strlen() on the string returned by string_buffer_to_string(sb).
 */
size_t string_buffer_size(string_buffer_t *sb);

/**
 * Returns the contents of the string buffer in a newly-allocated string, which
 * it is the caller's responsibility to free once it is no longer needed.
 */
char *string_buffer_to_string(string_buffer_t *sb);

/**
 * Clears the contents of the string buffer, setting its length to zero.
 */
void string_buffer_reset(string_buffer_t *sb);

//////////////////////////////////////////////////////
// String Feeder

/**
 * Creates a string feeder object which can be used to traverse the supplied
 * string using the string_feeder_*() functions. A local copy of the string's
 * contents will be stored so that future changes to 'str' will not be
 * reflected by the string feeder object.
 *
 * It is the caller's responsibility to call string_feeder_destroy() on the
 * returned object when it is no longer needed.
 */
string_feeder_t *string_feeder_create(const char *str);

/**
 * Frees resources associated with the supplied string feeder object, after
 * which it will no longer be valid for use.
 */
void string_feeder_destroy(string_feeder_t *sf);

/**
 * Determines whether any characters remain to be retrieved from the string
 * feeder's string (not including the terminating '\0').
 *
 * Returns true if at least one more character can be retrieved with calls to
 * string_feeder_next(), string_feeder_peek(), string_feeder_peek(), or
 * string_feeder_consume(), else false.
 */
bool string_feeder_has_next(string_feeder_t *sf);

/**
 * Retrieves the next available character from the supplied string feeder
 * (which may be the terminating '\0' character) and advances the feeder's
 * position to the next character in the string.
 *
 * Note: Attempts to read past the end of the string will throw an assertion.
 */
char string_feeder_next(string_feeder_t *sf);

/**
 * Retrieves a series of characters from the supplied string feeder. The number
 * of characters returned will be 'length' or the number of characters
 * remaining in the string, whichever is shorter. The string feeder's position
 * will be advanced by the number of characters returned.
 *
 * It is the caller's responsibility to free the returned string when it is no
 * longer needed.
 *
 * Note: Calling once the end of the string has already been read will throw an assertion.
 */
char *string_feeder_next_length(string_feeder_t *sf, size_t length);

/**
 * Retrieves the next available character from the supplied string feeder
 * (which may be the terminating '\0' character), but does not advance
 * the feeder's position so that subsequent calls to _next() or _peek() will
 * retrieve the same character.
 *
 * Note: Attempts to peek past the end of the string will throw an assertion.
 */
char string_feeder_peek(string_feeder_t *sf);

/**
 * Retrieves a series of characters from the supplied string feeder. The number
 * of characters returned will be 'length' or the number of characters
 * remaining in the string, whichever is shorter. The string feeder's position
 * will not be advanced.
 *
 * It is the caller's responsibility to free the returned string when it is no
 * longer needed.
 *
 * Note: Calling once the end of the string has already been read will throw an assertion.
 */
char *string_feeder_peek_length(string_feeder_t *sf, size_t length);

/**
 * Retrieves the line number of the current position in the supplied
 * string feeder, which will be incremented whenever a newline is consumed.
 *
 * Examples:
 *   prior to reading 1st character:                line = 1, column = 0
 *   after reading 1st non-newline character:       line = 1, column = 1
 *   after reading 2nd non-newline character:       line = 1, column = 2
 *   after reading 1st newline character:           line = 2, column = 0
 *   after reading 1st character after 1st newline: line = 2, column = 1
 *   after reading 2nd newline character:           line = 3, column = 0
 */
int string_feeder_get_line(string_feeder_t *sf);

/**
 * Retrieves the column index in the current line for the current position
 * in the supplied string feeder, which will be incremented with each
 * non-newline character consumed, and reset to 0 whenever a newline (\n) is
 * consumed.
 *
 * Examples:
 *   prior to reading 1st character:                line = 1, column = 0
 *   after reading 1st non-newline character:       line = 1, column = 1
 *   after reading 2nd non-newline character:       line = 1, column = 2
 *   after reading 1st newline character:           line = 2, column = 0
 *   after reading 1st character after 1st newline: line = 2, column = 1
 *   after reading 2nd newline character:           line = 3, column = 0
 */
int string_feeder_get_column(string_feeder_t *sf);

/**
 * Determines whether the supplied string feeder's remaining contents starts
 * with the given string.
 *
 * Returns true if the beginning of the string feeder's remaining contents matches
 * the supplied string exactly, else false.
 */
bool string_feeder_starts_with(string_feeder_t *sf, const char *str);

/**
 * Consumes from the string feeder the number of characters contained in the
 * given string (not including the terminating '\0').
 *
 * Throws an assertion if the consumed characters do not exactly match the
 * contents of the supplied string.
 */
void string_feeder_require(string_feeder_t *sf, const char *str);

/*#ifndef strdup
    static inline char *strdup(const char *s) {
        int len = strlen(s);
        char *out = malloc(len+1);
        memcpy(out, s, len + 1);
        return out;
    }
#endif
*/


// find everything that looks like an env variable and expand it
// using getenv. Caller should free the result.
// e.g. "$HOME/abc" ==> "/home/ebolson/abc"
char *str_expand_envs(const char *in);

#ifdef __cplusplus
}
#endif