.. 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()
* ptrcmp()
* ringvm_cfunctionslist() 
* ringvm_functionslist() 
* ringvm_classeslist() 
* ringvm_packageslist() 
* ringvm_memorylist() 
* ringvm_calllist() 
* ringvm_fileslist()

.. 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.

.. tip:: We can pass NULL as parameter instead of using NULLPointer()

.. 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).

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

ptrcmp() function
================================

We can compare between two pointers (C Objects) using the ptrcmp() function.

Syntax:

.. code-block:: ring

	ptrcmp(oObject1,oObject2) ---> value = 1 if oObject1 = oObject2
				       value = 0 if oObject1 != oObject2

Example:

.. code-block:: ring

	fp = fopen("ptrcmp.ring","r")
	fp2 = fp
	fp3 = fopen("ptrcmp.ring","r")

	see ptrcmp(fp,fp2) + nl
	see ptrcmp(fp,fp3) + nl

	fclose(fp)
	fclose(fp3)

Output:

.. code-block:: ring

	1
	0

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

ringvm_cfunctionslist() function
================================

The Function return a list of functions written in C.

Syntax:

.. code-block:: ring

	RingVM_CFunctionsList() ---> List

Example:

.. code-block:: ring

	See RingVM_CFunctionsList()

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

ringvm_functionslist() function
===============================

The Function return a list of functions written in Ring.

Each List Member is a list contains the next items

* Function Name
* Program Counter (PC) - Function Position in Byte Code.
* Source Code File Name
* Private Flag (For Private Methods in Classes)

Syntax:

.. code-block:: ring

	RingVM_FunctionsList() ---> List

Example:

.. code-block:: ring

	test()

	func test
		see ringvm_functionslist()

Output:

.. code-block:: ring

	test
	8
	B:/ring/tests/scripts/functionslist.ring
	0

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

ringvm_classeslist() function
=============================

The Function return a list of Classes.

Each List Member is a list contains the next items

* Class Name
* Program Counter (PC) - Class Position in Byte Code.
* Parent Class Name
* Methods List
* Flag (Is parent class information collected)
* Pointer to the package (or NULL if no package is used)

Syntax:

.. code-block:: ring

	RingVM_ClassesList() ---> List

Example:

.. code-block:: ring

	see ringvm_classeslist()

	class class1
		func f1
	class class2 from class1
	class class3 from class1

Output:

.. code-block:: ring

	class1
	9

	f1
	13
	B:/ring/tests/scripts/classeslist.ring
	0
	0
	00000000
	class2
	16
	class1
	0
	00000000
	class3
	20
	class1
	0
	00000000

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

ringvm_packageslist() function
==============================

The Function return a list of Packages.

Each List Member is a list contains the next items

* Package Name
* Classes List

Syntax:

.. code-block:: ring

	RingVM_PackagesList() ---> List

Example:

.. code-block:: ring

	see ringvm_packageslist()

	package package1
		class class1

	package package2
		class class1

	package package3
		class class1

Output:

.. code-block:: ring

	package1
	class1
	11

	0
	00FEF838
	package2
	class1
	17

	0
	00FEF978
	package3
	class1
	23

	0
	00FEFF68

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

ringvm_memorylist() function
============================

The Function return a list of Memory Scopes and Variables.

Each List Member is a list contains variables in a different scope.

Each Item in the scope list is a list contains the next items

* Variable Name
* Variable Type
* Variable Value
* Pointer Type (List/Item) if the value is a list
* Private Flag (if the variable is an attribute in a Class)

Syntax:

.. code-block:: ring

	RingVM_MemoryList() ---> List

Example:

.. code-block:: ring

	x = 10
	test()
	func test
		y = 20
		see ringvm_memorylist()

Output:

.. code-block:: ring

	true
	2
	1
	0
	0
	false
	2
	0
	0
	0
	nl
	1


	0
	0
	null
	1

	0
	0
	ring_gettemp_var
	4
	00000000
	0
	0
	ccatcherror
	1
	NULL
	0
	0
	ring_settemp_var
	4
	00000000
	0
	0
	ring_tempflag_var
	2
	0
	0
	0
	stdin
	3
	50512DB8
	file
	0
	0
	0
	stdout
	3
	50512DD8
	file
	0
	0
	0
	stderr
	3
	50512DF8
	file
	0
	0
	0
	this
	4
	00000000
	0
	0
	sysargv
	3
	B:\ring\bin/ring
	B:/ring/tests/scripts/memorylist.ring
	0
	0
	x
	2
	10
	0
	0
	y
	2
	20
	0
	0

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

ringvm_calllist() function
==========================

The Function return a list of the functions call list.

Each List Member is a list contains the next items

* Function Type
* Function Name
* Program Counter (PC)
* Stack Pointer (SP)
* Temp. Memory List
* Method or Function Flag
* Caller PC
* FuncExec Flag
* ListStart Flag
* Nested Lists Pointer
* State List

Syntax:

.. code-block:: ring

	RingVM_CallList() ---> List

Example:

.. code-block:: ring

	hello()
	func hello
		test()

	func test
		mylist = ringvm_calllist()
		for t in mylist see t[2] + nl next

Output:

.. code-block:: ring

	function hello() in file B:/ring/tests/scripts/calllist.ring
	called from line 1
	function test() in file B:/ring/tests/scripts/calllist.ring
	called from line 3
	ringvm_calllist


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

ringvm_fileslist() function
===========================

Function return a list of the Ring Files.

Syntax:

.. code-block:: ring

	RingVM_FilesList() ---> List

Example:

.. code-block:: ring

	load "stdlib.ring"
	see ringvm_fileslist()

Output:

.. code-block:: ring

	B:/ring/tests/scripts/fileslist.ring
	B:\ring\bin\stdlib.ring
	eval
	stdlib.ring
	stdlib.rh
	stdclasses.ring
	stdfunctions.ring
	stdbase.ring
	stdstring.ring
	stdlist.ring
	stdstack.ring
	stdqueue.ring
	stdmath.ring
	stddatetime.ring
	stdfile.ring
	stdsystem.ring
	stddebug.ring
	stddatatype.ring
	stdconversion.ring
	stdodbc.ring
	stdmysql.ring
	stdsecurity.ring
	stdinternet.ring
	stdhashtable.ring
	stdtree.ring