Arma3_Epoch/ACE3
1
0
Fork 0
mirror of https://github.com/acemod/ACE3.git synced 2024-08-30 18:23:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation - Remove Hashes from Coding guidelines (#10072)

Browse Source 
Remove Hashes from Coding guidelines
This commit is contained in:
Mike-MF 2024-06-14 22:21:53 +01:00 committed by GitHub
parent 7a6c837f1b
commit 2dc0cd4fc4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 0 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/wiki/development/coding-guidelines.md
View File

@ -632,81 +632,6 @@ player addEventHandler ["Fired", FUNC(handleFired)]; // bad
player addEventHandler ["Fired", {call FUNC(handleFired)}]; // good
```
### 7.4 Hashes
When a key value pair is required, make use of the hash implementation from ACE3.
Hashes are a variable type that store key value pairs. They are not implemented natively in SQF, so there are a number of macros and functions for their usage in ACE3. If you are unfamiliar with the idea, they are similar in function to `setVariable`/`getVariable` but do not require an object to use.
The following example is a simple usage using our macros which will be explained further below.
```sqf
_hash = HASHCREATE;
HASH_SET(_hash,"key","value");
if (HASH_HASKEY(_hash,"key")) then {
player sideChat format ["val: %1", HASH_GET(_hash,"key"); // will print out "val: value"
};
HASH_REM(_hash,"key");
if (HASH_HASKEY(_hash,"key")) then {
// this will never execute because we removed the hash key/val pair "key"
};
```
A description of the above macros is below.
| Macro | Use |
| ------|-------|
|`HASHCREATE` | Used to create an empty hash. |
|`HASH_SET(hash,key,val)` | Will set the hash key to that value, a key can be anything, even objects. |
|`HASH_GET(hash,key)` | Will return the value of that key (or nil if it doesn't exist). |
|`HASH_HASKEY(hash,key)` | Will return true/false if that key exists in the hash. |
|`HASH_REM(hash,key)` | Will remove that hash key. |
#### 7.4.1 Hashlists
A hashlist is an extension of a hash. It is a list of hashes! The reason for having this special type of storage container rather than using a normal array is that an array of normal hashes that are similar will duplicate a large amount of data in their storage of keys. A hashlist on the other hand uses a common list of keys and an array of unique value containers. The following will demonstrate its usage.
```sqf
_defaultKeys = ["key1", "key2", "key3"];
// create a new hashlist using the above keys as default
_hashList = HASHLIST_CREATELIST(_defaultKeys);
//lets get a blank hash template out of this hashlist
_hash = HASHLIST_CREATEHASH(_hashList);
//_hash is now a standard hash...
HASH_SET(_hash,"key1","1");
//to store it to the list we need to push it to the list
HASHLIST_PUSH(_hashList, _hash);
//now lets get it out and store it in something else for fun
//it was pushed to an empty list, so it's index is 0
_anotherHash = HASHLIST_SELECT(_hashList,0);
// this should print "val: 1"
player sideChat format["val: %1", HASH_GET(_anotherHash,"key1")];
//Say we need to add a new key to the hashlist
//that we didn't initialize it with? We can simply
//set a new key using the standard HASH_SET macro
HASH_SET(_anotherHash,"anotherKey","another value");
```
As you can see above working with hashlists are fairly simple, a more in depth explanation of the macros is below.
| Macro | Use |
| -------|---------|
|`HASHLIST_CREATELIST(keys)` | Creates a new hashlist with the default keys, pass [] for no default keys. |
|`HASHLIST_CREATEHASH(hashlist)` | Returns a blank hash template from a hashlist. |
|`HASHLIST_PUSH(hashList, hash)` | Pushes a new hash onto the end of the list. |
|`HASHLIST_SELECT(hashlist, index)` | Returns the hash at that index in the list. |
|`HASHLIST_SET(hashlist, index, hash)` | Sets a specific index to that hash. |
##### 7.4.1.1 A note on pass by reference and hashes
Hashes and hashlists are implemented with SQF arrays, and as such they are passed by reference to other functions. Remember to make copies (using the `+` operator) if you intend for the hash or hashlist to be modified with out the need for changing the original value.
## 8. Performance Considerations
### 8.1 Adding Elements to Arrays