mhl/README

   1
   2 Micro helper library.
   3 --
   4
   5 This is a tiny library of helper functions/macros.
   6
   7     * MACRO-FUNC:       macro w/ function syntax. (might become inline func)
   8     * INLINE-FUNC:      inline function (might become macro func)
   9     * MACRO:            strictly a macro (may never become a inline func)
  10
  11 --
  12
  13 mhl/memory.h:   Memory management functions
  14
  15     * mhl_mem_alloc_u(sz)                               [MACRO-FUNC]
  16
  17         Allocate sz bytes on stack, unitialized
  18
  19     * mhl_mem_alloc_z(sz)                               [INLINE-FUNC]
  20
  21         Allocate sz bytes on stack, zero'ed
  22
  23     * mhl_mem_free(ptr)                                 [INLINE-FUNC]
  24
  25         Free chunk @ptr (MUST be allocated w/ mhl_mem_alloc_*()),
  26         passing NULL is graciously allowed
  27
  28     * mhl_mem_realloc(ptr,newsize) -> returns newptr
  29
  30         Re-allocates a heap chunk, just like realloc()
  31
  32     * MHL_PTR_FREE(ptr)                                 [MACRO-ONLY]
  33
  34         like mhl_mem_free(), but with ptr as a variable that gets cleared
  35         (use this as shortcut to "mhl_mem_free(foo); foo = NULL")
  36
  37 mhl/string.h:   String helpers
  38
  39     * mhl_str_dup(const char*s) -> char*
  40
  41         [MACRO-FUNC] Safe version of strdup(), when NULL passed, returns strdup("")
  42
  43     * mhl_str_ndup(const char* s) -> char*
  44
  45         [MACRO-FUNC] Safe version of strndup(), when NULL passed, returns strdup("")
  46
  47     * mhl_str_trim(char* s) -> char*
  48
  49         [INLINE-FUNC] Trims the string (removing leading and trailing whitespacs),
  50         WITHIN the passed buffer, returning the string s itself.
  51         When NULL passed returns NULL.
  52
  53     * mhl_str_toupper(char* s) -> char*
  54
  55         [INLINE-FUNC] Converts the string in passed buffer to uppercase, returns that
  56         buffer. When NULL passed returns NULL.
  57
  58     * mhl_str_concat_1(const char* base, const char* one) -> char*
  59
  60         [INLINE-FUNC] Concatenates the string one onto the string base and returns the
  61         result in a newly allocated buffer (free it w/ mhl_mem_free()).
  62         For NULL strings, "" is assumed.
  63
  64     * mhl_str_concat_2(const char* base,const char* one,const char* two) -> char*
  65       mhl_str_concat_3(const char* base,const char* one,const char* two,const char* three) -> char*
  66       mhl_str_concat_4(const char* base,const char* one,const char* two,const char* three,const char* four) -> char*
  67       mhl_str_concat_5(const char* base,const char* one,const char* two,const char* three,const char* four,const char* five) -> char*
  68       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*
  69       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*
  70
  71         [INLINE-FUNC] Like str_concat_1() but adding more strings.
  72
  73     * mhl_str_reverse(char* str)        -> char*
  74
  75         [INLINE-FUNC] Reverses the string in passed buffer and returns the buffer ptr itself.
  76         If NULL is passed, returns NULL.
  77
  78 mhl/escape.h:   Shell-style string escaping
  79
  80     * mhl_shell_escape_toesc(char c)    -> bool
  81
  82         [MACRO-FUNC] returns true when given char has to be escaped
  83
  84     * mhl_shell_escape_nottoesc(char c) -> bool
  85
  86         [MACRO-FUNC] opposite of mhl_shell_escape_toesc()
  87
  88     * mhl_shell_escape_dup(const char* s) -> char*
  89
  90         [INLINE-FUNC] escapes an string and returns the result in a malloc()'ed chunk
  91         Passing NULL returns an empty malloc()ed string.
  92
  93     * mhl_shell_unescape_buf(char* s) -> char*
  94
  95         [INLINE-FUNC] unescapes the string into given buffer (changes buffer!) and
  96         returns ptr to the buffer itself. When NULL passed returns NULL.
  97
  98 mhl/env.h:      Environment variable helpers
  99
 100     * mhl_getenv_dup(const char* n)     -> char*
 101
 102         [MACRO-FUNC] like getenv() but returns an strdup()'ed copy. When NULL passed,
 103         returns strdup("")