blib/lib/SPVM/StringBuffer.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::StringBuffer;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::StringBuffer - String Buffers
8  
9 =head1 Description
10  
11 The StringBuffer class in L<SPVM> has methods to manipulate string buffers.
12  
13 =head1 Usage
14
15 use StringBuffer;
16
17 # new
18 my $buffer = StringBuffer->new;
19
20 my $buffer = StringBuffer->new("abc");
21
22 # push string
23 $buffer->push("def");
24
25 # Convert to the string
26 my $string = $buffer->to_string;
27  
28 =head1 Details
29  
30 =head2 Internal Data Structure
31  
32 The L</"string"> stored in a StringBuffer object always starts at index 0.
33  
34 The charactors in the range that is greater than or equal to L</"length"> field and less than L</"capacity"> field are filled with "\0".
35  
36 =head1 Interfaces
37  
38 =over 2
39  
40 =item * L<Cloneable|SPVM::Cloneable>
41  
42 =item * L<Comparable|SPVM::Comparable>
43  
44 =item * L<EqualityCheckable|SPVM::EqualityCheckable>
45  
46 =back
47  
48 =head1 Fields
49  
50 =head2 capacity
51  
52 C<has capacity : virtual ro int;>
53  
54 The capacity. This is the length of the internally reserved characters to extend the length of the string buffer.
55  
56 =head2 length
57  
58 C<has length : virtual ro int;>
59  
60 The length of the string buffer.
61  
62 =head2 string
63  
64 C<has string : mutable string;>
65  
66 The internal string stored in the StringBuffer object.
67  
68 =head1 Class Methods
69  
70 =head2 new
71  
72 C<static method new : L<StringBuffer|SPVM::StringBuffer> ($string : string = undef, $capacity : int = -1);>
73  
74 Creates a new C<StringBuffer> object using L</"new_len">.
75  
76 The passed $length to L</"new_len"> is the length of $string. If the string is undef, it is 0.
77  
78 $string is copied to the value of the the created string buffer.
79  
80 =head2 new_len
81  
82 C<static method new_len : L<StringBuffer|SPVM::StringBuffer> ($length : int, $capacity : int = -1);>
83  
84 Creates a new C<StringBuffer> object with $length and $capacity.
85  
86 If $capacity is less than 0, $capacity is set to an appropriate value.
87  
88 If $length is greater than $capacity, $capacity is set to $length.
89  
90 Exceptions:
91  
92 $length must be greater than or equal to 0. Otherwise an exception is thrown.
93  
94 =head2 new_ref
95  
96 C<static method new_ref : L<StringBuffer|SPVM::StringBuffer> ($string : mutable string);>
97  
98 Creates a new L<StringBuffer|SPVM::StringBuffer> object, and set L</"string"> field to the string $string, and return the new object.
99  
100 Exceptions:
101  
102 The array $array must be defined. Otherwise an exception is thrown.
103  
104 =head1 Instance Methods
105  
106 =head2 push
107  
108 C<method push : void ($string : string, $offset : int = 0, $length : int = -1);>
109  
110 Adds a $string from $offset to the position proceeded by $length after the end of the string in the string buffer.
111  
112 Exceptions:
113  
114 $string must be defined. Otherwise an exception is thrown.
115  
116 $offset must be greater than or equal to 0. Otherwise an exception is thrown.
117  
118 $offset + $length must be less than or equal to the length of $string. Otherwise an exception is thrown.
119  
120 =head2 push_char
121  
122 C<method push_char : void ($char : int);>
123  
124 Adds Ascii $char after the end of the string in the string buffer.
125  
126 =head2 reserve
127  
128 C<method reserve : void ($new_capacity : int);>
129  
130 Reserves the characters that size is $new_capacity.
131  
132 If $new_capacity is greater than the capacity of the string buffer, the capacity of the string buffer is extended to $new_capacity.
133  
134 Exceptions:
135  
136 $new_capacity must be greater than or equal to 0. Otherwise an exception is thrown.
137  
138 =head2 to_string
139  
140 C<method to_string : string ();>
141  
142 Creates a new string with the length of the buffer and copies all characters in the buffer into the new string, and returns it.
143  
144 =head2 get_string
145  
146 C<method get_string : string ();>
147  
148 Returns the internal L</"string">.
149  
150 =head2 set_length
151  
152 C<method set_length : void ($length : int);>
153  
154 Sets L</"length"> fields.
155  
156 If the length $length is greater than L</"length"> field, the characters of the exceeding part are filled with "\0".
157  
158 =head2 set
159  
160 C<method set : void ($string : string);>
161  
162 Sets the string $string.
163  
164 =head2 compare_string
165  
166 C<method compare_string : int ($string : string);>
167  
168 The return value is the same as the return value of C<cmp> operator given C<$self-E<gt>to_string> and $string.
169  
170 =head2 equals_string
171  
172 C<method equals_string : int ($string : string);>
173  
174 If the string contained in the StringBuffer instance is equal to the string $string, returns 1, otherwise returns 0.
175  
176 =head2 clone
177  
178 C<method clone ();>
179  
180 Clones this string buffer and returns it.
181  
182 This method is a method implementation for L<Cloneable|SPVM::Cloneable> interface.
183  
184 =head2 cmp
185  
186 C<method cmp : int ($a : L<StringBuffer|SPVM::StringBuffer>, $b : L<StringBuffer|SPVM::StringBuffer>);>
187  
188 Compares two L<StringBuffer|SPVM::StringBuffer> and returns its result.
189  
190 The return value is the same as the return value of C<cmp> operator given C<$a-E<gt>to_string> or undef(if $a is undef) and C<$b-E<gt>to_string> or undef(if $b is undef).
191  
192 This method is a method implementation for L<Comparable|SPVM::Comparable> interface.
193  
194 =head2 eq
195  
196 C<method eq : int ($a : L<StringBuffer|SPVM::StringBuffer>, $b : L<StringBuffer|SPVM::StringBuffer>);>
197  
198 Checks if $a is equal to $b, and returns its result.
199  
200 Implementation:
201  
202 If $a and $b is defined, calls L</"cmp"> method. If the return value is 0, returns 1, otherwise 0.
203  
204 If only $a is not defined, returns 0.
205  
206 If only $b is not defined, returns 0.
207  
208 If both $a and $b is not defined, returns 1.
209  
210 This method is a method implementation for L<EqualityCheckable|SPVM::EqualityCheckable> interface.
211  
212 =head2 substr
213  
214 C<method substr : string ($offset : int, $length : int = -1, $replacement : string = undef);>
215  
216 Calls L<Fn#substr|SPVM::Fn/"substr"> method given the value of L</"string"> field, $offset, $length, and returns its return value.
217  
218 If the replacement string $replacement is specified, also calls L</"replace"> method.
219  
220 Exceptions:
221  
222 The offset $offset + the length $length must be less than or equal to the value of length field. Otherwise an exception is thrown.
223  
224 Exceptions thrown by L<Fn#substr|SPVM::Fn/"substr"> method could be thrown.
225  
226 =head2 index
227  
228 C<method index : int ($substring : string, $begin : int = 0, $end : int = -1);>
229  
230 Calls L<Fn#index|SPVM::Fn/"index"> method given L</"string"> field, $substring, $bigen, $end, and retunrs its return value.
231  
232 If $end is less than 0, it is set to the value of L</"length"> field.
233  
234 Exceptions:
235  
236 The begin $begin must be between 0 and the length of string field. Otherwise an exception is thrown.
237  
238 The end $end must be less than or equal to the length of string field. Otherwise an exception is thrown.
239  
240 Exceptions thrown by L<Fn#index|SPVM::Fn/"index"> method could be thrown.
241  
242 =head2 contains
243  
244 C<static method contains : int ($substring : string, $begin : int = 0, $end : int = -1);>
245  
246 Checks if L</"string"> field contains $substring.
247  
248 Implementation:
249  
250 The alias for the following code using L</"index"> method.
251  
252 my $ret = $self->index($substring, $begin, $end) >= 0;
253  
254 Exceptions:
255  
256 Exceptions thrown by L</"index"> method could be thrown.
257  
258 =head1 Copyright & License
259  
260 Copyright (c) 2023 Yuki Kimoto
261  
262 MIT License