12.3.34 SP_get_integer_bytes()

Synopsis

#include <sicstus/sicstus.h>

int
SP_get_integer_bytes(SP_term_ref term,
                     void *buf,
                     size_t *pbuf_size,
                     int native);

Extracts from term an an arbitrarily sized integer.

Arguments

term

The SP_term_ref holding the integer

buf

The buffer receiving the integer

pbuf_size

Should point at the size of buf

native

See the description below

Return Value

Zero if the conversion fails (as far as failure can be detected), and a nonzero value otherwise.

Description

In the following, assume that the integer referred to by term requires a minimum of size bytes to store (in twos-complement representation).

1. If term does not refer to a Prolog integer, zero is returned and the other arguments are ignored.
2. If *pbuf_size is less than size, then *pbuf_size is updated to size and zero is returned. The fact that *pbuf_size has changed can be used to distinguish insufficient buffer size from other possible errors. By calling SP_get_integer_bytes() with *pbuf_size set to zero, you can determine the buffer size needed; in this case, buf is ignored.
3. *pbuf_size is set to size.
4. If native is zero, buf is filled with the twos complement representation of the integer, with the least significant bytes stored at lower indices in buf. Note that all of buf is filled, even though only size bytes was needed.
5. If native is non-zero, buf is assumed to point at a native *pbuf_size byte integral type. On most platforms, native integer sizes of two (16-bit), four (32 bit) and eight (64 bytes) bytes are supported. Note that *pbuf_size == 1, which would correspond to signed char, is not supported with native.
6. If an unsupported size is used with native, zero is returned.

Examples

The following example gets a Prolog integer into a (presumably 64 bit) long long C integer.

{
  long long x; // C99, GCC supports this
  size_t sz = sizeof x;
  if (!SP_get_integer_bytes(tr, &x, &sz, 1)) // 1 for native
    .. error handling ..
  .. use x .. // sz may have decreased
}

See Also

Accessing Prolog Terms.