/[guile]/guile/guile-core/doc/ref/data-rep.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/data-rep.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.2.3 by dirk, Fri Mar 1 20:53:03 2002 UTC revision 1.1.2.4 by ossau, Tue Mar 12 20:51:25 2002 UTC
# Line 1077  with @code{SCM} values.  Values are conv Line 1077  with @code{SCM} values.  Values are conv
1077  the @code{SCM} type with utility functions and macros.  the @code{SCM} type with utility functions and macros.
1078    
1079  @item  @item
1080  @code{scm_bits_t} is an integral data type that is guaranteed to be  @code{scm_t_bits} is an integral data type that is guaranteed to be
1081  large enough to hold all information that is required to represent any  large enough to hold all information that is required to represent any
1082  Scheme object.  While this data type is mostly used to implement Guile's  Scheme object.  While this data type is mostly used to implement Guile's
1083  internals, the use of this type is also necessary to write certain kinds  internals, the use of this type is also necessary to write certain kinds
# Line 1085  of extensions to Guile. Line 1085  of extensions to Guile.
1085  @end itemize  @end itemize
1086    
1087  @menu  @menu
1088  * Relationship between SCM and scm_bits_t::  * Relationship between SCM and scm_t_bits::
1089  * Immediate objects::  * Immediate objects::
1090  * Non-immediate objects::  * Non-immediate objects::
1091  * Heap Cell Type Information::  * Heap Cell Type Information::
# Line 1094  of extensions to Guile. Line 1094  of extensions to Guile.
1094  @end menu  @end menu
1095    
1096    
1097  @node Relationship between SCM and scm_bits_t  @node Relationship between SCM and scm_t_bits
1098  @subsubsection Relationship between @code{SCM} and @code{scm_bits_t}  @subsubsection Relationship between @code{SCM} and @code{scm_t_bits}
1099    
1100  A variable of type @code{SCM} is guaranteed to hold a valid Scheme  A variable of type @code{SCM} is guaranteed to hold a valid Scheme
1101  object.  A variable of type @code{scm_bits_t}, on the other hand, may  object.  A variable of type @code{scm_t_bits}, on the other hand, may
1102  hold a representation of a @code{SCM} value as a C integral type, but  hold a representation of a @code{SCM} value as a C integral type, but
1103  may also hold any C value, even if it does not correspond to a valid  may also hold any C value, even if it does not correspond to a valid
1104  Scheme object.  Scheme object.
# Line 1107  For a variable @var{x} of type @code{SCM Line 1107  For a variable @var{x} of type @code{SCM
1107  information is stored in a form that is not directly usable.  To be able  information is stored in a form that is not directly usable.  To be able
1108  to work on the type encoding of the scheme value, the @code{SCM}  to work on the type encoding of the scheme value, the @code{SCM}
1109  variable has to be transformed into the corresponding representation as  variable has to be transformed into the corresponding representation as
1110  a @code{scm_bits_t} variable @var{y} by using the @code{SCM_UNPACK}  a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK}
1111  macro.  Once this has been done, the type of the scheme object @var{x}  macro.  Once this has been done, the type of the scheme object @var{x}
1112  can be derived from the content of the bits of the @code{scm_bits_t}  can be derived from the content of the bits of the @code{scm_t_bits}
1113  value @var{y}, in the way illustrated by the example earlier in this  value @var{y}, in the way illustrated by the example earlier in this
1114  chapter (@pxref{Cheaper Pairs}).  Conversely, a valid bit encoding of a  chapter (@pxref{Cheaper Pairs}).  Conversely, a valid bit encoding of a
1115  Scheme value as a @code{scm_bits_t} variable can be transformed into the  Scheme value as a @code{scm_t_bits} variable can be transformed into the
1116  corresponding @code{SCM} value using the @code{SCM_PACK} macro.  corresponding @code{SCM} value using the @code{SCM_PACK} macro.
1117    
1118  @deftypefn Macro scm_bits_t SCM_UNPACK (SCM @var{x})  @deftypefn Macro scm_t_bits SCM_UNPACK (SCM @var{x})
1119  Transforms the @code{SCM} value @var{x} into its representation as an  Transforms the @code{SCM} value @var{x} into its representation as an
1120  integral type.  Only after applying @code{SCM_UNPACK} it is possible to  integral type.  Only after applying @code{SCM_UNPACK} it is possible to
1121  access the bits and contents of the @code{SCM} value.  access the bits and contents of the @code{SCM} value.
1122  @end deftypefn  @end deftypefn
1123    
1124  @deftypefn Macro SCM SCM_PACK (scm_bits_t @var{x})  @deftypefn Macro SCM SCM_PACK (scm_t_bits @var{x})
1125  Takes a valid integral representation of a Scheme object and transforms  Takes a valid integral representation of a Scheme object and transforms
1126  it into its representation as a @code{SCM} value.  it into its representation as a @code{SCM} value.
1127  @end deftypefn  @end deftypefn
# Line 1153  Given a Scheme object @var{x} of unknown Line 1153  Given a Scheme object @var{x} of unknown
1153  with @code{SCM_IMP (@var{x})} if it is an immediate object.  with @code{SCM_IMP (@var{x})} if it is an immediate object.
1154  @item  @item
1155  If so, all of the type and value information can be determined from the  If so, all of the type and value information can be determined from the
1156  @code{scm_bits_t} value that is delivered by @code{SCM_UNPACK  @code{scm_t_bits} value that is delivered by @code{SCM_UNPACK
1157  (@var{x})}.  (@var{x})}.
1158  @end itemize  @end itemize
1159    
# Line 1180  pointer @var{x}. Line 1180  pointer @var{x}.
1180  @end deftypefn  @end deftypefn
1181    
1182  Note that it is also possible to transform a non-immediate @code{SCM}  Note that it is also possible to transform a non-immediate @code{SCM}
1183  value by using @code{SCM_UNPACK} into a @code{scm_bits_t} variable.  value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable.
1184  However, the result of @code{SCM_UNPACK} may not be used as a pointer to  However, the result of @code{SCM_UNPACK} may not be used as a pointer to
1185  a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a  a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a
1186  @code{SCM} object into a valid pointer to a heap cell.  Also, it is not  @code{SCM} object into a valid pointer to a heap cell.  Also, it is not
# Line 1205  Don't use @code{PTR2SCM} for anything bu Line 1205  Don't use @code{PTR2SCM} for anything bu
1205  @subsubsection Heap Cell Type Information  @subsubsection Heap Cell Type Information
1206    
1207  Heap cells contain a number of entries, each of which is either a scheme  Heap cells contain a number of entries, each of which is either a scheme
1208  object of type @code{SCM} or a raw C value of type @code{scm_bits_t}.  object of type @code{SCM} or a raw C value of type @code{scm_t_bits}.
1209  Which of the cell entries contain Scheme objects and which contain raw C  Which of the cell entries contain Scheme objects and which contain raw C
1210  values is determined by the first entry of the cell, which holds the  values is determined by the first entry of the cell, which holds the
1211  cell type information.  cell type information.
1212    
1213  @deftypefn Macro scm_bits_t SCM_CELL_TYPE (SCM @var{x})  @deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x})
1214  For a non-immediate Scheme object @var{x}, deliver the content of the  For a non-immediate Scheme object @var{x}, deliver the content of the
1215  first entry of the heap cell referenced by @var{x}.  This value holds  first entry of the heap cell referenced by @var{x}.  This value holds
1216  the information about the cell type.  the information about the cell type.
1217  @end deftypefn  @end deftypefn
1218    
1219  @deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_bits_t @var{t})  @deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t})
1220  For a non-immediate Scheme object @var{x}, write the value @var{t} into  For a non-immediate Scheme object @var{x}, write the value @var{t} into
1221  the first entry of the heap cell referenced by @var{x}.  The value  the first entry of the heap cell referenced by @var{x}.  The value
1222  @var{t} must hold a valid cell type.  @var{t} must hold a valid cell type.
# Line 1233  hold Scheme objects and which cell entri Line 1233  hold Scheme objects and which cell entri
1233  the different cell entries appropriately, the following macros are  the different cell entries appropriately, the following macros are
1234  provided.  provided.
1235    
1236  @deftypefn Macro scm_bits_t SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})  @deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
1237  Deliver the cell entry @var{n} of the heap cell referenced by the  Deliver the cell entry @var{n} of the heap cell referenced by the
1238  non-immediate Scheme object @var{x} as raw data.  It is illegal, to  non-immediate Scheme object @var{x} as raw data.  It is illegal, to
1239  access cell entries that hold Scheme objects by using these macros.  For  access cell entries that hold Scheme objects by using these macros.  For
# Line 1268  SCM_CELL_OBJECT_@var{n} (@var{x}) @resul Line 1268  SCM_CELL_OBJECT_@var{n} (@var{x}) @resul
1268  @end itemize  @end itemize
1269  @end deftypefn  @end deftypefn
1270    
1271  @deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_bits_t @var{w})  @deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_t_bits @var{w})
1272  Write the raw C value @var{w} into entry number @var{n} of the heap cell  Write the raw C value @var{w} into entry number @var{n} of the heap cell
1273  referenced by the non-immediate Scheme value @var{x}.  Values that are  referenced by the non-immediate Scheme value @var{x}.  Values that are
1274  written into cells this way may only be read from the cells using the  written into cells this way may only be read from the cells using the
# Line 1432  never @code{equal?} unless they are @cod Line 1432  never @code{equal?} unless they are @cod
1432    
1433  To actually register the new smob type, call @code{scm_make_smob_type}:  To actually register the new smob type, call @code{scm_make_smob_type}:
1434    
1435  @deftypefun scm_bits_t scm_make_smob_type (const char *name, size_t size)  @deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
1436  This function implements the standard way of adding a new smob type,  This function implements the standard way of adding a new smob type,
1437  named @var{name}, with instance size @var{size}, to the system.  The  named @var{name}, with instance size @var{size}, to the system.  The
1438  return value is a tag that is used in creating instances of the type.  return value is a tag that is used in creating instances of the type.
# Line 1451  special function for a given type.  Each Line 1451  special function for a given type.  Each
1451  only zero or one time per type, and the call should be placed  only zero or one time per type, and the call should be placed
1452  immediately following the call to @code{scm_make_smob_type}.  immediately following the call to @code{scm_make_smob_type}.
1453    
1454  @deftypefun void scm_set_smob_mark (scm_bits_t tc, SCM (*mark) (SCM))  @deftypefun void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
1455  This function sets the smob marking procedure for the smob type specified by  This function sets the smob marking procedure for the smob type specified by
1456  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1457  @end deftypefun  @end deftypefun
1458    
1459  @deftypefun void scm_set_smob_free (scm_bits_t tc, size_t (*free) (SCM))  @deftypefun void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM))
1460  This function sets the smob freeing procedure for the smob type specified by  This function sets the smob freeing procedure for the smob type specified by
1461  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1462  @end deftypefun  @end deftypefun
1463    
1464  @deftypefun void scm_set_smob_print (scm_bits_t tc, int (*print) (SCM, SCM, scm_print_state*))  @deftypefun void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, scm_print_state*))
1465  This function sets the smob printing procedure for the smob type specified by  This function sets the smob printing procedure for the smob type specified by
1466  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1467  @end deftypefun  @end deftypefun
1468    
1469  @deftypefun void scm_set_smob_equalp (scm_bits_t tc, SCM (*equalp) (SCM, SCM))  @deftypefun void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
1470  This function sets the smob equality-testing predicate for the smob type specified by  This function sets the smob equality-testing predicate for the smob type specified by
1471  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.  the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1472  @end deftypefun  @end deftypefun
# Line 1500  representing eight-bit gray-scale images Line 1500  representing eight-bit gray-scale images
1500  @example  @example
1501  #include <libguile.h>  #include <libguile.h>
1502    
1503  static scm_bits_t image_tag;  static scm_t_bits image_tag;
1504    
1505  void  void
1506  init_image_type (void)  init_image_type (void)
# Line 1529  or @code{SCM_NEWSMOB3}:@footnote{The @co Line 1529  or @code{SCM_NEWSMOB3}:@footnote{The @co
1529  @code{SCM_NEWSMOB3} variants will allocate double cells and thus use  @code{SCM_NEWSMOB3} variants will allocate double cells and thus use
1530  twice as much memory as smobs created by @code{SCM_NEWSMOB}.}  twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
1531    
1532  @deftypefn Macro void SCM_NEWSMOB(SCM value, scm_bits_t tag, void *data)  @deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
1533  @deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_bits_t tag, void *data1, void *data2)  @deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2)
1534  @deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_bits_t tag, void *data1, void *data2, void *data3)  @deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, void *data2, void *data3)
1535  Make @var{value} contain a smob instance of the type with tag @var{tag}  Make @var{value} contain a smob instance of the type with tag @var{tag}
1536  and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).  and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).
1537  @var{value} must be previously declared as C type @code{SCM}.  @var{value} must be previously declared as C type @code{SCM}.
# Line 1541  Since it is often the case (e.g., in smo Line 1541  Since it is often the case (e.g., in smo
1541  create a smob instance and return it, there is also a slightly specialized  create a smob instance and return it, there is also a slightly specialized
1542  macro for this situation:  macro for this situation:
1543    
1544  @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_bits_t tag, void *data)  @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
1545  @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_bits_t tag, void *data1, void *data2)  @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2)
1546  @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_bits_t tag, void *data1, void *data2, void *data3)  @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3)
1547  This macro expands to a block of code that creates a smob instance of  This macro expands to a block of code that creates a smob instance of
1548  the type with tag @var{tag} and smob data @var{data} (or @var{data1},  the type with tag @var{tag} and smob data @var{data} (or @var{data1},
1549  @var{data2}, and @var{data3}), and returns that @code{SCM} value.  It  @var{data2}, and @var{data3}), and causes the surrounding function to
1550  should be the last piece of code in a block.  return that @code{SCM} value.  It should be the last piece of code in
1551    a block.
1552  @end deftypefn  @end deftypefn
1553    
1554  Guile provides the following functions for managing memory, which are  Guile provides the following functions for managing memory, which are
# Line 1942  Guile shell, extended with the datatypes Line 1943  Guile shell, extended with the datatypes
1943  #include <stdlib.h>  #include <stdlib.h>
1944  #include <libguile.h>  #include <libguile.h>
1945    
1946  static scm_bits_t image_tag;  static scm_t_bits image_tag;
1947    
1948  struct image @{  struct image @{
1949    int width, height;    int width, height;

Legend:
Removed from v.1.1.2.3  
changed lines
  Added in v.1.1.2.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26