* scheme-data.texi (Integers): Added docs for the new scm_is_,

scm_to_ and scm_from_ functions for integers.

diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi
index ef57898..3cf12e9 100755 (executable)
--- 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