Seed7 FAQ Manual Demo Screenshots Examples Libraries Algorithms Benchmarks Index Download GitHub Build Seed7 Links
Manual Introduction Tutorial Declarations Statements Types Parameters Objects File I/O Syntax Tokens Expressions OS access Database Graphic Actions Foreign funcs Errors
Foreign funcs C types Conversions OS + Path Parameters Create results Memory Basic functions Error handling
Manual
Foreign funcs
 previous   up   next 

16. FOREIGN FUNCTION INTERFACE

Foreign functions cannot be called directly. It is necessary to write wrapper functions. Several things must be done to call a foreign function:

In general two functions are needed: A wrapper function and an action function. The corresponding function definitions can be placed in two *.c files. Corresponding *.h files contain prototypes. Assume, we have the library "superlib" and the function doWurx1 from "superlib" should be called from a Seed7 program. The three letter abbreviation sup is used to determine the file and function names for wrapper and action. The following files and functions are used:

File Function Comment
superlib.a doWurx1 External library (the extension may vary)
superlib.h doWurx1 Prototype of the external C function
sup_rtl.c supDoWurx1 Wrapper function
sup_rtl.h supDoWurx1 Prototype of the wrapper function
suplib.c sup_doWurx1 Action function
suplib.h sup_doWurx1 Prototype of the action function
primitiv.c   Alphabetical list of all primitive actions
makefile   Makefile name depends on operating system and C compiler
superlib.s7i doWurx1 Introduces the external function to a Seed7 program

The C prototype of doWurx1 is defined in the file "superlib.h": 

int doWurx1 (char *name);

This function accepts an UTF-8 'name' and it returns 0 on success. Every other return value indicates that the string is too long. In this case the exception RANGE_ERROR should be raised. The wrapper function is defined in the file "sup_rtl.c" with: 

#include "version.h"
#include "stdio.h"
#include "superlib.h"
#include "common.h"
#include "striutl.h"
#include "rtl_err.h"

void supDoWurx1 (const striType name)
  {
    cstriType cName;
    errInfoType err_info = OKAY_NO_ERROR;
    int wurxResult;

    cName = stri_to_cstri8(name, &err_info);
    if (cName == NULL) {
      raise_error(err_info);
    } else {
      wurxResult = doWurx1(cName);
      free_cstri8(cName, name);
      if (wurxResult != 0) {
        raise_error(RANGE_ERROR);
      }
    }
  }

The prototype of supDoWurx1 is defined in the file "sup_rtl.h" with: 

void supDoWurx1 (const striType name);

The action function for supDoWurx1 is defined in the file "suplib.c" with: 

#include "version.h"
#include "stdio.h"
#include "common.h"
#include "data.h"
#include "syvarutl.h"
#include "objutl.h"
#include "sup_rtl.h"

objectType sup_doWurx1 (listType arguments)
  {
    isit_stri(arg_1(arguments));
    supDoWurx1(take_stri(arg_1(arguments)));
    return SYS_EMPTY_OBJECT;
  }

The prototype of sup_doWurx1 is defined in the file "suplib.h" with: 

objectType sup_doWurx1 (listType arguments);

The action is introduced to the interpreter, by changing the file "primitiv.c". An include directive for "suplib.h" must be added: 

#include "strlib.h"
#include "suplib.h"
#include "timlib.h"

The file "primitiv.c" contains a list of alphabetically sorted primitive actions. Each action entry takes a line. It is important to add the new action "SUP_DO_WURX" at the correct place: 

{ "STR_VALUE",               str_value,               },

{ "SUP_DO_WURX",             sup_doWurx1,             },

{ "TIM_AWAIT",               tim_await,               },

The new files must be added to the makefile. Depending on C compiler and operating system Seed7 uses several makefiles. In the correct "makefile" suplib and sup_rtl must be added to lists of source and object files. Adding the suplib object file results in: 

LOBJ = actlib.o arrlib.o biglib.o blnlib.o bstlib.o chrlib.o cmdlib.o conlib.o dcllib.o drwlib.o \
       enulib.o fillib.o fltlib.o hshlib.o intlib.o itflib.o kbdlib.o lstlib.o pollib.o prclib.o \
       prglib.o reflib.o rfllib.o sctlib.o setlib.o soclib.o strlib.o suplib.o timlib.o typlib.o ut8lib.o

Adding the "suplib" source file results in: 

LSRC = actlib.c arrlib.c biglib.c blnlib.c bstlib.c chrlib.c cmdlib.c conlib.c dcllib.c drwlib.c \
       enulib.c fillib.c fltlib.c hshlib.c intlib.c itflib.c kbdlib.c lstlib.c pollib.c prclib.c \
       prglib.c reflib.c rfllib.c sctlib.c setlib.c soclib.c strlib.c suplib.c timlib.c typlib.c ut8lib.c

and object files. Adding the sup_rtl object file results in: 

ROBJ = arr_rtl.o bln_rtl.o bst_rtl.o chr_rtl.o cmd_rtl.o con_rtl.o dir_rtl.o drw_rtl.o fil_rtl.o \
       flt_rtl.o hsh_rtl.o int_rtl.o set_rtl.o soc_rtl.o str_rtl.o sup_rtl.o tim_rtl.o ut8_rtl.o \
       heaputl.o striutl.o

Adding the "sup_rtl" source file results in: 

RSRC = arr_rtl.c bln_rtl.c bst_rtl.c chr_rtl.c cmd_rtl.c con_rtl.c dir_rtl.c drw_rtl.c fil_rtl.c \
       flt_rtl.c hsh_rtl.c int_rtl.c set_rtl.c soc_rtl.c str_rtl.c sup_rtl.c tim_rtl.c ut8_rtl.c \
       heaputl.c striutl.c

The external library "superlib" itself is added with: 

SYSTEM_LIBS = -lm superlib.a

The interpreter must be compiled, so the changes can take effect. To actually call the new function it must be introduced in a Seed7 library. This is done with the library "super.s7i": 

const proc: doWurx1 (in string: name) is action "SUP_DO_WURX";

15.1 C types used by the implementation

Several Seed7 types correspond to simple C types, which are defined in "common.h":

Seed7 type C type Comment
boolean boolType _Bool, bool or int
integer intType 32- or 64-bit signed int
float floatType float (or double)
char charType 32-bit unsigned int
clib_file fileType FILE *
PRIMITIVE_SOCKET socketType int or unsigned int

Other Seed7 types correspond to C pointers, which point to a struct. Some of this structs are used in all situations: In the interpreter and in the compiler and under different operation systems and with different runtime libraries. This invariant structs are defined in "common.h" and in "data.h":

Seed7 type C type C struct Comment
string striType struct striStruct UTF-32 encoded, can contain null chars
set setType struct setStruct  
bstring bstriType struct bstriStruct Byte sequence, can contain null bytes
reference objectType struct objectStruct Interpreter type for Seed7 objects
ref_list listType struct listStruct Interpreter type for Seed7 object lists

Other Seed7 types also correspond to struct pointers, but the structs are different in interpreted and compiled Seed7 programs. The structs for interpreted programs are defined in "data.h" and the structs for compiled programs are defined in "data_rtl.h":

Seed7 type C type (interpreted) C struct (interpreted) C type (compiled) C struct (compiled)
array arrayType struct arrayStruct rtlArrayType struct rtlArrayStruct
hash hashType struct hashStruct rtlHashType struct rtlHashStruct
struct structType struct structStruct rtlStructType struct rtlStructStruct

Because interpreter and compiler use different structs the functions from e.g. "arrlib.c" cannot use functions from "arr_rtl.c".

Some Seed7 types depend on the operating system or runtime library used:

Seed7 type C type Defined as Sourcefile Comment
bigInteger bigIntType struct bigIntStruct * big_rtl.c The built-in bigInteger library
bigIntType mpz_ptr big_gmp.c The GNU Multiple Precision Arithmetic Library
pollData pollType struct select_based_pollStruct * pol_sel.c Functions cast it to implementation dependent struct
pollType struct poll_based_pollStruct * pol_unx.c Functions cast it to implementation dependent struct
PRIMITIVE_WINDOW winType x11_winRecord * drw_x11.c Functions cast from struct winStruct * to x11_winRecord *
winType win_winRecord * drw_win.c Functions cast from struct winStruct * to win_winRecord *
winType emc_winRecord * drw_emc.c Functions cast from struct winStruct * to emc_winRecord *
database databaseType dbType sql_cli.c Functions cast from databaseType to dbType
databaseType dbType sql_fire.c Functions cast from databaseType to dbType
databaseType dbType sql_lite.c Functions cast from databaseType to dbType
databaseType dbType sql_my.c Functions cast from databaseType to dbType
databaseType dbType sql_oci.c Functions cast from databaseType to dbType
databaseType dbType sql_post.c Functions cast from databaseType to dbType
databaseType dbType sql_tds.c Functions cast from databaseType to dbType
sqlStatement sqlStmtType preparedStmtType sql_cli.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_fire.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_lite.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_my.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_oci.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_post.c Functions cast from sqlStmtType to preparedStmtType
sqlStmtType preparedStmtType sql_tds.c Functions cast from sqlStmtType to preparedStmtType

There are also C types without corresponding Seed7 type. They are defined in "common.h":

C type C definition Comment
int16Type short int It is assumed that sizeof(short int) == 2
uint16Type unsigned short int Unsigned integer type with the size of int16Type
int32Type int If sizeof(int) == 4
long If sizeof(long) == 4
uint32Type unsigned int32Type Unsigned integer type with the size of int32Type
int64Type long If sizeof(long) == 8
long long If sizeof(long long) == 8
__int64 If sizeof(__int64) == 8
uint64Type unsigned int64Type Unsigned integer type with the size of int64Type
int128Type __int128 If sizeof(__int128) == 16
__int128_t If sizeof(__int128_t) == 16
uint128Type unsigned __int128 If sizeof(unsigned __int128) == 16
__uint128_t If sizeof(__uint128_t) == 16
uintType unsigned intType Unsigned integer type with the size of intType
cstriType char * String type of the C compiler
ustriType unsigned char * Helpful for unsigned comparisons
utf16striType uint16Type * UTF-16 string
utf32striType uint32Type * UTF-32 string
strElemType charType UTF-32 character element of string.
os_striType char * If the OS uses UTF-8 chars
wchar_t * If the OS uses UTF-16 chars
memSizeType uint32Type If C uses 32-bit pointers
uint64Type If C uses 64-bit pointers
errInfoType int Represents predefined Exceptions

15.2 String conversions

Seed7 strings are UTF-32 encoded and C strings are zero terminated byte sequences. C uses also byte sequences with a length. The byte sequences can be encoded with ISO-8859-1 or UTF-8. To convert between the different representations, "striutl.h" defines conversion functions between the types striType, cstriType, bstriType, utf16striType and utf32striType. The types utf16striType and utf32striType are independent of the size of wchar_t. Strings with utf16striType and utf32striType can be zero terminated or a buffer with a length, that is specified with a parameter.

Function Summary
cstriType
stri_to_cstri (const const_striType stri, errInfoType *err_info)
Create an ISO-8859-1 encoded C string from a Seed7 UTF-32 string.
cstriType
stri_to_cstri8 (const const_striType stri, errInfoType *err_info)
Create an UTF-8 encoded C string from a Seed7 UTF-32 string.
cstriType
stri_to_cstri8_buf (const const_striType stri, memSizeType *length)
Create an UTF-8 encoded C string buffer from a Seed7 UTF-32 string.
bstriType
stri_to_bstri (const const_striType stri, errInfoType *err_info)
Create an ISO-8859-1 encoded bstring from a Seed7 UTF-32 string.
bstriType
stri_to_bstri8 (const_striType stri)
Create an UTF-8 encoded bstring from a Seed7 UTF-32 string.
utf16striType
stri_to_wstri16 (const const_striType stri, memSizeType *length, errInfoType *err_info)
Create an UTF-16 encoded wide string buffer from a Seed7 UTF-32 string.
utf32striType
stri_to_wstri32 (const const_striType stri, memSizeType *length, errInfoType *err_info)
Create an UTF-32 encoded wide string buffer from a Seed7 UTF-32 string.
striType
cstri_to_stri (const_cstriType cstri)
Copy an ISO-8859-1 (Latin-1) encoded C string to a Seed7 string.
striType
cstri_buf_to_stri (const_cstriType cstri, memSizeType length)
Copy an ISO-8859-1 (Latin-1) encoded C string buffer to a Seed7 string.
striType
cstri8_to_stri (const_cstriType cstri, errInfoType *err_info)
Copy an UTF-8 encoded C string to a Seed7 string.
striType
cstri8_buf_to_stri (const_cstriType cstri, memSizeType length, errInfoType *err_info)
Copy an UTF-8 encoded C string buffer to a Seed7 string.
striType
cstri8_or_cstri_to_stri (const_cstriType cstri)
Copy an UTF-8 or ISO-8859-1 encoded C string to a Seed7 string.
striType
wstri16_to_stri (const_utf16striType wstri, memSizeType length, errInfoType *err_info)
Copy an UTF-16 encoded wide string buffer to a Seed7 string.
striType
wstri32_to_stri (const_utf32striType wstri, memSizeType length, errInfoType *err_info)
Copy an UTF-32 encoded wide string buffer to a Seed7 string.

Function Detail

stri_to_cstri

cstriType stri_to_cstri (const const_striType stri, errInfoType *err_info)

Create an ISO-8859-1 encoded C string from a Seed7 UTF-32 string. The memory for the zero byte terminated C string is allocated. The C string result must be freed with the macro free_cstri().

Parameters:
stri - Seed7 UTF-32 string to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if stri contains a null character or a character that is higher than the highest allowed ISO-8859-1 character (255).
Returns:
an ISO-8859-1 encoded null terminated C string, or NULL if the memory allocation failed or the conversion failed (the error is indicated by err_info).

stri_to_cstri8

cstriType stri_to_cstri8 (const const_striType stri, errInfoType *err_info)

Create an UTF-8 encoded C string from a Seed7 UTF-32 string. The memory for the zero byte terminated C string is allocated. The C string result must be freed with the macro free_cstri8(). This function is intended to create temporary strings, that are used as parameters. To get good performance the allocated memory for the C string is oversized.

Parameters:
stri - Seed7 UTF-32 string to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if stri contains a null character or a character that is higher than the highest allowed Unicode character (U+10FFFF).
Returns:
an UTF-8 encoded null terminated C string, or NULL if the memory allocation failed or the conversion failed (the error is indicated by err_info).

stri_to_cstri8_buf

cstriType stri_to_cstri8_buf (const const_striType stri, memSizeType *length)

Create an UTF-8 encoded C string buffer from a Seed7 UTF-32 string. The memory for the zero byte terminated C string is allocated. Zero bytes inside the string are copied to the C string. The C string result must be freed with the macro free_cstri8(). This function is intended to create temporary strings, that are used as parameters. To get good performance the allocated memory for the C string is oversized.

Parameters:
stri - Seed7 UTF-32 string to be converted.
length - Place to return the length of the result (without '\0').
Returns:
an UTF-8 encoded null terminated C string, or NULL if the memory allocation failed.

stri_to_bstri

bstriType stri_to_bstri (const const_striType stri, errInfoType *err_info)

Create an ISO-8859-1 encoded bstring from a Seed7 UTF-32 string. The memory for the bstring is allocated. No zero byte is added to the end of the bstring. No special action is done, if the UTF-32 string contains a null character.

Parameters:
stri - Seed7 UTF-32 string to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if stri contains a character that is higher than the highest allowed ISO-8859-1 character (255).
Returns:
an ISO-8859-1 encoded bstring, or NULL if the memory allocation failed or the conversion failed (the error is indicated by err_info).

stri_to_bstri8

bstriType stri_to_bstri8 (const_striType stri)

Create an UTF-8 encoded bstring from a Seed7 UTF-32 string. The memory for the bstring is allocated. No zero byte is added to the end of the bstring. No special action is done, if the original string contains a null character.

Parameters:
stri - Seed7 UTF-32 string to be converted.
Returns:
an UTF-8 encoded bstring, or NULL if the memory allocation failed.

stri_to_wstri16

utf16striType stri_to_wstri16 (const const_striType stri, memSizeType *length, errInfoType *err_info)

Create an UTF-16 encoded wide string buffer from a Seed7 UTF-32 string. The memory for the zero byte terminated wide string is allocated. This function is intended to create temporary strings, that are used as parameters. To get good performance the allocated memory for the wide string is oversized.

Parameters:
stri - Seed7 UTF-32 string to be converted.
length - Place to return the character length of the result (without '\0').
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if stri contains a character that is higher than the highest allowed Unicode character (U+10FFFF).
Returns:
an UTF-16 encoded null terminated wide string, or NULL if the memory allocation failed or the conversion failed (the error is indicated by err_info).

stri_to_wstri32

utf32striType stri_to_wstri32 (const const_striType stri, memSizeType *length, errInfoType *err_info)

Create an UTF-32 encoded wide string buffer from a Seed7 UTF-32 string. The memory for the zero byte terminated wide string is allocated. This function is intended to create temporary strings, that are used as parameters. To get good performance the allocated memory for the wide string is oversized.

Parameters:
stri - Seed7 UTF-32 string to be converted.
length - Place to return the character length of the result (without '\0').
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if stri contains a character that is higher than the highest allowed Unicode character (U+10FFFF).
Returns:
an UTF-32 encoded null terminated wide string, or NULL if the memory allocation failed or the conversion failed (the error is indicated by err_info).

cstri_to_stri

striType cstri_to_stri (const_cstriType cstri)

Copy an ISO-8859-1 (Latin-1) encoded C string to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
cstri - Null terminated ISO-8859-1 encoded C string.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed.

cstri_buf_to_stri

striType cstri_buf_to_stri (const_cstriType cstri, memSizeType length)

Copy an ISO-8859-1 (Latin-1) encoded C string buffer to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
cstri - ISO-8859-1 encoded C string buffer (not null terminated).
length - Byte length of the ISO-8859-1 encoded C string buffer.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed.

cstri8_to_stri

striType cstri8_to_stri (const_cstriType cstri, errInfoType *err_info)

Copy an UTF-8 encoded C string to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
cstri - Null terminated UTF-8 encoded C string.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if the conversion failed.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed or invalid UTF-8 encodings are used.

cstri8_buf_to_stri

striType cstri8_buf_to_stri (const_cstriType cstri, memSizeType length, errInfoType *err_info)

Copy an UTF-8 encoded C string buffer to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
cstri - UTF-8 encoded C string buffer (not null terminated).
length - Byte length of the UTF-8 encoded C string buffer.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if the conversion failed.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed or invalid UTF-8 encodings are used.

cstri8_or_cstri_to_stri

striType cstri8_or_cstri_to_stri (const_cstriType cstri)

Copy an UTF-8 or ISO-8859-1 encoded C string to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
cstri - Null terminated UTF-8 or ISO-8859-1 encoded C string.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed.

wstri16_to_stri

striType wstri16_to_stri (const_utf16striType wstri, memSizeType length, errInfoType *err_info)

Copy an UTF-16 encoded wide string buffer to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
wstri - UTF-16 encoded wide string buffer (not null terminated).
length - Character length of the UTF-16 encoded wide string buffer.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed.

wstri32_to_stri

striType wstri32_to_stri (const_utf32striType wstri, memSizeType length, errInfoType *err_info)

Copy an UTF-32 encoded wide string buffer to a Seed7 string. The memory for the UTF-32 encoded Seed7 string is allocated.

Parameters:
wstri - UTF-32 encoded wide string buffer (not null terminated).
length - Character length of the UTF-32 encoded wide string buffer.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed.
Returns:
an UTF-32 encoded Seed7 string, or NULL if the memory allocation failed.

15.3 Operating system string and path conversions

Operating systems disagree in their Unicode encoding (UTF-8 or UTF-16). To cope with this, "striutl.h" defines the type os_striType and functions to convert to and from os_striType. The different concepts to represent a file path (path delimiter and drive letter) are handled with cp_to_os_path and cp_from_os_path.

Function Summary
striType
conv_from_os_stri (const const_os_striType os_stri, memSizeType length)
Convert an os_striType string with length to a Seed7 UTF-32 string.
os_striType
stri_to_os_stri (const_striType stri, errInfoType *err_info)
Convert a Seed7 UTF-32 string to a null terminated os_striType string.
striType
os_stri_to_stri (const_os_striType os_stri, errInfoType *err_info)
Convert a null terminated os_striType string to a Seed7 UTF-32 string.
os_striType
cp_to_os_path (const_striType std_path, int *path_info, errInfoType *err_info)
Convert a Seed7 standard path to a path used by system calls.
striType
cp_from_os_path (const_os_striType os_path, errInfoType *err_info)
Convert a path returned by a system call to a Seed7 standard path.

Function Detail

conv_from_os_stri

striType conv_from_os_stri (const const_os_striType os_stri, memSizeType length)

Convert an os_striType string with length to a Seed7 UTF-32 string. Many system calls return os_striType data with length. System calls are defined in "version.h" and "os_decls.h". They are prefixed with os_ and use strings of the type os_striType. Depending on the operating system os_striType can describe byte or wide char strings. The encoding can be Latin-1, UTF-8, UTF-16 or it can use a code page.

Parameters:
os_stri - Possibly binary string (may contain null characters).
length - Length of os_stri in characters.
Returns:
a Seed7 UTF-32 string, or NULL if an error occurred.

stri_to_os_stri

os_striType stri_to_os_stri (const_striType stri, errInfoType *err_info)

Convert a Seed7 UTF-32 string to a null terminated os_striType string. The memory for the null terminated os_striType string is allocated. The os_striType result is allocated with the macro os_stri_alloc() and it must be freed with the macro os_stri_free(). Strings allocated with os_stri_alloc() must be freed in the reverse order of their creation. This allows that allocations work in a stack like manner. Many system calls have parameters with null terminated os_striType strings. System calls are defined in "version.h" and "os_decls.h". They are prefixed with os_ and use strings of the type os_striType. Depending on the operating system os_striType can describe byte or wide char strings. The encoding can be Latin-1, UTF-8, UTF-16 or it can use a code page.

Parameters:
stri - Seed7 UTF-32 string to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if the conversion failed.
Returns:
a null terminated os_striType value used by system calls, or NULL if an error occurred.

os_stri_to_stri

striType os_stri_to_stri (const_os_striType os_stri, errInfoType *err_info)

Convert a null terminated os_striType string to a Seed7 UTF-32 string. Many system calls return null terminated os_striType strings. System calls are defined in "version.h" and "os_decls.h". They are prefixed with os_ and use strings of the type os_striType. Depending on the operating system os_striType can describe byte or wide char strings. The encoding can be Latin-1, UTF-8, UTF-16 or it can use a code page.

Parameters:
os_stri - Null terminated os_striType string to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed.
Returns:
a Seed7 UTF-32 string, or NULL if an error occurred.

cp_to_os_path

os_striType cp_to_os_path (const_striType std_path, int *path_info, errInfoType *err_info)

Convert a Seed7 standard path to a path used by system calls. The memory for the null terminated os_striType path is allocated. The os_striType result is allocated with the macro os_stri_alloc() and it must be freed with the macro os_stri_free(). Strings allocated with os_stri_alloc() must be freed in the reverse order of their creation. This allows that allocations work in a stack like manner. System calls are defined in "version.h" and "os_decls.h". They are prefixed with os_ and use system paths of the type os_striType. Depending on the operating system os_striType can describe byte or wide char strings. The encoding can be Latin-1, UTF-8, UTF-16 or it can use a code page. Beyond the conversion to os_striType a mapping to drive letters might take place on some operating systems.

Parameters:
std_path - UTF-32 encoded Seed7 standard path to be converted.
path_info - Unchanged if the function succeeds, and PATH_IS_EMULATED_ROOT if the path is "/", and PATH_NOT_MAPPED if the path cannot be mapped.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed, and RANGE_ERROR if the path is not a standard path.
Returns:
a null terminated os_striType path used by system calls, or NULL if an error occurred.

cp_from_os_path

striType cp_from_os_path (const_os_striType os_path, errInfoType *err_info)

Convert a path returned by a system call to a Seed7 standard path. System calls are defined in "version.h" and "os_decls.h". They are prefixed with os_ and use system paths of the type os_striType. Depending on the operating system os_striType can describe byte or wide char strings. The encoding can be Latin-1, UTF-8, UTF-16 or it can use a code page. Beyond the conversion from os_striType a mapping from drive letters might take place on some operating systems.

Parameters:
os_path - Null terminated os_striType path to be converted.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if the memory allocation failed.
Returns:
an UTF-32 encoded Seed7 standard path, or NULL if the memory allocation failed.

15.4 Macros to access the action parameters

A primitive action function has one parameter named 'arguments'. The 'arguments' parameter has the type listType and contains a list of objects. The header file "objutl.h" defines macros like arg_1, arg_2, arg_3, etc. to get a specific object from the 'arguments'.

Functions (macros) to get a Seed7 object from a list
objectType
arg_1 (listType arguments)
Take the first object from the list.
objectType
arg_2 (listType arguments)
Take the second object from the list.
objectType
arg_3 (listType arguments)
Take the third object from the list.
. . .
. . .
objectType
arg_12 (listType arguments)
Take the twelfth object from the list.

An object value contains a specific C implementation type. The header file "objutl.h" defines macros like isit_char and isit_set to check, if an object has the requested type. If the object has not the requested C implementation type and error message is written.

Functions (macros) to check the C type of Seed7 objects
void
isit_array (objectType arg)
Check if the object type is arrayType.
void
isit_bigint (objectType arg)
Check if the object type is bigIntType.
void
isit_bool (objectType arg)
Check if the object type is boolType.
void
isit_bstri (objectType arg)
Check if the object type is bstriType.
void
isit_char (objectType arg)
Check if the object type is charType.
void
isit_database (objectType arg)
Check if the object type is databaseType.
void
isit_file (objectType arg)
Check if the object type is fileType.
void
isit_float (objectType arg)
Check if the object type is floatType.
void
isit_hash (objectType arg)
Check if the object type is hashType.
void
isit_int (objectType arg)
Check if the object type is intType.
void
isit_poll (objectType arg)
Check if the object type is pollType.
void
isit_set (objectType arg)
Check if the object type is setType.
void
isit_socket (objectType arg)
Check if the object type is socketType.
void
isit_sqlstmt (objectType arg)
Check if the object type is sqlStmtType.
void
isit_stri (objectType arg)
Check if the object type is striType.
void
isit_struct (objectType arg)
Check if the object type is structType.
void
isit_win (objectType arg)
Check if the object type is winType.

The header file "objutl.h" defines macros like take_bool and take_file. This macros return a value with the requested C implementation type.

Functions (macros) to get the C values of Seed7 objects
arrayType
take_array (objectType arg)
Take the array value from an object.
bigIntType
take_bigint (objectType arg)
Take the bigInteger value from an object.
boolType
take_bool (objectType arg)
Take the boolean value from an object.
bstriType
take_bstri (objectType arg)
Take the bstring value from an object.
charType
take_char (objectType arg)
Take the char value from an object.
databaseType
take_database (objectType arg)
Take the database value from an object.
fileType
take_file (objectType arg)
Take the file value from an object.
floatType
take_float (objectType arg)
Take the float value from an object.
hashType
take_hash (objectType arg)
Take the hash table value from an object.
intType
take_int (objectType arg)
Take the integer value from an object.
pollType
take_poll (objectType arg)
Take the poll data value from an object.
setType
take_set (objectType arg)
Take the set value from an object.
socketType
take_socket (objectType arg)
Take the socket value from an object.
sqlStmtType
take_sqlstmt (objectType arg)
Take the SQL prepared statement value from an object.
striType
take_stri (objectType arg)
Take the string value from an object.
structType
take_struct (objectType arg)
Take the struct value from an object.
winType
take_win (objectType arg)
Take the struct value from an object.

15.5 Functions to create action results

A primitive action function has a result of type objectType. The header file "objutl.h" defines macros like bld_bigint_temp and bld_stri_temp to create an object with the specified type.

Functions to create Seed7 objects with a C value
objectType
bld_array_temp (arrayType temp_array)
Create an object with an arrayType value.
objectType
bld_bigint_temp (bigIntType temp_bigint)
Create an object with a bigIntType value.
objectType
bld_bstri_temp (bstriType temp_bstri)
Create an object with a bstriType value.
objectType
bld_char_temp (charType temp_char)
Create an object with a charType value.
objectType
bld_database_temp (databaseType temp_database)
Create an object with a databaseType value.
objectType
bld_file_temp (fileType temp_file)
Create an object with a fileType value.
objectType
bld_float_temp (floatType temp_float)
Create an object with a floatType value.
objectType
bld_hash_temp (hashType temp_hash)
Create an object with a hashType value.
objectType
bld_int_temp (intType temp_int)
Create an object with an intType value.
objectType
bld_poll_temp (pollType temp_poll)
Create an object with a pollType value.
objectType
bld_set_temp (setType temp_set)
Create an object with a setType value.
objectType
bld_socket_temp (socketType temp_socket)
Create an object with a socketType value.
objectType
bld_sqlstmt_temp (sqlStmtType temp_sqlstmt)
Create an object with a sqlStmtType value.
objectType
bld_stri_temp (striType temp_stri)
Create an object with a striType value.
objectType
bld_struct_temp (structType temp_struct)
Create an object with a structType value.
objectType
bld_win_temp (winType temp_win)
Create an object with a winType value.

15.6 Memory management macros

The conversion functions mentioned above use macros to do the memory management. Some of this macros are not based on malloc() but manage the memory in a stack. Therefore it is important to use the correct macro to allocate and free memory. The macros below are defined in the header file "striutl.h".

Macro Summary
void
free_cstri (cstriType cstri, striType stri)
Macro to free memory that has been allocated by stri_to_cstri().
void
free_cstri8 (cstriType cstri, striType stri)
Macro to free memory that has been allocated by stri_to_cstri8() or stri_to_cstri8_buf().
boolType
os_stri_alloc (os_striType &var, memSizeType len)
Macro to allocate memory for an os_striType string.
void
os_stri_free (os_striType var)
Macro to free memory that has been allocated with os_stri_alloc.

Macro Detail

free_cstri

void free_cstri (cstriType cstri, striType stri)

Macro to free memory that has been allocated by stri_to_cstri().

Parameters:
cstri - The string to be freed.
stri - The parameter that was used when stri_to_cstri() was called.

free_cstri8

void free_cstri8 (cstriType cstri, striType stri)

Macro to free memory that has been allocated by stri_to_cstri8() or stri_to_cstri8_buf().

Parameters:
cstri - The string to be freed.
stri - The parameter that was used when stri_to_cstri8() or stri_to_cstri8_buf() was called.

os_stri_alloc

boolType os_stri_alloc (os_striType &var, memSizeType len)

Macro to allocate memory for an os_striType string. Strings allocated with os_stri_alloc() must be freed with os_stri_free() in the reverse order of their creation. This allows that allocations work in a stack like manner.

Parameters:
var - Reference to a variable to which the allocated memory is assigned.
len - Size of the allocated memory in characters.
Returns:
TRUE if the allocation succeeds, and FALSE if the memory allocation failed.

os_stri_free

void os_stri_free (os_striType var)

Macro to free memory that has been allocated with os_stri_alloc. Strings allocated with os_stri_alloc() must be freed with os_stri_free() in the reverse order of their creation. This allows that allocations work in a stack like manner. The strings returned by stri_to_os_stri and cp_to_os_path are also allocated with os_stri_alloc. Therefore they must also be freed with os_stri_free() in the reverse order of their creation.

Parameters:
var - The string to be freed.

15.7 Basic conversion functions

The conversion functions mentioned above are implemented with basic conversion functions. In some situations it might make sense to use the basic conversion functions directly. This functions are optimized for performance. Some functions use loop unrolling inspired by Duff's device. The basic conversion functions below are defined in the header file "striutl.h".

Function Summary
void
memcpy_to_strelem (register strElemType *const dest, register const const_ustriType src, memSizeType len)
Copy len bytes to Seed7 characters in a string.
void
memset_to_strelem (register strElemType *const dest, register const strElemType ch, memSizeType len)
Fill len Seed7 characters with the character ch.
boolType
memcpy_from_strelem (register const const_ustriType dest, register const strElemType *const src, memSizeType len)
Copy len Seed7 characters to a byte string.
const strElemType *
memchr_strelem (register const strElemType *mem, const strElemType ch, memSizeType len)
Scan the first len Seed7 characters for the character ch.
memSizeType
utf8_to_stri (strElemType *const dest_stri, memSizeType *const dest_len, const_ustriType ustri, memSizeType len)
Convert an UTF-8 encoded string to an UTF-32 encoded string.
memSizeType
stri_to_utf8 (const ustriType out_stri, const strElemType *strelem, memSizeType len)
Convert an UTF-32 encoded string to an UTF-8 encoded string.
memSizeType
stri_to_utf16 (const utf16striType out_wstri, register const strElemType *strelem, memSizeType len, errInfoType *const err_info)
Convert an UTF-32 encoded string to an UTF-16 encoded string.

Function Detail

memcpy_to_strelem

void memcpy_to_strelem (register strElemType *const dest, register const const_ustriType src, memSizeType len)

Copy len bytes to Seed7 characters in a string. This function works also correct if 'src' and 'dest' point to the same address. In other words it works correct for: 

       memcpy_to_strelem(mem, (ustriType) mem, num);
Parameters:
dest - Destination array with UTF-32 encoded characters.
src - Source array with ISO-8859-1 encoded bytes.
len - Number of bytes in 'src' and UTF-32 characters in 'dest'.

memset_to_strelem

void memset_to_strelem (register strElemType *const dest, register const strElemType ch, memSizeType len)

Fill len Seed7 characters with the character ch.

Parameters:
dest - Destination array with UTF-32 encoded characters.
ch - UTF-32 encoded character to be filled into 'dest'.
len - Specifies how often 'ch' is filled into 'dest'.

memcpy_from_strelem

boolType memcpy_from_strelem (register const const_ustriType dest, register const strElemType *const src, memSizeType len)

Copy len Seed7 characters to a byte string. This function uses loop unrolling inspired by Duff's device and a trick with a binary or (|=) to check for allowed values.

Parameters:
dest - Destination array with ISO-8859-1 encoded bytes.
src - Source array with UTF-32 encoded characters.
len - Number of UTF-32 characters in 'src' and bytes in 'dest'.
Returns:
TRUE if one of the characters does not fit into a byte, FALSE otherwise.

memchr_strelem

const strElemType *memchr_strelem (register const strElemType *mem, const strElemType ch, memSizeType len)

Scan the first len Seed7 characters for the character ch.

Parameters:
mem - Array with UTF-32 characters.
ch - UTF-32 character to be searched in 'mem'.
len - Number of UTF-32 characters in 'mem'.
Returns:
a pointer to the matching character, or NULL if the character does not occur in the given string area.

utf8_to_stri

memSizeType utf8_to_stri (strElemType *const dest_stri, memSizeType *const dest_len, const_ustriType ustri, memSizeType len)

Convert an UTF-8 encoded string to an UTF-32 encoded string. The source and destination strings are not '\0' terminated. The memory for the destination dest_stri is not allocated.

Parameters:
dest_stri - Destination of the UTF-32 encoded string.
dest_len - Place to return the length of dest_stri.
ustri - UTF-8 encoded string to be converted.
len - Number of bytes in ustri.
Returns:
the number of bytes in ustri that are left unconverted, or 0 if ustri has been successfully converted.

stri_to_utf8

memSizeType stri_to_utf8 (const ustriType out_stri, const strElemType *strelem, memSizeType len)

Convert an UTF-32 encoded string to an UTF-8 encoded string. The source and destination strings are not '\0' terminated. The memory for the destination out_stri is not allocated.

Parameters:
out_stri - Destination of the UTF-8 encoded string.
strelem - UTF-32 encoded string to be converted.
len - Number of UTF-32 characters in strelem.
Returns:
the length of the converted UTF-8 string.

stri_to_utf16

memSizeType stri_to_utf16 (const utf16striType out_wstri, register const strElemType *strelem, memSizeType len, errInfoType *const err_info)

Convert an UTF-32 encoded string to an UTF-16 encoded string. The source and destination strings are not '\0' terminated. The memory for the destination out_wstri is not allocated.

Parameters:
out_wstri - Destination of the UTF-16 encoded string.
strelem - UTF-32 encoded string to be converted.
len - Number of UTF-32 characters in strelem.
err_info - Unchanged if the function succeeds, and MEMORY_ERROR if *strelem contains a character that is higher than the highest allowed Unicode character (U+10FFFF).
Returns:
the length of the converted UTF-16 string in characters.

15.8 Error handling

The C programming language does not provide exceptions. Seed7 uses several methods to provide error handling. Before an actual exception is raised an error state can be handled in different ways:

C code can check the value of the err_info variable, or check if a function returns NULL. In case of error it is possible to do some cleaning up. An error situation can be propagated this way over several function levels. It is important to assure that an existing error situation (err_info has a value not equal to OKAY_NO_ERROR) is not reset to a situation that no error occurred.

An actual exception can be triggered with the macro raise_error. This macro takes an errInfoType parameter to describe the actual exception. Note that all cleaning up must be done before raise_error is called. This macro calls the function raise_exception2 with the additional parameters __FILE__ and __LINE__. The function raise_exception2 has different implementations for interpreted and compiled programs:

That means that raise_error also returns normally in the interpreter. Therefore a function that calls raise_error must return after it has called this function. Surrounding functions must also return. This must be done up to the current action function. So either all these functions always return immediate or a special return value (e.g. NULL) signals them to return. Doing some clean up, when the special return value is received, will not work in compiled code. If cleaning up is necessary the call of raise_error should be done in the outer function.

Function Summary
void
raise_error (errInfoType err_info)
Macro to raise an exception.

Function Detail

raise_error

void raise_error (errInfoType err_info)

Macro to raise an exception. This macro calls the function raise_exception2 with the additional parameters __FILE__ and __LINE__. The function raise_exception2 has different implementations for interpreted and compiled programs.

Parameters:
err_info - The exception to be raised.
 previous   up   next