| 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 |