3 * =============================================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _adt_trie_included
36 #define _adt_trie_included
39 * Creates a Trie structure. A trie is a data storage object that maps any value to a
40 * string of text. It features very fast lookup and deletion, but grows very slow for
41 * insertion once tens of thousands of items are added.
43 * Keys in Tries are unique. That is, each key may only have one value. Unlike arrays,
44 * Tries cannot be iterated right now. Since the contents are known to be unique, to
45 * work around this, you can use ADT Arrays to store a list of keys known to be in a
48 * @return New Trie Handle, which must be freed via CloseHandle().
50 native Handle:CreateTrie();
53 * Sets a value in a Trie, either inserting a new entry or replacing an old one.
55 * @param trie Trie Handle.
56 * @param key Key string.
57 * @param value Value to store at this key.
58 * @param replace If false, operation will fail if the key is already set.
59 * @return True on success, false on failure.
60 * @error Invalid Handle.
62 native bool:SetTrieValue(Handle:trie, const String:key[], any:value, bool:replace=true);
65 * Sets an array value in a Trie, either inserting a new entry or replacing an old one.
67 * @param trie Trie Handle.
68 * @param key Key string.
69 * @param array Array to store.
70 * @param num_items Number of items in the array.
71 * @param replace If false, operation will fail if the key is already set.
72 * @return True on success, false on failure.
73 * @error Invalid Handle.
75 native bool:SetTrieArray(Handle:trie, const String:key[], const array[], num_items, bool:replace=true);
78 * Sets a string value in a Trie, either inserting a new entry or replacing an old one.
80 * @param trie Trie Handle.
81 * @param key Key string.
82 * @param array Array to store.
83 * @param num_items Number of items in the array.
84 * @param replace If false, operation will fail if the key is already set.
85 * @return True on success, false on failure.
86 * @error Invalid Handle.
88 native bool:SetTrieString(Handle:trie, const String:key[], const String:value[], bool:replace=true);
91 * Retrieves a value in a Trie.
93 * @param trie Trie Handle.
94 * @param key Key string.
95 * @param val Variable to store value.
96 * @return True on success. False if the key is not set, or the key is set
97 * as an array or string (not a value).
98 * @error Invalid Handle.
100 native bool:GetTrieValue(Handle:trie, const String:key[], &any:value);
103 * Retrieves an array in a Trie.
105 * @param trie Trie Handle.
106 * @param key Key string.
107 * @param array Buffer to store array.
108 * @param max_size Maximum size of array buffer.
109 * @param size Optional parameter to store the number of elements written to the buffer.
110 * @return True on success. False if the key is not set, or the key is set
111 * as a value or string (not an array).
112 * @error Invalid Handle.
114 native bool:GetTrieArray(Handle:trie, const String:key[], array[], max_size, &size=0);
117 * Retrieves a string in a Trie.
119 * @param trie Trie Handle.
120 * @param key Key string.
121 * @param value Buffer to store value.
122 * @param max_size Maximum size of string buffer.
123 * @param size Optional parameter to store the number of bytes written to the buffer.
124 * @return True on success. False if the key is not set, or the key is set
125 * as a value or array (not a string).
126 * @error Invalid Handle.
128 native bool:GetTrieString(Handle:trie, const String:key[], String:value[], max_size, &size=0);
131 * Removes a key entry from a Trie.
133 * @param trie Trie Handle.
134 * @param key Key string.
135 * @return True on success, false if the value was never set.
136 * @error Invalid Handle.
138 native RemoveFromTrie(Handle:trie, const String:key[]);
141 * Clears all entries from a Trie.
143 * @param trie Trie Handle.
144 * @error Invalid Handle.
146 native ClearTrie(Handle:trie);
149 * Retrieves the number of elements in a trie.
151 * Note that trie items are not enumerable/iteratable. If you need to
152 * retrieve the elements in a trie, store its keys in an ADT Array.
154 * @param trie Trie Handle.
155 * @return Number of elements in the trie.
156 * @error Invalid Handle.
158 native GetTrieSize(Handle:trie);
