home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 February / PCWK0296.iso / sharewar / dos / program / gs300sr1 / gs300sr1.exe / IDICT.H < prev    next >
C/C++ Source or Header  |  1994-07-27  |  5KB  |  133 lines
  1. /* Copyright (C) 1989, 1992, 1993, 1994 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17. */
  18.  
  19. /* idict.h */
  20. /* Interfaces for Ghostscript dictionary package */
  21.  
  22. /*
  23.  * Contrary to our usual practice, we expose the (first-level)
  24.  * representation of a dictionary in the interface file,
  25.  * because it is so important that access checking go fast.
  26.  * The access attributes for the dictionary are stored in
  27.  * the values ref.
  28.  */
  29. struct dict_s {
  30.     ref values;        /* t_array, values */
  31.     ref keys;        /* t_shortarray or t_array, keys */
  32.     ref count;        /* t_integer, count of occupied entries */
  33.                 /* (length) */
  34.     ref maxlength;        /* t_integer, maxlength as seen by client. */
  35. };
  36.  
  37. /* Define the maximum size of a dictionary. */
  38. extern const uint dict_max_size;
  39.  
  40. /*
  41.  * Define whether dictionaries expand automatically when full.  Note that
  42.  * if dict_auto_expand is true, dict_put, dict_copy, dict_resize, and
  43.  * dict_grow cannot return e_dictfull; however, they can return e_VMerror.
  44.  * (dict_find can return e_dictfull even if dict_auto_expand is true.)
  45.  */
  46. extern bool dict_auto_expand;
  47.  
  48. /* Create a dictionary. */
  49. int    dict_create(P2(uint maxlength, ref *pdref));
  50.  
  51. /* Return a pointer to a ref that holds the access attributes */
  52. /* for a dictionary. */
  53. #define dict_access_ref(pdref) (&(pdref)->value.pdict->values)
  54. #define check_dict_read(dref) check_read(*dict_access_ref(&dref))
  55. #define check_dict_write(dref) check_write(*dict_access_ref(&dref))
  56.  
  57. /*
  58.  * Look up a key in a dictionary.  Store a pointer to the value slot
  59.  * where found, or to the (value) slot for inserting.
  60.  * Return 1 if found, 0 if not and there is room for a new entry,
  61.  * or e_dictfull if the dictionary is full and the key is missing.
  62.  * The caller is responsible for ensuring that key is not a null.
  63.  */
  64. int    dict_find(P3(const ref *pdref, const ref *key, ref **ppvalue));
  65.  
  66. /*
  67.  * Look up a (constant) C string in a dictionary.
  68.  * Return 1 if found, <= 0 if not.
  69.  */
  70. int    dict_find_string(P3(const ref *pdref, const char _ds *kstr,
  71.                 ref **ppvalue));
  72.  
  73. /*
  74.  * Enter a key-value pair in a dictionary.
  75.  * Return 1 if this was a new entry, 0 if this replaced an existing entry,
  76.  * e_dictfull, e_invalidaccess, or e_VMerror if the key was a string
  77.  * and a VMerror occurred when converting it to a name.
  78.  */
  79. int    dict_put(P3(ref *pdref, const ref *key, const ref *pvalue));
  80.  
  81. /*
  82.  * Enter a key-value pair where the key is a (constant) C string.
  83.  */
  84. int    dict_put_string(P3(ref *pdref, const char *kstr, const ref *pvalue));
  85.  
  86. /* Remove a key-value pair from a dictionary. */
  87. /* Return 0 or e_undefined. */
  88. int    dict_undef(P2(ref *pdref, const ref *key));
  89.  
  90. /* Return the number of elements in a dictionary. */
  91. uint    dict_length(P1(const ref *pdref));
  92.  
  93. /* Return the capacity of a dictionary. */
  94. uint    dict_maxlength(P1(const ref *pdref));
  95.  
  96. /* Copy one dictionary into another. */
  97. /* Return 0 or e_dictfull. */
  98. int    dict_copy(P2(const ref *dfrom, ref *dto));
  99.  
  100. /* Grow or shrink a dictionary. */
  101. /* Return 0, e_dictfull, or e_VMerror. */
  102. int    dict_resize(P2(ref *pdref, uint newmaxlength));
  103.  
  104. /* Grow a dictionary in the same way as dict_put does. */
  105. /* We export this for some special-case code in zop_def. */
  106. int    dict_grow(P1(ref *pdref));
  107.  
  108. /* Ensure that a dictionary uses the unpacked representation for keys. */
  109. /* (This is of no interest to ordinary clients.) */
  110. int    dict_unpack(P1(ref *pdref));
  111.  
  112. /* Prepare to enumerate a dictionary. */
  113. /* Return an integer suitable for the first call to dict_next. */
  114. int    dict_first(P1(const ref *pdref));
  115.  
  116. /* Enumerate the next element of a dictionary. */
  117. /* index is initially the result of a call on dict_first. */
  118. /* Either store a key and value at eltp[0] and eltp[1] */
  119. /* and return an updated index, or return -1 */
  120. /* to signal that there are no more elements in the dictionary. */
  121. int    dict_next(P3(const ref *pdref, int index, ref *eltp));
  122.  
  123. /* Given a value pointer return by dict_find, return an index that */
  124. /* identifies the entry within the dictionary. (This may, but need not, */
  125. /* be the same as the index returned by dict_next.) */
  126. /* The index is in the range [0..maxlength-1]. */
  127. int    dict_value_index(P2(const ref *pdref, const ref *pvalue));
  128.  
  129. /* Given an index in [0..maxlength-1], as returned by dict_value_index, */
  130. /* return the key and value, as returned by dict_next. */
  131. /* If the index designates an unoccupied entry, return e_undefined. */
  132. int    dict_index_entry(P3(const ref *pdref, int index, ref *eltp));
  133.