Index  |  Classes  |  Functions

Functions

derefPtr()

Dereferences a pointer to pointer.

derefPtr( ptr )
ptr

The pointer to be dereferenced.

Returns:

The pointer stored at the location indicated by ptr, as a pointer-sized integer.

This function can be used to access data stored into indirect pointers either returned or stored into by-reference parameters or structures by foreign functions.

dynExt()

Return a system dependent dynamic library extension.

dynExt( )
Returns:

A string containing the local platform dynamic library extension.

This methods return one of the following values:

It is possible to use this string to load the "same" dynamic library, exporting the same functions, on different platforms.

limitMembuf()

Sizes a memory buffer to a zero terminated string.

limitMembuf( mb, [size] )
mb

The memory buffer to be sized.

size

The size at which to cut the memory buffer.

Returns:

The resized Memory Buffer.

Many external functions in C dynamic libraries returns zero terminated strings in an encoding-neutral format.

It is possible to encapsulate that data in a Falcon memory buffer for easier manipulation in Falcon, and possibly for a later transformation into an internationalized Falcon string.

Whenever DynLib returns a memory buffer, it sets its size to 2^31, as the size of the returned data is not known. But if the user knows that the returned data is actually a non-utf8 zero terminated string (utf-8 strings can be parsed directly with the "S" return specifier), or if it has some mean to determine the returned structure size, it is possible to re-size the MemBuf so that it fits the actual data. It is granted that the resized memory buffer points to the same foreign data as the original one, so the returned buffer can be fed into foreign function expecting to deal with the original data.

Note: The behavior of this function is undefined if the mb parameter was not created through a function in DynLib in versions prior to 0.8.12.

If the size parameter is not provided, the function scans for a zero byte and sets that position as the size of this memory buffer. If it's provided, that value is used as the new dimension of the Memory Buffer.

Note: Using this function is necessary to correctly turn a C zero terminated string in arbitrary encoding into a Falcon string via transcodeFrom.

Note: since version 0.9, the function modifies the original memory buffer and returns it, instead of creating a new memory buffer.

limitMembufW()

Sizes a memory buffer to a zero terminated string.

limitMembufW( mb, [size] )
mb

The memory buffer to be sized.

size

The size at which to cut the memory buffer.

Many external functions in C dynamic libraries returns zero terminated strings in an encoding-neutral format.

It is possible to encapsulate that data in a Falcon memory buffer for easier manipulation in Falcon, and possibly for a later transformation into an internationalized Falcon string.

Whenever DynLib returns a memory buffer, it sets its size to 2^31, as the size of the returned data is not known. But if the user knows that the returned data is actually a non-utf16 zero terminated string (utf-16 strings can be parsed directly with the "W" return specifier), or if it has some mean to determine the returned structure size, it is possible to re-size the MemBuf so that it fits the actual data. It is granted that the resized memory buffer points to the same foreign data as the original one, so the returned buffer can be fed into foreign function expecting to deal with the original data.

Note: The behavior of this function is undefined if the mb parameter was not created through a function in DynLib in versions prior to 0.8.12.

If the size parameter is not provided, the function scans for a zero short int (16-bit word) and sets that position as the size of this memory buffer. If it's provided, that value is used as the new dimension of the Memory Buffer.

Note: Using this function is necessary to correctly turn a C zero terminated string in arbitrary encoding into a Falcon string via transcodeFrom.

Note: Actually, this function uses the platform specific wchar_t size to scan for the 0 terminator. On some platforms, wchar_t is 4 bytes wide.

Note: since version 0.9, the function modifies the original memory buffer and returns it, instead of creating a new memory buffer.


Index  |  Classes  |  Functions
Made with Faldoc 1.0.0