mc/mhl/README

Micro helper library.
--

This is a tiny library of helper functions/macros. 

    * MACRO-FUNC:	macro w/ function syntax. (might become inline func)
    * INLINE-FUNC:	inline function (might become macro func)
    * MACRO:		strictly a macro (may never become a inline func)

--

mhl/memory.h:	Memory management functions

    * mhl_mem_alloc_u(sz)				[MACRO-FUNC]
    
	Allocate sz bytes on stack, unitialized

    * mhl_mem_alloc_z(sz)				[INLINE-FUNC]

	Allocate sz bytes on stack, zero'ed

    * mhl_mem_free(ptr)					[INLINE-FUNC]

	Free chunk @ptr (MUST be allocated w/ mhl_mem_alloc_*()),
	passing NULL is graciously allowed

    * mhl_mem_realloc(ptr,newsize) -> returns newptr
    
	Re-allocates a heap chunk, just like realloc()

    * MHL_PTR_FREE(ptr)					[MACRO-ONLY]
    
	like mhl_mem_free(), but with ptr as a variable that gets cleared
	(use this as shortcut to "mhl_mem_free(foo); foo = NULL")

mhl/string.h:	String helpers

    * mhl_str_dup(const char*s) -> char*

	[MACRO-FUNC] Safe version of strdup(), when NULL passed, returns strdup("")

    * mhl_str_ndup(const char* s) -> char*

	[MACRO-FUNC] Safe version of strndup(), when NULL passed, returns strdup("")

    * mhl_str_trim(char* s) -> char*

	[INLINE-FUNC] Trims the string (removing leading and trailing whitespacs), 
	WITHIN the passed buffer, returning the string s itself.
	When NULL passed returns NULL.

    * mhl_str_toupper(char* s) -> char*

	[INLINE-FUNC] Converts the string in passed buffer to uppercase, returns that
	buffer. When NULL passed returns NULL.

    * mhl_str_concat_1(const char* base, const char* one) -> char*

	[INLINE-FUNC] Concatenates the string one onto the string base and returns the
	result in a newly allocated buffer (free it w/ mhl_mem_free()).
	For NULL strings, "" is assumed.

    * mhl_str_concat_2(const char* base,const char* one,const char* two) -> char*
      mhl_str_concat_3(const char* base,const char* one,const char* two,const char* three) -> char*
      mhl_str_concat_4(const char* base,const char* one,const char* two,const char* three,const char* four) -> char*
      mhl_str_concat_5(const char* base,const char* one,const char* two,const char* three,const char* four,const char* five) -> char*
      mhl_str_concat_6(const char* base,const char* one,const char* two,const char* three,const char* four,const char* five,const char* six) -> char*
      mhl_str_concat_7(const char* base,const char* one,const char* two,const char* three,const char* four,const char* five,const char* six,const char* seven) -> char*
    
	[INLINE-FUNC] Like str_concat_1() but adding more strings.

    * mhl_str_reverse(char* str)	-> char*
    
	[INLINE-FUNC] Reverses the string in passed buffer and returns the buffer ptr itself.
	If NULL is passed, returns NULL.

mhl/escape.h:	Shell-style string escaping

    * mhl_shell_escape_toesc(char c) 	-> bool

	[MACRO-FUNC] returns true when given char has to be escaped

    * mhl_shell_escape_nottoesc(char c)	-> bool

	[MACRO-FUNC] opposite of mhl_shell_escape_toesc()

    * mhl_shell_escape_dup(const char* s) -> char*

	[INLINE-FUNC] escapes an string and returns the result in a malloc()'ed chunk
	Passing NULL returns an empty malloc()ed string.

    * mhl_shell_unescape_buf(char* s) -> char*

	[INLINE-FUNC] unescapes the string into given buffer (changes buffer!) and 
	returns ptr to the buffer itself. When NULL passed returns NULL.

mhl/env.h:	Environment variable helpers

    * mhl_getenv_dup(const char* n)	-> char*
    
	[MACRO-FUNC] like getenv() but returns an strdup()'ed copy. When NULL passed,
	returns strdup("")