A freelist is used to return an unreserved identity number from a sequencial list. These identity numbers can be used to provide unique identities for similar resources in your software. These numbers can also be used to represent other numerical representations, where such numbers can be reserved or consumed.
Freelists share similarities with the Matrix1 'Reserve Free' functions, the difference is that freelists are not exclusive to DarkBASIC resources such as images or sprites.
A freelist can contain numbers from 1 to the highest number the freelist can return which is 2147483646. Freelists can also be limited to a smaller range from the lowest and highest figure you specify.
A freelist identity number is either free or reserved. When a freelist ranging from 1 to 10 has no reserved identities, the following command returns 1:
GET FROM FREELIST( FREELIST_ID ) --> 1
When a freelist ranging from 1 to 10 contains no reserved identities, the following command requests any available number from 5 with the range set by the range parameter, starting with just 1 number. Since all numbers are free, it will return the first number tested which is 5
GET FROM FREELIST( FREELIST_ID, 5, 1) --> 5
The identity number you obtain using the GET FROM FREELIST command is reserved; therefore you will not get this ID number again until it is returned to the list. The following commands return different numbers because of this.
GET FROM FREELIST( FREELIST_ID ) --> 1
GET FROM FREELIST( FREELIST_ID ) --> 2
GET FROM FREELIST( FREELIST_ID ) --> 3
If you had a freelist limited with the range of 1 to 2, the third time you run the previously demonstrated code you would not have the number 3 returned because it is out of range, and all numbers have been reserved.
When all numbers have been used; a default number is returned instead, which is called the 'Not Found' number. The default number will be zero, unless you specify otherwise with the MAKE FREELIST command.
You can return a reserved identity back into the freelist using the RETURN TO FREELIST command.
`%Project Title%
`%Source File Name%
`======================
Set Text Size 30
Set Text Font "Arial"
Make Freelist 1, 1, 2
Print "First available ID is "; Get From Freelist(1)
Print "Next available ID is "; Get From Freelist(1)
Print "Is ID 3 available in this list? 0 = No, 1 = Yes --> "; Available In Freelist ( 1, 2 )
Print "The ID given when all have been reserved: "; Get From Freelist(1)
Print
Nice Wait 5000
Make Freelist 2, 1, 5, 10
Print "A new freelist from the range of 1 to 5, with a not found value of 10"
Print "First available ID is "; Get From Freelist(2)
Print "And the next available ID is "; Get From Freelist(2)
Print "And the next one is "; Get From Freelist(2)
Print "And the next one is "; Get From Freelist(2)
Print "And the next one is "; Get From Freelist(2)
Print "And the next one is "; Get From Freelist(2)
Print "10 has been returned where none are available"
Print
Nice Wait 5000
Print "Now returning the first 2 numbers to freelist 2"
Return To Freelist 2, 1
Return To Freelist 2, 2
Print "The next returned ID makes the following number available "; Get From Freelist(2)
Print "And the next available ID is "; Get From Freelist(2)
Print "When we try again there are none left, so we get "; Get From Freelist(2); " with the failed attempt"
Nice Wait 1000
Print
Print "Press any key to exit"
Wait Key
I use the freelist to generate identities for my 3D entities in Sports Fiction; I am planning to use it to make random pools for returning random consumable numbers for fictional sport features.
