blib/lib/SPVM/Hash.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package SPVM::Hash;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::Hash - Hash (Associative Array)
8  
9 =head1 Description
10  
11 Hash class in L<SPVM> represents hashes(associative arrays).
12  
13 =head1 Usage
14
15 use Hash;
16
17 my $book = Hash->new;
18 my $book = Hash->new({id => 4, name => "Perl", price => 3000.0});
19
20 $book->set(id => 4);
21 $book->set(name => "Perl");
22 $book->set(price => 3000.0);
23 $book->set(point => Point->new(1, 2));
24
25 my $id = $book->get("id")->(int);
26 my $name = $book->get("name")->(string);
27 my $price = $book->get("price")->(double);
28 my $point = $book->get("point")->(Point);
29
30 if ($hash->exists("id")) {
31
32 }
33
34 # Use hash access syntax
35 $book->{"id"} = 4;
36 $book->{"name"} = "Perl";
37 $book->{"price"} = 3000.0;
38 $book->{"point"} = Point->new(1, 2);
39
40 my $id = $book->{"id"}->(int);
41 my $name = $book->{"name"}->(string);
42 my $price = $book->{"price"}->(double);
43 my $point = $book->{"point"}->(Point);
44
45 =head1 Details
46  
47 =head2 Hash Algorithm
48  
49 The hash function used in C<SPVM::Hash> is B<SipHash-1-3>.
50  
51 SipHash-1-3 is a fast and cryptographically strong hash function designed for short inputs, such as hash table keys. It is widely adopted by modern programming languages (e.g., Python, Ruby, Rust) to provide high performance while ensuring security.
52  
53 =head2 Security
54  
55 By using SipHash-1-3 with a seed generated from OS-specific secure random bytes (CSPRNG), this class is resistant to B<Hash DOS attacks> (hash collision attacks). Each C<Hash> instance has its own unique seed, making it practically impossible for an attacker to predict collisions and degrade performance.
56  
57 =head2 Performance
58  
59 While being secure, SipHash-1-3 is highly optimized for 64-bit CPUs and offers excellent performance for common hash table operations compared to older, less secure algorithms.
60  
61 =head1 Interfaces
62  
63 =over 2
64  
65 =item * L<Cloneable|SPVM::Cloneable>
66  
67 =back
68  
69 =head1 Fields
70  
71 =head2 keys_length
72  
73 has keys_length : ro int;
74  
75 The length of the keys in the hash.
76  
77 =head1 Class Methods
78  
79 =head2 new
80  
81 C<static method new : L<Hash|SPVM::Hash> ($key_values : object[] = undef);>
82  
83 Creates a new L<Hash|SPVM::Hash> object given key-value pairs $key_values.
84  
85 Examples:
86  
87 my $book = Hash->new;
88 my $book = Hash->new({});
89 my $book = Hash->new({id => 4, name => "Perl"});
90  
91 =head2 new_from_keys
92  
93 C<static method new_from_keys : void ($keys : string[], $value : object);>
94  
95 Creates a new hash with the keys $keys and the value $value shared by all keys, and returns the new hash.
96  
97 Exceptions:
98  
99 The keys $keys must be defined. Otherwise an exception is thrown.
100  
101 =head1 Instance Methods
102  
103 =head2 copy
104  
105 C<method copy : L<Hash|SPVM::Hash> ();>
106  
107 Creates a new L<Hash|SPVM::Hash> object, and copies the keys and values of the current hash to the new hash, and returns it.
108  
109 This is not deep copy. The keys are got by L</"keys"> method. The values are got by L</"get"> method.
110  
111 =head2 clone
112  
113 C<method clone : L<Hash|SPVM::Hash> ();>
114  
115 The alias for L</"copy"> method.
116  
117 =head2 delete
118  
119 C<method delete : element ($key : string);>
120  
121 Deletes the key and value given by the key $key.
122  
123 The deleted value is returned.
124  
125 Exceptions:
126  
127 The key $key must be defined. Otherwise, an exception is thrown.
128  
129 =head2 exists
130  
131 C<method exists : int ($key : string);>
132  
133 Checks if the value specified by the key $key exists. If it exists, returns 1. Otherwise returns 0.
134  
135 =head2 keys
136  
137 C<method keys : string[] ();>
138  
139 Gets the keys in the hash. This method does not copy the strings.
140  
141 =head2 values
142  
143 C<method values : object[] ();>
144  
145 Gets all the values in the hash.
146  
147 =head2 get
148  
149 C<method get : element ($key : string);>
150  
151 Gets the value specifed by the key $key, and returns it.
152  
153 If the value does not exist, returns undef.
154  
155 Exceptions:
156  
157 The key $key must be defined. Otherwise, an exception is thrown.
158  
159 =head2 weaken
160  
161 C<method weaken : void ($key : string));>
162  
163 Enables a weaken reference of the field that stores the value specifed by the key $key if the value exists.
164  
165 Exceptions:
166  
167 The key $key must be defined. Otherwise, an exception is thrown.
168  
169 =head2 unweaken
170  
171 C<method unweaken : void ($key : string);>
172  
173 Disables a weaken reference of the field that stores the value specifed by the key $key if the value exists.
174  
175 Exceptions:
176  
177 The key $key must be defined. Otherwise, an exception is thrown.
178  
179 =head2 isweak
180  
181 C<method isweak : int ($key : string)>
182  
183 If the field that stores the value specifed by the key $key is weakened, returns 1, otherwise returns 0.
184  
185 Exceptions:
186  
187 The key $key must be defined. Otherwise, an exception is thrown.
188  
189 =head2 set
190
191 C<method set : void ($key : string, $value : object);>
192  
193 Sets $value to the hash by the key $key.
194  
195 Exceptions:
196  
197 The key $key must be defined. Otherwise, an exception is thrown.
198  
199 =head2 to_array
200  
201 C<method to_array : object[] ($sort : int = 0);>
202  
203 Converts all the key-value pairs in the hash to an array, and returns it.
204  
205 If the option $sort is a positive value, the keys are sorted by ascendant order.
206  
207 If the option $sort is a negative value, the keys are sorted by decendant order.
208  
209 =head2 to_options
210  
211 C<method to_options : object[] ($sort : int = 0);>
212  
213 Same as L</"to_array"> method, but enables options flag using C<enable_options> operator.
214  
215 =head2 get_or_default
216  
217 C<method get_or_default : element ($key : string, $default : object;>
218  
219 If the value specified by the key $key exists, this method calls L</"get"> method
220 , and returns the return value of L</"get"> method.
221  
222 If the value specified by the key $key does not exists, returns the default value $default.
223  
224 =head2 merge
225  
226 C<method merge : void ($hash : Hash);>
227  
228 Merges the hash $hash into the current hash.
229  
230 =head2 merge_options
231  
232 C<method merge_options : void ($options : object[]);>
233
234 Merges the options $options into the current hash.
235  
236 =head1 Copyright & License
237  
238 Copyright (c) 2023 Yuki Kimoto
239  
240 MIT License