Memory allocation
=================

The libjit library provides an interface to the traditional system malloc routines.  All heap allocation in libjit goes through these functions.  If you need to perform some other kind of memory allocation, you can replace these functions with your own versions.

 -- Function: void * jit_malloc (unsigned int SIZE)
     Allocate SIZE bytes of memory from the heap.

 -- Function: type * jit_new (TYPE)
     Allocate sizeof(TYPE) bytes of memory from the heap and cast the return pointer to TYPE *.  This is a macro that wraps up the underlying jit_malloc function and is less error-prone when allocating structures.

 -- Function: void * jit_calloc (unsigned int NUM, unsigned int SIZE)
     Allocate NUM * SIZE bytes of memory from the heap and clear them to zero.

 -- Function: type * jit_cnew (TYPE)
     Allocate sizeof(TYPE) bytes of memory from the heap and cast the return pointer to TYPE *.  The memory is cleared to zero.

 -- Function: void * jit_realloc (void *PTR, unsigned int SIZE)
     Re-allocate the memory at PTR to be SIZE bytes in size. The memory block at PTR must have been allocated by a previous call to jit_malloc, jit_calloc, or jit_realloc.

 -- Function: void jit_free (void *PTR)
     Free the memory at PTR.  It is safe to pass a NULL pointer.

Memory set, copy, compare, etc
==============================

The following functions are provided to set, copy, compare, and search memory blocks.

 -- Function: void * jit_memset (void *DEST, int CH, unsigned int LEN)
     Set the LEN bytes at DEST to the value CH. Returns DEST.

 -- Function: void * jit_memcpy (void *DEST, const void *SRC, unsigned int LEN)
     Copy the LEN bytes at SRC to DEST.  Returns DEST.  The behavior is undefined if the blocks overlap (use JIT_MEMMOVE instead for that case).

 -- Function: void * jit_memmove (void *DEST, const void *SRC, unsigned int LEN)
     Copy the LEN bytes at SRC to DEST and handle overlapping blocks correctly.  Returns DEST.

 -- Function: int jit_memcmp (const void *S1, const void *S2, unsigned int LEN)
     Compare LEN bytes at S1 and S2, returning a negative, zero, or positive result depending upon their relationship.  It is system-specific as to whether this function uses signed or unsigned byte comparisons.

 -- Function: void * jit_memchr (void *STR, int CH, unsigned int LEN)
     Search the LEN bytes at STR for the first instance of the value CH.  Returns the location of CH if it was found, or NULL if it was not found.

String operations
=================

The following functions are provided to manipulate NULL-terminated strings.  It is highly recommended that you use these functions in preference to system functions, because the corresponding system functions are extremely non-portable.

 -- Function: unsigned int jit_strlen (const char *STR)
     Returns the length of STR.

 -- Function: char * jit_strcpy (char *DEST, const char *SRC)
     Copy the string at SRC to DEST.  Returns DEST.

 -- Function: char * jit_strcat (char *DEST, const char *SRC)
     Copy the string at SRC to the end of the string at DEST. Returns DEST.

 -- Function: char * jit_strncpy (char *DEST, const char *SRC, unsigned int LEN)
     Copy at most LEN characters from the string at SRC to DEST.  Returns DEST.

 -- Function: char * jit_strdup (const char *STR)
     Allocate a block of memory using jit_malloc and copy STR into it.  Returns NULL if STR is NULL or there is insufficient memory to perform the jit_malloc operation.

 -- Function: char * jit_strndup (const char *STR, unsigned int LEN)
     Allocate a block of memory using jit_malloc and copy at most LEN characters of STR into it.  The copied string is then NULL-terminated.  Returns NULL if STR is NULL or there is insufficient memory to perform the jit_malloc operation.

 -- Function: int jit_strcmp (const char *STR1, const char *STR2)
     Compare the two strings STR1 and STR2, returning a negative, zero, or positive value depending upon their relationship.

 -- Function: int jit_strncmp (const char *STR1, const char *STR2, unsigned int LEN)
     Compare the two strings STR1 and STR2, returning a negative, zero, or positive value depending upon their relationship. At most LEN characters are compared.

 -- Function: int jit_stricmp (const char *STR1, const char *STR2)
     Compare the two strings STR1 and STR2, returning a negative, zero, or positive value depending upon their relationship. Instances of the English letters A to Z are converted into their lower case counterparts before comparison.

     Note: this function is guaranteed to use English case comparison rules, no matter what the current locale is set to, making it suitable for comparing token tags and simple programming language identifiers.

     Locale-sensitive string comparison is complicated and usually specific to the front end language or its supporting runtime library.  We deliberately chose not to handle this in libjit.

 -- Function: int jit_strnicmp (const char *STR1, const char *STR2, unsigned int LEN)
     Compare the two strings STR1 and STR2, returning a negative, zero, or positive value depending upon their relationship. At most LEN characters are compared.  Instances of the English letters A to Z are converted into their lower case counterparts before comparison.

 -- Function: char * jit_strchr (const char *STR, int CH)
     Search STR for the first occurrence of CH.  Returns the address where CH was found, or NULL if not found.

 -- Function: char * jit_strrchr (const char *STR, int CH)
     Search STR for the first occurrence of CH, starting at the end of the string.  Returns the address where CH was found, or NULL if not found.