▼Inside: Racket C API
  top  ← prev  up  next → 

18 Miscellaneous Utilities

The MZSCHEME_VERSION preprocessor macro is defined as a string describing the version of Racket. The MZSCHEME_VERSION_MAJOR and MZSCHEME_VERSION_MINOR macros are defined as the major and minor version numbers, respectively.

int

 

scheme_eq

(

Scheme_Object* obj1,

 

 

 

 

Scheme_Object* obj2)

Returns 1 if the Scheme values are eq?.

int

 

scheme_eqv

(

Scheme_Object* obj1,

 

 

 

 

Scheme_Object* obj2)

Returns 1 if the Scheme values are eqv?.

int

 

scheme_equal

(

Scheme_Object* obj1,

 

 

 

 

Scheme_Object* obj2)

Returns 1 if the Scheme values are equal?.

int

 

scheme_recur_equal

(

Scheme_Object* obj1,

 

 

 

 

Scheme_Object* obj2,

 

 

 

 

void* cycle_data)

Like scheme_equal, but accepts an extra value for cycle tracking. This procedure is meant to be called by a procedure installed with scheme_set_type_equality.

Returns 1 if the Racket values are equal?.}

intptr_t

 

scheme_equal_hash_key

(

Scheme_Object* obj)

Returns the primary equal?-hash key for obj.

intptr_t

 

scheme_equal_hash_key2

(

Scheme_Object* obj)

Returns the secondary equal?-hash key for obj.

intptr_t

 

scheme_recur_equal_hash_key

(

Scheme_Object* obj,

 

 

 

 

void* cycle_data)

Like scheme_equal_hash_key, but accepts an extra value for cycle tracking. This procedure is meant to be called by a hashing procedure installed with scheme_set_type_equality.

Returns the primary equal?-hash key for obj.}

intptr_t

 

scheme_recur_equal_hash_key2

(

Scheme_Object* obj,

 

 

 

 

void* cycle_data)

Like scheme_equal_hash_key2, but accepts an extra value for cycle tracking. This procedure is meant to be called by a secondary hashing procedure installed with scheme_set_type_equality.

Scheme_Object*

 

scheme_build_list

(

int c,

 

 

 

 

Scheme_Object** elems)

Creates and returns a list of length c with the elements elems.

int

 

scheme_list_length

(

Scheme_Object* list)

Returns the length of the list. If list is not a proper list, then the last cdr counts as an item. If there is a cycle in list (involving only cdrs), this procedure will not terminate.

int

 

scheme_proper_list_length

(

Scheme_Object* list)

Returns the length of the list, or -1 if it is not a proper list. If there is a cycle in list (involving only cdrs), this procedure returns -1.

Scheme_Object*

 

scheme_car

(

Scheme_Object* pair)

Returns the car of the pair.

Scheme_Object*

 

scheme_cdr

(

Scheme_Object* pair)

Returns the cdr of the pair.

Scheme_Object*

 

scheme_cadr

(

Scheme_Object* pair)

Returns the cadr of the pair.

Scheme_Object*

 

scheme_caddr

(

Scheme_Object* pair)

Returns the caddr of the pair.

Scheme_Object*

 

scheme_vector_to_list

(

Scheme_Object* vec)

Creates a list with the same elements as the given vector.

Scheme_Object*

 

scheme_list_to_vector

(

Scheme_Object* list)

Creates a vector with the same elements as the given list.

Scheme_Object*

 

scheme_append

(

Scheme_Object* lstx,

 

 

 

 

Scheme_Object* lsty)

Non-destructively appends the given lists.

Scheme_Object*

 

scheme_unbox

(

Scheme_Object* obj)

Returns the contents of the given box.

void

 

scheme_set_box

(

Scheme_Object* b,

 

 

 

 

Scheme_Object* v)

Sets the contents of the given box.

Scheme_Object*

 

scheme_dynamic_require

(

int argc,

 

 

 

 

Scheme_Object** argv)

The same as dynamic-require. The argc argument must be 2, and argv contains the arguments.

Scheme_Object*

scheme_namespace_require

(

Scheme_Object* prim_req_spec)

The same as namespace-require.

Scheme_Object*

 

scheme_load

(

char* file)

Loads the specified Racket file, returning the value of the last expression loaded, or NULL if the load fails.

Scheme_Object*

 

scheme_load_extension

(

char* filename)

Loads the specified Racket extension file, returning the value provided by the extension’s initialization function.

Scheme_Hash_Table*

 

scheme_make_hash_table

(

int type)

Creates a hash table. The type argument must be either SCHEME_hash_ptr or SCHEME_hash_string, which determines how keys are compared (unless the hash and compare functions are modified in the hash table record; see below). A SCHEME_hash_ptr table hashes on a key’s pointer address, while SCHEME_hash_string uses a key as a char* and hashes on the null-terminated string content. Since a hash table created with SCHEME_hash_string (instead of SCHEME_hash_ptr) does not use a key as a Racket value, it cannot be used from Racket code.

Although the hash table interface uses the type Scheme_Object* for both keys and values, the table functions never inspect values, and they inspect keys only for SCHEME_hash_string hashing. Thus, the actual types of the values (and keys, for SCHEME_hash_ptr tables) can be anything.

The public portion of the Scheme_Hash_Table type is defined roughly as follows:

  typedef struct Scheme_Hash_Table {

    Scheme_Object so; /* so.type == scheme_hash_table_type */

    /* ... */

    int size;  /* size of keys and vals arrays */

    int count; /* number of mapped keys */

    Scheme_Object **keys;

    Scheme_Object **vals;

    void (*make_hash_indices)(void *v, intptr_t *h1, intptr_t *h2);

    int (*compare)(void *v1, void *v2);

    /* ... */

  } Scheme_Hash_Table;

The make_hash_indices and compare function pointers can be set to arbitrary hashing and comparison functions (before any mapping is installed into the table). A hash function should fill h1 with a primary hash value and h2 with a secondary hash value; the values are for double-hashing, where the caller takes appropriate modulos. Either h1 or h2 can be NULL if the corresponding hash code is not needed.

To traverse the hash table content, iterate over keys and vals in parallel from 0 to size-1, and ignore keys where the corresponding vals entry is NULL. The count field indicates the number of non-NULL values that will be encountered.

Scheme_Hash_Table*

 

scheme_make_hash_table_equal

(

)

Like scheme_make_hash_table, except that keys are treated as Racket values and hashed based on equal? instead of eq?.

void

 

scheme_hash_set

(

Scheme_Hash_Table* table,

 

 

 

 

Scheme_Object* key,

 

 

 

 

Scheme_Object* val)

Sets the current value for key in table to val. If val is NULL, the key is unmapped in table.

Scheme_Object*

 

scheme_hash_get

(

Scheme_Hash_Table* table,

 

 

 

 

Scheme_Object* key)

Returns the current value for key in table, or NULL if key has no value.

Scheme_Bucket_Table*

 

scheme_make_bucket_table

(

int size_hint,

 

 

 

 

int type)

Like make_hash_table, but bucket tables are somewhat more flexible, in that hash buckets are accessible and weak keys are supported. (They also consume more space than hash tables.)

The type argument must be either SCHEME_hash_ptr, SCHEME_hash_string, or SCHEME_hash_weak_ptr. The first two are the same as for hash tables. The last is like SCHEME_hash_ptr, but the keys are weakly held.

The public portion of the Scheme_Bucket_Table type is defined roughly as follows:

  typedef struct Scheme_Bucket_Table {

    Scheme_Object so; /* so.type == scheme_variable_type */

    /* ... */

    int size;  /* size of buckets array */

    int count; /* number of buckets, >= number of mapped keys */

    Scheme_Bucket **buckets;

    void (*make_hash_indices)(void *v, intptr_t *h1, intptr_t *h2);

    int (*compare)(void *v1, void *v2);

    /* ... */

  } Scheme_Bucket_Table;

The make_hash_indices and compare functions are used as for hash tables. Note that SCHEME_hash_weak_ptr supplied as the initial type makes keys weak even if the hash and comparison functions are changed.

See scheme_bucket_from_table for information on buckets.

void

 

scheme_add_to_table

(

Scheme_Bucket_Table* table,

 

 

 

 

const char* key,

 

 

 

 

void* val,

 

 

 

 

int const)

Sets the current value for key in table to val. If const is non-zero, the value for key must never be changed.

void

 

scheme_change_in_table

(

Scheme_Bucket_Table* table,

 

 

 

 

const char* key,

 

 

 

 

void* val)

Sets the current value for key in table to val, but only if key is already mapped in the table.

void*

 

scheme_lookup_in_table

(

Scheme_Bucket_Table* table,

 

 

 

 

const char* key)

Returns the current value for key in table, or NULL if key has no value.

Scheme_Bucket*

scheme_bucket_from_table

(

Scheme_Bucket_Table* table,

 

 

const char* key)

Returns the bucket for key in table. The Scheme_Bucket structure is defined as:

  typedef struct Scheme_Bucket {

    Scheme_Object so; /* so.type == scheme_bucket_type */

    /* ... */

    void *key;

    void *val;

  } Scheme_Bucket;

Setting val to NULL unmaps the bucket’s key, and key can be NULL in that case as well. If the table holds keys weakly, then key points to a (weak) pointer to the actual key, and the weak pointer’s value can be NULL.

intptr_t

 

scheme_double_to_int

(

char* where,

 

 

 

 

double d)

Returns a fixnum value for the given floating-point number d. If d is not an integer or if it is too large, then an error message is reported; name is used for error-reporting.

intptr_t

 

scheme_get_milliseconds

(

)

Returns the current “time” in milliseconds, just like current-milliseconds.

intptr_t

 

scheme_get_process_milliseconds

(

)

Returns the current process “time” in milliseconds, just like current-process-milliseconds.

char*

 

scheme_banner

(

)

Returns the string that is used as the Racket startup banner.

char*

 

scheme_version

(

)

Returns a string for the executing version of Racket.

Scheme_Hash_Table*

 

scheme_get_place_table

(

)

Returns an eq?-based hash table that is global to the current place.

A key generated by scheme_malloc_key can be useful as a common key across multiple places.

Scheme_Object*

 

scheme_malloc_key

(

)

Generates an uncollectable Racket value that can be used across places. Free the value with scheme_free_key.

void

 

scheme_free_key

(

Scheme_Object* key)

Frees a key allocated with scheme_malloc_key. When a key is freed, it must not be accessible from any GC-travsered reference in any place.

void*

 

scheme_register_process_global

(

const char* key,

 

 

 

 

void* val)

Gets or sets a value in a process-global table (i.e., shared across multiple places, if any). If val is NULL, the current mapping for key is given, otherwise val is installed as the value for key and NULL is returned. The given val must not refer to garbage-collected memory.

This function is intended for infrequent use with a small number of keys.

  top  ← prev  up  next →