From 4e2b1f342dadacbefb752c28b60ed089bbe8d8cc Mon Sep 17 00:00:00 2001 From: Marius Vollmer Date: Wed, 7 Jul 2004 15:39:21 +0000 Subject: [PATCH] * scheme-data.texi (Integers): Added docs for the new scm_is_, scm_to_ and scm_from_ functions for integers. --- doc/ref/scheme-data.texi | 123 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi index ef5789877..3cf12e953 100755 --- a/doc/ref/scheme-data.texi +++ b/doc/ref/scheme-data.texi @@ -304,8 +304,17 @@ The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be inexact integers. They are explained in detail in the next section, together with reals and rationals. -@c REFFIXME Maybe point here to discussion of handling immediates/bignums -@c on the C level, where the conversion is not so automatic - NJ +C has a host of different integer types, and Guile offers a host of +functions to convert between them and the @code{SCM} representation. +For example, a C @code{int} can be handled with @code{scm_to_int} and +@code{scm_from_int}. Guile also defines a few C integer types of its +own, to help with differences between systems. + + C integer types that are not covered can be +handled with the generic @code{scm_to_signed_integer} and +@code{scm_from_signed_integer} for signed types, or with +@code{scm_to_unsigned_integer} and @code{scm_from_unsigned_integer} +for unsigned types. @deffn {Scheme Procedure} integer? x @deffnx {C Function} scm_integer_p (x) @@ -323,6 +332,116 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}. @end lisp @end deffn +@deftypefn {C Function} int scm_is_integer (SCM x) +This is equivalent to @code{scm_is_true (scm_integer_p (x))}. +@end deftypefn + +@defvr {C Type} scm_t_int8 +@defvrx {C Type} scm_t_uint8 +@defvrx {C Type} scm_t_int16 +@defvrx {C Type} scm_t_uint16 +@defvrx {C Type} scm_t_int32 +@defvrx {C Type} scm_t_uint32 +@defvrx {C Type} scm_t_int64 +@defvrx {C Type} scm_t_uint64 +@defvrx {C Type} scm_t_intmax +@defvrx {C Type} scm_t_uintmax +The C types are equivalent to the corresponding ISO C types but are +defined on all platforms, with the exception of @code{scm_t_int64} and +@code{scm_t_uint64}, which are only defined when a 64-bit type is +available. For example, @code{scm_t_int8} is equivalent to +@code{int8_t}. + +You can regard these definitions as a stop-gap measure until all +platforms provide these types. If you know that all the platforms +that you are interested in already provide these types, it is better +to use them directly instead of the types provided by Guile. +@end defvr + +@deftypefn {C Function} int scm_is_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max) +@deftypefnx {C Function} int scm_is_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max) +Return @code{1} when @var{x} represents an integer that is between +@var{min} and @var{max}, inclusive. + +These functions can be used to check whether a @code{SCM} value will +fit into a given range, such as the range of a given C integer type. +If you just want to convert a @code{SCM} value to a given C integer +type, use one of the conversion functions directly. +@end deftypefn + +@deftypefn {C Function} scm_t_intmax scm_to_signed_integer (SCM x, scm_t_intmax min, scm_t_intmax max) +@deftypefnx {C Function} scm_t_uintmax scm_to_unsigned_integer (SCM x, scm_t_uintmax min, scm_t_uintmax max) +When @var{x} represents an integer that is between @var{min} and +@var{max} inclusive, return that integer. Else signal an error, +either a `wrong-type' error when @var{x} is not an integer, or an +`out-of-range' error when it doesn't fit the given range. +@end deftypefn + +@deftypefn {C Function} SCM scm_from_signed_integer (scm_t_intmax x) +@deftypefnx {C Function} SCM scm_from_unsigned_integer (scm_t_uintmax x) +Return the @code{SCM} value that represents the integer @var{x}. +This function will always succeed. +@end deftypefn + +@deftypefn {C Function} char scm_to_char (SCM x) +@deftypefnx {C Function} {signed char} scm_to_schar (SCM x) +@deftypefnx {C Function} {unsigned char} scm_to_uchar (SCM x) +@deftypefnx {C Function} short scm_to_short (SCM x) +@deftypefnx {C Function} {unsigned short} scm_to_ushort (SCM x) +@deftypefnx {C Function} int scm_to_int (SCM x) +@deftypefnx {C Function} {unsigned int} scm_to_uint (SCM x) +@deftypefnx {C Function} long scm_to_long (SCM x) +@deftypefnx {C Function} {unsigned long} scm_to_ulong (SCM x) +@deftypefnx {C Function} long long scm_to_long_long (SCM x) +@deftypefnx {C Function} {unsigned long long} scm_to_ulong_long (SCM x) +@deftypefnx {C Function} size_t scm_to_size_t (SCM x) +@deftypefnx {C Function} ssize_t scm_to_ssize_t (SCM x) +@deftypefnx {C Function} scm_t_int8 scm_to_int8 (SCM x) +@deftypefnx {C Function} scm_t_uint8 scm_to_uint8 (SCM x) +@deftypefnx {C Function} scm_t_int16 scm_to_int16 (SCM x) +@deftypefnx {C Function} scm_t_uint16 scm_to_uint16 (SCM x) +@deftypefnx {C Function} scm_t_int32 scm_to_int32 (SCM x) +@deftypefnx {C Function} scm_t_uint32 scm_to_uint32 (SCM x) +@deftypefnx {C Function} scm_t_int64 scm_to_int64 (SCM x) +@deftypefnx {C Function} scm_t_uint64 scm_to_uint64 (SCM x) +@deftypefnx {C Function} scm_t_intmax scm_to_intmax (SCM x) +@deftypefnx {C Function} scm_t_uintmax scm_to_uintmax (SCM x) +When @var{x} represents an integer that fits into the indicated C +type, return that integer. Else signal an error, either a +`wrong-type' error when @var{x} is not an integer, or an +`out-of-range' error when it doesn't fit the given range. + +The functions @code{scm_to_long_long}, @code{scm_to_ulong_long}, +@code{scm_to_int64}, and @code{scm_to_uint64} are only available when +the corresponding types are. +@end deftypefn + +@deftypefn {C Function} SCM scm_from_char (char x) +@deftypefnx {C Function} SCM scm_from_schar (signed char x) +@deftypefnx {C Function} SCM scm_from_uchar (unsigned char x) +@deftypefnx {C Function} SCM scm_from_short (short x) +@deftypefnx {C Function} SCM scm_from_ushort (unsigned short x) +@deftypefnx {C Function} SCM scm_from_int (int x) +@deftypefnx {C Function} SCM scm_from_uint (unsigned int x) +@deftypefnx {C Function} SCM scm_from_long (long x) +@deftypefnx {C Function} SCM scm_from_ulong (unsigned long x) +@deftypefnx {C Function} SCM scm_from_long_long (long long x) +@deftypefnx {C Function} SCM scm_from_ulong_long (unsigned long long x) +@deftypefnx {C Function} SCM scm_from_size_t (size_t x) +@deftypefnx {C Function} SCM scm_from_ssize_t (ssize_t x) +@deftypefnx {C Function} SCM scm_from_int8 (scm_t_int8 x) +@deftypefnx {C Function} SCM scm_from_uint8 (scm_t_uint8 x) +@deftypefnx {C Function} SCM scm_from_int16 (scm_t_int16 x) +@deftypefnx {C Function} SCM scm_from_uint16 (scm_t_uint16 x) +@deftypefnx {C Function} SCM scm_from_int32 (scm_t_int32 x) +@deftypefnx {C Function} SCM scm_from_uint32 (scm_t_uint32 x) +@deftypefnx {C Function} SCM scm_from_int64 (scm_t_int64 x) +@deftypefnx {C Function} SCM scm_from_uint64 (scm_t_uint64 x) +@deftypefnx {C Function} SCM scm_from_intmax (scm_t_intmax x) +@deftypefnx {C Function} SCM scm_from_uintmax (scm_t_uintmax x) +Return the @code{SCM} value that represents the integer @var{x}. +These functions will always succeed. +@end deftypefn @node Reals and Rationals @subsubsection Real and Rational Numbers -- 2.20.1