File Coverage

=head1 NAME

src/pmc/string.pmc - String PMC Class

=head1 DESCRIPTION

C<String> extends C<scalar> to provide a string for languages that want a
C<string> type without going to an S register.  It acts as a wrapper for the
functions in F<src/string.c>.

=head2 Methods

=over 4

=cut

=item C<void init()>

Initializes the string.

=cut

=item C<PMC instantiate_str(STRING *rep)>

Class method to construct a String from the string representation C<rep>.

=cut

=item C<void mark()>

Marks the string as live.

=cut

=item C<PMC *clone()>

Creates a copy of the string.

=cut

=item C<INTVAL get_integer()>

Returns the integer representation of the string.

=cut

=item C<FLOATVAL get_number()>

Returns the floating-point representation of the string.

=cut

=item C<PMC *get_bignum()>

Returns the big numbers representation of the string.

=cut

=item C<STRING *get_string()>

Returns the string itself.

=cut

=item C<INTVAL get_bool()>

Returns the boolean value of the string.

=cut

=item C<VOID set_integer_native(INTVAL value)>

=item C<VOID set_bool(INTVAL value)>

Sets the value of the string to the integer C<value>.

=cut

=item C<VOID set_number_native(FLOATVAL value)>

Sets the value of the string to the floating-point C<value>.

=cut

=item C<VOID set_string_native(STRING *value)>

Sets the value of the string to that of the specified C<string>.

=cut

=item C<VOID assign_string_native(STRING *value)>

Sets the value of the string to a copy of the specified C<string>.

=cut

=item C<VOID set_pmc(PMC *value)>

Sets the value of the string to the string value of
the specified C<PMC>.

=cut

=item C<PMC *bitwise_ors(PMC *value, PMC *dest)>

=item C<PMC *bitwise_ors_str(PMC *value, PMC *dest)>

=item C<PMC *bitwise_ands(PMC *value, PMC *dest)>

=item C<PMC *bitwise_ands_str(PMC *value, PMC *dest)>

=item C<PMC *bitwise_xors(PMC *value, PMC *dest)>

=item C<PMC *bitwise_xors_str(PMC *value, PMC *dest)>

=item C<void bitwise_nots(PMC *value)>

These functions perform bitwise operations on entire
strings, and place the result in C<dest>.

=item C<void i_bitwise_ors(PMC *value)>

=item C<void i_bitwise_ors_str(PMC *value)>

=item C<void i_bitwise_ands(PMC *value)>

=item C<void i_bitwise_ands_str(PMC *value)>

=item C<void i_bitwise_xors(PMC *value)>

=item C<void i_bitwise_xors_str(PMC *value)>

=item C<void i_bitwise_nots(PMC *value)>

These functions perform bitwise operations on entire
strings in place.

=cut

=item C<INTVAL is_equal(PMC *value)>

Compares the string with C<value>; returns true if
they match.

=cut

=item C<INTVAL is_equal_num(PMC *value)>

Compares the numerical value of the string with that of
C<value>; returns true if they match.

=cut

=item C<INTVAL is_equal_string(PMC *value)>

Compares the string with C<value>; returns FALSE if they match.

=cut

=item C<INTVAL cmp(PMC *value)>

Compares the string with C<value>; returns -1 if the
string is smaller, 0 if they are equal, and 1 if C<value>
is smaller.

=cut

=item C<INTVAL cmp_num(PMC *value)>

Compares the numerical value of the string with that of
C<value>; returns -1 if the string is smaller, 0 if they
are equal, and 1 if C<value> is smaller.

=cut

=item C<INTVAL cmp_string(PMC *value)>

Compares the string with C<value>; returns -1 if the
string is smaller, 0 if they are equal, and 1 if C<value>
is smaller.

=cut

=item C<void substr(INTVAL offset, INTVAL length, PMC *dest)>

Extracts the substring starting at C<offset>, with size
C<length>, and places it in C<dest>.

=cut

=item C<STRING *substr_str(INTVAL offset, INTVAL length)>

Extracts the substring starting at C<offset>, with size
C<length>, and returns it.

=cut

=item C<INTVAL exists_keyed(PMC *key)>

Returns true if the C<key>'th character in the string exists. Negative
numbers count from the end.

=cut

=item C<STRING *get_string_keyed(PMC *key)>

Returns the C<key>'th character in the string. Negative numbers count
from the end.

=item C<INTVAL get_integer_keyed(PMC *key)>

Returns the integer value (ord) at C<*key>.

=item C<void set_string_keyed(PMC *key, STRING *val)>

Replace the string at C<key> with C<value>.

=item C<void set_integer_keyed(PMC *key, INTVAL val)>

Replace the string at C<key> with the chr of C<value>.

=cut

=item C<void replace(STRING *orig, STRING *_new)>

Replace every occurrence of C<orig> with C<_new>.

=cut

=item C<PMC *to_int(INTVAL base)>

Return the integer equivalent of SELF, which is assumed to be a C<base>
digit string. The String is assumed to be in an ascii-compatible encoding.
The String is considered being unsigned, and no I<+> or I<-> chars are
processed. C<base> has to be within [2..36].

If any chars in the String aren't converted, an exception is thrown.

TODO Currently overflow to BigInt is B<not> handled nor detected.

=cut

=head2 Iterator Interface

=over 4

=item C<PMC *slice(PMC *key, INTVAL f)>

Return a new iterator for the slice PMC C<key> if f==0.

Return a new pythonic slice if f == 1.

=item C<PMC *get_iter(PMC *key)>

Return a new iterator for this string.

=item C<INTVAL elements()>

Return length of the string.


=cut

=head2 Freeze/thaw Interface

=over 4

=item C<void freeze(visit_info *info)>

Used to archive the string.

=cut

=item C<void thaw(visit_info *info)>

Used to unarchive the string.

=cut

=head2 NCI methods

=over 4

=item C<PMC *lower()>

Downcase this string

=cut

=item C<void trans(STRING *src, PMC *trams_table)>

Translate ascii string C<src> with entries from C<trans_table>.

=cut

=item C<void reverse(STRING *src)>

Reverse the ascii STRING C<src> in place.

=cut

=item C<INTEGER is_integer(STRING *src)>

Checks if the ascii STRING C<str> is just an integer.

=cut

=item C<INTEGER reverse_index(STRING *substring, INTVAL start)>

Find last occurrence of C<substring>, but not after the C<start> position.

=cut