By breaking your code into modules or “classes” you can have a finer granularity of the code itself, you can encapsulate the base code and work on top of it, you can also reuse the code in other projects if you have a good design. An example would be a log library (for logging useful debugging information onto text files) with proper design and care you’ll be able to use the same library in almost all of your projects with little to no modification at all.

The main points you should never forget about are:

• Instancing
  • This is when you create an “object” – And as you create it, you should also be able to destroy it. (Constructors / Destructors in OOP). An object factory may be implemented (this would be another class) to handle the instances. In CPP you may use smart pointers, but we’re talking about PB in this case.
• Members
  • In our case a main structure is used as the “members” (Again, in reference to OOP) – This structure is instantiated by the constructor or “create” function. Don’t forget that anything you allocate you should also be able to deallocate. It doesn’t matter if the language or OS handles it underneath; it’s bad coding practice to avoid such trivial – but important – code.
• Methods
  • They give you functionality, in PB there are no methods but a similar concept applies: you have functions or routines that you create specifically for the library itself. Some may be of the Get / Set type (which either get or set a variable) Or other methods such as converters, helpers, accesibility calls, etc.

All together they make a class; in our case a library.

Let’s write one and follow by example!

Imagine you needed to encapsulate the random functions to provide extra functionality, then all you need to do is first define a structure (if you’re going to have members; for instance do you want the library to “remember” the previous and current numbers?, if so you would need a structure!)

;- Library Structure
Structure RANDOM
	LastNumber.i
	PreviousNumber.i
	Seed.i
EndStructure

Alright, now we need to write our constructor and destructor functions! This will create and destroy the instances.

;- Library Instancing
Procedure.i RandomCreate( Seed.i = 0 )
 
	Define.RANDOM *this = AllocateMemory( SizeOf( RANDOM ) )
 
	If *this
 
		If Not Seed
			Seed = ElapsedMilliseconds()
		EndIf
 
		With *this
			 \LastNumber 		= 0
			 \PreviousNumber 	= 0
			 \Seed 			= Seed
		EndWith
 
		RandomSeed( *this\Seed )
		ProcedureReturn *this
 
	EndIf
 
EndProcedure
 
Procedure.i RandomDestroy( *this.RANDOM )
 
	If *this
 
		FreeMemory( *this )
		*this = #Null
		ProcedureReturn *this
 
	EndIf
 
EndProcedure

That’s not too bad, first we allocate an instance and then we populate the member variables just to return the pointer of our new “object”. The destructor simply frees any allocated memory and clears out the pointer itself.

Now we need to define our library functions, in this case we only need one so we may generate a random number and keep track of the previous and current numbers.

;- Library functions
Procedure.i RandomGetInteger( *this.RANDOM, min.i, max.i )
 
	If *this
 
		*this\PreviousNumber 	= *this\LastNumber
		*this\LastNumber 	= ( min + Random( max-min ) )
		ProcedureReturn *this\LastNumber
 
	EndIf
 
EndProcedure

That’s ok, but we can still add functionality. For instance, we need a way to access the structure fields (or “members”) without having to cast pointers, etc. We can do this by implementing a few Get/Set routines. In this case we only need to get the previous and current numbers, so…

;- Helper functions
Procedure.i RandomGetLast( *this.RANDOM )
 
	If *this
		ProcedureReturn *this\LastNumber
	EndIf
 
EndProcedure
 
Procedure.i RandomGetPrevious( *this.RANDOM )
 
	If *this
		ProcedureReturn *this\PreviousNumber
	EndIf
 
EndProcedure

But wait, we can still add functionality! such as utility functions, in this case we would like to fill a given array with random numbers, so…

;- Utility functions
Procedure.i RandomFillArray( *this.RANDOM, min.i, max.i, Array DestArray.i(1) )
 
	If *this
 
		Define.i Size, i
		Size = ArraySize( DestArray(), 1 )
 
		If Size
			For i=0 To Size
				DestArray(i) = RandomGetInteger( *this, min, max )
			Next
		EndIf
 
	EndIf
 
EndProcedure

And while we’re at it, let’s fill lists as well!

Procedure.i RandomFillList( *this.RANDOM, min.i, max.i, elements.i, List DestList.i(), Clear.i=#False )
 
	If *this
 
		If Clear
			ClearList(DestList())
		EndIf
 
		Define.i i
 
		If elements
			For i=1 To elements
				If AddElement( DestList() )
					DestList() = RandomGetInteger( *this, min, max )
				EndIf
			Next
		EndIf
 
	EndIf
 
EndProcedure

If you don’t need to keep track of the current and previous numbers, you can just opt out the instancing system and modify the utility calls to work in an “instance-less” mode, however that’s up to you.

But, let’s take it for a ride first!

;- Example
Define.RANDOM *rnd = RandomCreate()
Define.i i
 
If *rnd
 
	For i=0 To 99
		Debug RandomGetInteger( *rnd, 5, 10 )
	Next
 
	Debug "--"
	Debug RandomGetLast( *rnd )
	Debug RandomGetPrevious( *rnd )
	Debug "--"
 
	Dim TestArray.i(9)
	RandomFillArray( *rnd, 100, 200, TestArray() )
 
	For i=0 To 9
		Debug TestArray(i)
	Next
 
	Debug "--"
 
	NewList TestList.i()
	RandomFillList( *rnd, 10, 20, 5, TestList() )
 
	ForEach TestList()
		Debug TestList()
	Next
 
	RandomDestroy(*rnd)
EndIf

Ok, so we tested the instancing and most if not all of the “methods” we just created. By now you should realize how useful such systems can be if you happen to design them correctly.

This particular lib could be extended to support averaging of the numbers, median / mean, etc. You could even implement a custom PRNG and give the option to choose between yours and the built-in one!.

You may download the entire source from here. As an exercise you could implement the Get/Set methods for the Seed.

Cheers!

PS: Someone remind me to update the language file for GeShi and to fix the font (The indentation is all wrong!)

This example implements a bare-bones n-vector library using a structure and a static array:

Macro Vector_Register( _n, _type )
 
	Structure VECTOR#_n#_type
		vector._type[_n]
	EndStructure
 
	Procedure._type Vector#_n#_type#_Add( *r.VECTOR#_n#_type, *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.i i
		For i=0 To _n - 1
			*r\vector[i] = *a\vector[i] + *b\vector[i]
		Next
	EndProcedure
 
	Procedure._type Vector#_n#_type#_Subtract( *r.VECTOR#_n#_type, *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.i i
		For i=0 To _n - 1
			*r\vector[i] = *a\vector[i] - *b\vector[i]
		Next
	EndProcedure
 
	Procedure._type Vector#_n#_type#_Divide( *r.VECTOR#_n#_type, *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.i i
		For i=0 To _n - 1
			If *b\vector[i] <> 0.0 And *a\vector[i] <> 0.0
				*r\vector[i] = *a\vector[i] / *b\vector[i]
			EndIf
		Next
	EndProcedure
 
	Procedure._type Vector#_n#_type#_Multiply( *r.VECTOR#_n#_type, *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.i i
		For i=0 To _n - 1
			*r\vector[i] = *a\vector[i] * *b\vector[i]
		Next
	EndProcedure
 
	Procedure._type Vector#_n#_type#_DotProduct( *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.i i
		Define._type result
		For i=0 To _n - 1
			result + ( *a\vector[i] * *b\vector[i] )
		Next
		ProcedureReturn result
	EndProcedure
 
	Procedure._type Vector#_n#_type#_Length( *v.VECTOR#_n#_type )
		ProcedureReturn Sqr( Vector#_n#_type#_DotProduct( *v, *v ) )
	EndProcedure
 
	Procedure._type Vector#_n#_type#_Distance( *a.VECTOR#_n#_type, *b.VECTOR#_n#_type )
		Define.VECTOR#_n#_type temp
		Vector#_n#_type#_Subtract( temp, *a, *b )
		ProcedureReturn Vector#_n#_type#_Length( temp )
	EndProcedure
 
	Procedure.s Vector#_n#_type#_Debug( *v.VECTOR#_n#_type, Decimals.i=#PB_Default )
		Define.i i
		Define.s tmp = "["
		For i=0 To _n-1
			tmp + StrF( *v\vector[i], Decimals.i )
			If i <> _n-1
				tmp + ", "
			EndIf
		Next
		tmp + "]"
		Debug tmp
		ProcedureReturn tmp
	EndProcedure
 
EndMacro

It might look strange/complicated at first, but once you read it you’ll realize it’s fairly simple.

Let’s see the usage of this particular template:

Vector_Register(3, f )	; Register a float "vec3".
Define.VECTOR3f a,b,c	; Define a few vectors with the new structure.
 
a\vector[0] = 10.0
a\vector[1] = 20.0
a\vector[2] = 30.0
 
b\vector[0] = 100.0
b\vector[1] = 200.0
b\vector[2] = 300.0
 
Vector3f_Add(c, a, b)	; c = a + b
Vector3f_Debug(c)	; show each element using the debug output.
 
Debug Vector3f_DotProduct( a, b )
Debug Vector3f_Length( a )
Debug Vector3f_Distance( a, b )

Cool, huh?. And you can define any amount of elements with any basic type.

Of course we sacrificed speed for flexibility. In those cases where we have to define n-vectors, this would be an ideal solution. For everything else, I suggest a specific library, such as my vec3 macro lib.

Using this principle you can abstract almost anything, within reason. One good example is my object factory template.  Ideally one would have arrays, lists, etc. Implemented in this very same way, in such case the possibilities would be endless and you’d be able to define dynamic lists/arrays inside structures, etc.

I strongly advice you to implement at least one of those templates, even if it’s just for an exercise.

Having the extra tools can’t hurt!

Cheers.

Whenever you deal with structures and what have you it’s obvious that there has to be a better way of doing it. Think about it, you encapsulate your structure-related code in such a way that it becomes clean, nice and tidy — in other words it makes it easy to understand what it does.

However in essence, you end up writing pretty much the same allocate / deallocate, list, etc. code every time you incorporate a new “class” into your project. Why should we?, let’s avoid it all together and focus our efforts in the task at hand rather than in the mundane stuff.

If you open your eyes you’ll see that this is an obvious pattern but what isn’t so obvious is how do you implement a template that deals with it in an efficient and clean way within the current constraints of the language.

Well… Have no fear, EasyObject is here!
First, download it. Secondly, embrace it.

Third, you’re free to post any comments regarding on how to enhance it if you dear to!.

Ok, now let’s describe this thing a little more and leave the marketing speech in the past.

From the “readme”:

EasyObject is an object factory template for PureBasic. It allows you to register any structure as a “class”. With EasyObject you can define constructors and destructors as well as iterators with ease.

The purpose of EasyObject is mainly to encapsulate trivial and redundant code usually regarded to allocation, deallocation and keeping track of the objects. The usage is fairly simple: classes can be registered and unregistered. Once a class has been registered, we can create new objects and delete them at will. If we decide to unregister a class, all of the objects will be freed and their respective destructors will be called.

More from where that came from…

Macros in this case are used as an aid to define templates (like you would in C++ for instance). There are certain limitations that forced me to design the template as it is right now but the usage is very simple. We’re not trying to mimic any language here but rather provide a way of dealing with objects without having to write redundant code all the time. Because overloading doesn’t exist in PB, the constructor will be called twice (once by the template and once by yourself) if you want to define the members using said ctor, just make certain that any dynamic allocations are performed only once or you’ll have a nasty memory leak in your hands.

It’s clear that some limitations are present in the template but for most of the tasks this is a great addition to anyone’s code.

Let me know if you find any bugs!

Cheers,
GuShH