#ifndef TRIM_H
#define TRIM_H

/**
  @mainpage
  Trim Library is a tiny C library for trimming redudant whitespace in C-style strings

  All functions are declared in trim.h file.

  For using the library, just include trim.h and add trim.c to your C project.
  If you want to compile trim as a static library (for example to avoid warnings in C++),
  the following commands can be run in your Unix-like shell:

  @code
	DEFINES='-DTRIM_LINE1=1 -DTRIM_LINE2=0'
	gcc -Wall -std=c11 ${DEFINES} -c trim.c -o trim.o
	ar rcs libtrim.a trim.o
  @endcode

  Macro TRIM_LINE1 enables trim_line() function, which makes the eight types of trim
  in only a pass for the string.

  Macro TRIM_LINE2 enables trim_line2() function, which makes the same work than trim_line()
  but it is faster when the length of the string is already known.
*/


#include <ctype.h>
#include <stdbool.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @brief Removes any whitespace at the beginning of the text.
 *
 * This function only traverses the @a text string only once. Changes are made in place.
 * Whitespace characters are tested by isspace() C function, that is: space (' '),
 * tabulators ('\\t'), line feed ('\\n'), carriage return ('\\r'), and vertical tabulator ('\\v').
 *
 * All whitespaces are be removed at the beginning of the string. Function params tell where the
 * text string begins, so the function can start the whitespace removing. Example:
 *
 * @code
	// Assume for the following call, the value for str is
	char str[] = "\t\n Any\nText    ";

	trim_left(str); // yields: "Any\nText    "
 * @endcode
 *
 * @param text The string to be left-trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position with trim_left. The capacity of @a text will
 * be untouched.
 *
 * @return A pointer to the first character of @a text
 */
char* trim_left(char* text);

/**
 * @brief Removes any whitespace at the end of the given text.
 *
 * This function traverses the @a text string only once. Changes are made in place. Whitespace
 * characters are tested by isspace() C function, that is: space (' '), tabulators ('\\t'),
 * line feed ('\\n'), carriage return ('\\r'), and vertical tabulator ('\\v').
 *
 * This function removes any whitespace at the end of @a text. Trailing whitespace is after the last
 * non-whitespace character of the string. If @a text only contains whitespace, it will be emptied
 * Example:
 *
 * @code
	test1[] = "\t\t    Test   1\t\t";
	trim_right(test1); // yields: "\t\t    Test   1"

	char test2[] = "\t\t    \t\t";
	trim_right(test2)); // yields: ""
 * @endcode
 *
 * @param text The string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position. The capacity of @a text will be untouched.
 *
 * @return A pointer to the first character of @a text
 */
char* trim_right(char* text);

/**
 * @brief Function that removes any whitespace at the right section of a certain string.
 *
 * This funcion eliminates the repeated blank space in the string at the end of the sentence,
 * without eliminating it's contents. The @a len parameter conditions where the string ends
 * so the processing is faster than @a trim_right() in average. This function moves backward
 * from the end of @a text towards the beginning,and  makes changes as it travels across it.
 * This function moves the end-of-string ('\\0') character, but it does not delete actual memory
 * of @a text. Therefore @a text keeps its capacity. Example:
 *
 * @code
	char str[] = "   Juanita tenia un perro    ";
	trim_right2(str, 29); // Modifies to: "   Juanita tenia un perro"
 * @endcode
 *
 * @param text This is the string being trimmed by the function. This string will be changed
 * its respective end-of-string ('\\0') character may be positioned.
 *
 * @param len The lenght of @a text, or the number of characters that the caller wants to be
 * processed by trim_right2()
 *
 * @see trim_right()
 *
 * @return A pointer to the first character of the parameter string.
 */
char* trim_right2(char* text, size_t len);

/**
 * @brief Replaces redundant whitespace that is in the middle of the string with single space.
 *
 * This function works from the first non-whitespace char to the last non-whitespace char.
 * Changes are made in place. Redundant whitespace are considered continuous occurrences of
 * one or more whitespace characters. Whitespace characters are tested by isspace() C
 * function, that is: space (' '), tabulators ('\\t'), line feed ('\\n'), carriage return
 * ('\\r'), and vertical tabulator ('\\v'). If the string consists only of whitespaces or is
 * only one word (i.e. "ThisIsOnlyOneWord"), then the trim_inside() function won't have any
 * effect on the string. Redudant whitespace will be only removed at the middle of the string.
 *
 * @code
	char str[] = "\t\tLeft.  Inside   white\tspace. No right.";
	trim_inside(str); // yields: "\t\tLeft. Inside white space. No right."
 * @endcode
 *
 * @param text The string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position and some characters may be shifted left.
 * The capacity of @a text will be untouched.
 *
 * @remarks Please note multiple or single ocurrences of tabulators ('\\t'), line feeds ('\\n'),
 * carriage returns ('\\r'), and vertical tabulators ('\\v') will be replaced by a simple space
 * character (' ').
 *
 * @return A pointer to the first character of @a text
 */
char* trim_inside(char* text);

/**
 * @brief Removes any whitespace at the beginning and at the end of the given text.
 *
 * This function traverses the @a text string only once. Changes are made in place. Whitespace
 * characteres are tested by isspace() C function, that is: space (' '), tabulators ('\\t'), line
 * feed ('\\n'), carriage return ('\\r'), and vertical tabulator ('\\v'). Example:
 *
 * @code
	char str[] = "    Your waifu   is/t/t/not  hot as  mine/t/t";
	trim(str); // yields: "Your waifu   is/t/t/not  hot as  mine"
 * @endcode
 *
 * @param text The string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position and some characters may be shifted left.
 * The capacity of @a text will be untouched.
 *
 * @return A pointer to the first character of @a text
 */
char* trim(char* text);

/**
 * @brief Removes any whitespace at the beginning or at the end of the given text.
 *
 * trim2() has the same function as @a trim(), but trim2() is faster than trim() because it knows
 * the length of @a text. Therefore, trim2() traverses @a text from the end toward the beginning
 * and adjusts the end-of-string character ('\\0') in the appropiate position. The capacity of
 * @a text remains unchanged. Example:
 *
 * @code
	trim2("nothing to trim", 15); // yields: "nothing to trim"
	trim2("    nothing to trim", 19); // yields: "nothing to trim"
	trim2("nothing to trim   ", 18); // yields: "nothing to trim"
	trim2("   nothing   to trim  ", 22); // yields: "nothing   to trim"
 * @endcode
 *
 * @param text C-style string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text.
 *
 * @param len Length of @a text string given to be trimmed. It may be less than the actual length
 * of @a text if you want to trim until some character of @a text.
 *
 * @see trim()
 *
 * @return a pointer to the first characterr of the text finally trimmed.
 */
char* trim2(char* text, size_t len);

/**
 * @brief Removes redundant whitespace at the beginning, in the middle and at the end of the given
 * text.
 *
 * This function only traverses the @a text string only once. Changes are made in place. All
 * whitespace at beginning or at the end of @a text will be removed. Redudant whitespace in the
 * middle of @a text will be replaced for a sigle character. Redudant whitespace is considered
 * as continous ocurrences of one or more whitespace characters. Whitespace characteres are tested
 * by isspace() C function, that is: space (' '), tabulators ('\\t'), line feed ('\\n'), carriage
 * return ('\\r'), and vertical tabulator ('\\v'). Example
 *
 * @code
	char str[] = "     la   \t luz  \n    \t   del   \n camino\n";
	trim_all(str, 39); // yields: "la luz del camino"
 * @endcode
 *
 * @param text The string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position and some characters may be shifted left.
 * The capacity of @a text will be untouched.

 * @return A pointer to the first character of @a text
 */
char* trim_all(char* text);

/**
 * @brief Removes redundant whitespace at the beginning, in the middle and at the end of a text
 * whose length is know.
 *
 * This function makes the same work than @a trim_all(), but it is faster.
 *
 * @param text C-style string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text.
 *
 * @param len Length of @a text string given to be trimmed. It may be less than the actual length
 * of @a text if you want to trim until some character of @a text.
 *
 * @see trim_all()
 *
 * @return un apuntador a el primer caracter del texto despues de haberle aplicado la funcion trim_all2().
 */
char* trim_all2(char* text, size_t len);

#if TRIM_LINE1

/**
 * @brief Removes redundant whitespace at the beginning, in the middle or at the end of the given
 * text.
 *
 * This function only traverses the @a text string only once. Changes are made in place. Redudant
 * whitespace are considered continous ocurrences of one or more whitespace characters. Whitespace
 * characteres are tested by isspace() C function, that is: space (' '), tabulators ('\\t'), line
 * feed ('\\n'), carriage return ('\\r'), and vertical tabulator ('\\v').
 *
 * Redudant whitespace can be removed at the beginning, at the middle, or at the end of the string.
 * Function params help to control where to remove whitespace. For example,
 * @code
	// Assume for each following call, the value for str is
	char str[] = "\t\tLeft.  Inside   white\tspace. Right    ";

	//             L  I  R
	trim_line(str, 0, 0, 0); // yields: "\t\tLeft.  Inside   white\tspace. Right    "
	trim_line(str, 0, 0, 1); // yields: "\t\tLeft.  Inside   white\tspace. Right"
	trim_line(str, 0, 1, 0); // yields: "\t\tLeft. Inside white space. Right    "
	trim_line(str, 0, 1, 1); // yields: "\t\tLeft. Inside white space. Right"
	trim_line(str, 1, 0, 0); // yields: "Left.  Inside   white\tspace. Right    "
	trim_line(str, 1, 0, 1); // yields: "Left.  Inside   white\tspace. Right"
	trim_line(str, 1, 1, 0); // yields: "Left. Inside white space. Right    "
	trim_line(str, 1, 1, 1); // yields: "Left. Inside white space. Right"
@endcode
 *
 * @param text The string to be trimmed. Changes will be made in place. If you need to keep the
 * original text untouched, make a copy and call this function with the copyied text. The
 * end-of-string character ('\\0') may change its position and some characters may be shifted left.
 * The capacity of @a text will be untouched.
 *
 * @param left Send true if you want to remove any whitespace at the beginning of @a text, false if
 * you want to keep it. Leading whitespace is before the first non-whitespace character of the
 * string. If @a text only contains whitespace, it will be removed if @a left is true.
 *
 * @param inside Send true if you want to replace sequences of two or more whitespace characters
 * by one space character in the middle of the @a text. The middle of the string is considered
 * from the first non whitespace character to the last non whitespace character. If @a text is only
 * compound of whitespace, the param @a insided has no effect.
 *
 * @param right Send true if you want to remove any whitespace at the end of @a text, false if you
 * want to keep it. Trailing whitespace is after the last non-whitespace character of the string.
 * If @a text only contains whitespace, it will be removed if @a right is true.
 *
 * @return A pointer to the first character of @a text
 */
char* trim_line(char* text, bool left, bool inside, bool right);

#endif // TRIM_LINE1

#if TRIM_LINE2
/**
 * @brief Removes redundant whitespace at the beginning, in the middle or at the end of the given
 * text.
 *
 * This function works the same way that @a trim_line() does, with the slight difference that the
 * string length is known. It traverses the whole string, making trim_left, trim_right, or
 * trim_inside, depeding on its parameters. Whitespace characteres are tested by isspace() C
 * standard library function, that is: space (' '), tabulators ('\\t'), line feed ('\\n'), carriage
 * return ('\\r'), and vertical tabulator ('\\v'). Example:
 *
 * @code
	// Assume for each following call, the value for str is
	char str[] = "\t\tLeft.  Inside   white\tspace. Right    "; // length = 40 characters

	//                 L  I  R
	trim_line(str, 40, 0, 0, 0); // yields: "\t\tLeft.  Inside   white\tspace. Right    "
	trim_line(str, 40, 0, 0, 1); // yields: "\t\tLeft.  Inside   white\tspace. Right"
	trim_line(str, 40, 0, 1, 0); // yields: "\t\tLeft. Inside white space. Right    "
	trim_line(str, 40, 0, 1, 1); // yields: "\t\tLeft. Inside white space. Right"
	trim_line(str, 40, 1, 0, 0); // yields: "Left.  Inside   white\tspace. Right    "
	trim_line(str, 40, 1, 0, 1); // yields: "Left.  Inside   white\tspace. Right"
	trim_line(str, 40, 1, 1, 0); // yields: "Left. Inside white space. Right    "
	trim_line(str, 40, 1, 1, 1); // yields: "Left. Inside white space. Right"
 * @endcode
 *
 * @param text This is the string the caller sends as the text to be trimmed. In case you want to
 * keep the original text, make a copy of your text and give as a parameter the copied text.
 *
 * @param len The length of @a text. The function counts whitespaces as a position in the string;
 * therefore, after running this function,the length of @a text will be modified.
 *
 * @param left A truth value in which it is decided whether left whitespaces are trimmed or not.
 * If @a text only contains whitespace, it will be removed if @a left is true.
 *
 * @param inside A truth value in which it is decided whether infixed whitespaces are trimmed or
 * not. The middle of the string is considered from the first non whitespace character to the last
 * non whitespace character. If @a text is only compound of whitespace, the param @a insided has
 * no effect.
 *
 * @param right A truth value in which it is decided whether right whitespaces are trimmed or not.
 * Whitespeace is considered after the last non-space character within the string. If @a text only
 * contains whitespace and @a right is true, it will be removed as well.
 *
 * @return A pointer to the first character of @a text
 */
char* trim_line2(char* text, size_t len, bool left, bool inside, bool right);

#endif // TRIM_LINE2

#ifdef __cplusplus
}
#endif

#endif // TRIM_H