.. index:: 
	single: Low Level Functions; Introduction

===================
Low Level Functions
===================

In this chapter we will learn about the low level functions provided by Ring

* callgc()
* varptr()
* space()
* nullpointer()
* object2pointer()
* pointer2object()

.. index:: 
	pair: Low Level Functions; callgc()

callgc() function
=================

Use this function to force calling the garbage collector during function execution when you
use a loop that create temp. variables that you don't free using the assignment operation.

It's very rare to need this function but it's useful when you create something like event-loop
for your game engine and start creating lists on the fly when you call functions.

Example 

.. code-block:: ring

	While True

		# process events
		# call functions using temp. lists like myfunc(["temp list"])

		# call the garbage collector
		callgc()
	End

.. tip:: In Ring the garbage collector works automatically in the end of function execution or
	 when you use the assignment statement.

.. index:: 
	pair: Low Level Functions; varptr()

varptr() function
=================

Use the varptr() function when you need to pass a pointer to a C/C++ function.

Syntax:

	varptr(cVariableName,cPointerType) ---> Low Level Object (C Pointer)

example:

.. code-block:: ring

	r = 10
	z = 20
	see r + nl
	see varptr("r","int") 
	see varptr("z","int")

Output:

.. code-block:: ring

	10
	00E3C740
	int
	2
	00E3BEC0
	int
	2

.. note:: the low level object is a list contains three items (The Pointer, The Type, The Status)


.. index:: 
	pair: Low Level Functions; space()

space() function
================

Use the space function to allocate a specific number of bytes in Memory.

Syntax:

.. code-block:: ring

	Space(nBytesCount) ---> String 

Example:

.. code-block:: ring

	mystring = space(200)
	See "String Size : " + len(mystring) + nl
	See "String : " + mystring + nl
	See "String Pointer : " 
	See varptr("mystring","char *")

Output:

.. code-block:: ring

	String Size : 200
	String :                                                                                                                                                        
	String Pointer : 00FF8FE8
	char *
	2

.. note:: You may need the space() and VarPtr() functions to pass buffers to C functions.

.. index:: 
	pair: Low Level Functions; nullpointer()

nullpointer() function
======================

You may need to pass the NULL pointer to a C function that may expect a pointer as parameter
and accept NULL pointers for optional parameters.

Example:

The next example uses the SDL_BlitSurface() function from the LibSDL Library through RingSDL
The function accept SDL_Rect pointers in the second and the last parameter.
Also the function accept NULL pointers, so we can pass them using the NULLPointer() Function.

.. code-block:: ring

	SDL_BlitSurface(text, nullpointer(), surface, nullpointer())

.. note:: The previous code doesn't work alone, you need to learn how to use RingSDL first.

.. index:: 
	pair: Low Level Functions; object2pointer()

object2pointer() function
=========================

Use this function to get a C pointer for Ring lists and objects

Syntax:

.. code-block:: ring

	object2pointer(List|Object) --> Low Level Object ( C Pointer )

.. index:: 
	pair: Low Level Functions; pointer2object()

pointer2object() function
=========================

Use this function to get the Ring list and/or object from the low level object (C Pointer)

Syntax:

.. code-block:: ring

	pointer2object(Low Level Object) ---> List|Object


Example:

.. code-block:: ring

	# Create the list 
	mylist = 1:5

	# Create pointer to the list
	x = object2pointer(mylist)
	see x

	see nl

	# Add items to the list
	mylist + "welcome"

	# print the list items
	y = pointer2object(x)
	see y 

Output:

.. code-block:: ring

	0069A5D8
	OBJECTPOINTER
	0

	1
	2
	3
	4
	5
	welcome

.. note:: In Ring the assignment operator copy lists and objects by value, to copy by reference
	Just use the object2pointer() and pointer2object() functions.

.. tip:: The object2pointer() and pointer2object() are used in the stdlib - Tree Class implementation
         to create a reference for the parent node (object) in the child node (another object).