/*
   "kernel_string_pool.h"

   created by: grayspace aka J. Leveille
   for: UbixOS Project
   date: May 11, 2002

   purpose: to provide a mechanism for maintaining a pool of strings
            for use by the kernel without unnecessary waste of memory

   NOTEs:
      - for now only ASCII is supported
      - done quickly, pretty hacky

   TODO:
      - expand to support unicode
      - use huffman encoding instead

   $Id$
*/

#ifndef _KERNEL_STRING_POOL_H
#define _KERNEL_STRING_POOL_H

/* memory FORMAT of a 'KRNSTR': (quick and dirty for now)
   
   an 'ID' is used to indicate a string within the pool
   ----------------------------------------------------

   'ID' - [DWORD]:
            -  BYTE offset inside pool where the 'KRNSTR'
               (kernel string) is stored

   'KRNSTR's (kernel strings) are specified as an array of continuous BYTEs
   ------------------------------------------------------------------------

   'KRNSTR':
      - 'num-bytes' - [BYTE] 
         - total number of bytes in kernel string
      - [KRNWORD] x ???
         - 'KRNWORD's follow for 'num-bytes' bytes

   'KRNWORD':
      - [BYTE] 'key1'

      - if key1 == [0,63]:
         - key1 is the index of the 'sub-string' in the pool

      - otherwise
         - if key1 has bit 7 set
            - [BYTE] 'key2'
            - [BYTE] 'key3'
            - the index of the 'sub-string' in the pool is:
                                          (key1&0x7F) * 65536
                                          + key2 * 256
                                          + key3
            - (index is in [16384,(2^23-1)]

         - otherwise
            - [BYTE] 'key2'
            - the index of the 'sub-string' in the pool is:
                                          (key1&0x3F) * 256
                                          + key2
            - (index is in [64,16383])

      - NOTE: the reason for using only extra 8-bit keys
      is in case we port to platform with data alignment exceptions
      and this stuff is left dormant and never changed

   - NOTE: a 'space' (0x20) is implied between each 'KRNWORD', therefore
   it is not currently possible to break encode string AB into substrings
   A & B if AB does not contain any spaces

   - a 'sub-string' is found by using the the index of the
   'sub-string' and scanning through the whole
   substring pool (a little slow)
   (lookup table was ditched to save memory)

   'sub-string's are specified as an array of continuous BYTEs
   -----------------------------------------------------------

   - a 'sub-string' is as follows:

      - [BYTE] 'numchars' [0,255] -> [1,256]
      - [BYTE] x 'numchars' (the chars themselves)
   
   - WARNING: empty 'sub-string's are not allowed

*/

/* WARNING: it is *assumed* any 'ID' given to a kernel
            string pool function will be valid!!         */

/* structure for kernel string pool */
typedef struct tagKSTR_POOL
{
   /* pointer to where the kernel strings are stored */
   const BYTEg * p_krnstrs;

   /* pointer to where the sub strings are stored */
   const BYTEg * p_substrs;
}
KSTR_POOL;

/* the reason for this structure format is so that a tool
   can be written which can generate a 'KSTR_POOL' from a configuration
   file and place it into a 'C' source and header file pair as static data */

// gets the substring indicated by 'id' from the pool 'p_ksp' into 'p_dst'
// - returns pointer to 'p_dst'
char * KSTR_POOL_GetString( KSTR_POOL * p_ksp, char * p_dst, DWORDg id );

#endif /* _KERNEL_STRING_POOL_H */