fun declaration inside a
lib binds to a C function.
lib C # In C: double cos(double x) fun cos(value : Float64) : Float64 end
Once you bind it, the function is available inside the
C type as if it was a class method:
C.cos(1.5) #=> 0.0707372
You can omit the parentheses if the function doesn't have arguments (and omit them in the call as well):
lib C fun getch : Int32 end C.getch
If the return type is void you can omit it:
lib C fun srand(seed : UInt32) end C.srand(1_u32)
You can bind to variadic functions:
lib X fun variadic(value : Int32, ...) : Int32 end X.variadic(1, 2, 3, 4)
Note that there are no implicit conversions (except
to_unsafe, explained later) when invoking a C function: you must pass the exact type that is expected. For integers and floats you can use the various
Because method names in Crystal must start with a lowercase letter,
fun names must also start with a lowercase letter. If you need to bind to a C function that starts with a capital letter you can give the function another name for Crystal:
lib LibSDL fun init = SDL_Init(flags : UInt32) : Int32 end
You can also use a string as a name if the name is not a valid identifier or type name:
lib LLVMIntrinsics fun ceil_f32 = "llvm.ceil.f32"(value : Float32) : Float32 end
This can also be used to give shorter, nicer names to C functions, as these tend to be long and usually be prefixed with the library name.
The valid types to use in C bindings are:
Pointer(Int32), which can also be written as
StaticArray(Int32, 8), which can also be written as
Function(Int32, Int32), which can also be written as
Int32 -> Int32)
Void: the absence of a return value.
NoReturn: similar to
Void, but the compiler understands that no code can be executed after that invocation.
Refer to the type gammar for the notation used in fun types.
The standard library defines the LibC lib with aliases for common C types, like
size_t. Use them in bindings like this:
lib MyLib fun my_fun(some_size : LibC::SizeT) end
Note: The C
char type is
UInt8 in Crystal, so a
char* or a
const char* is
Char type in Crystal is a unicode codepoint so it is represented by four bytes, making it similar to an
Int32, not to an
UInt8. There's also the alias
LibC::Char if in doubt.