# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

=encoding utf8

=head1 NAME

Clownfish::String - Immutable string holding Unicode characters.

=head1 SYNOPSIS

    my $string = Clownfish::String->new('abc');
    print $string->to_perl, "\n";

=head1 DESCRIPTION

=head1 CONSTRUCTORS

=head2 new

    my $string = Clownfish::String->new($perl_string);

Return a String containing the passed-in Perl string.

=head1 METHODS

=head2 cat

    my $result = $string->cat($other);

Return the concatenation of the String and C<other>.

=head2 to_i64

    my $int = $string->to_i64();

Extract a 64-bit integer from a decimal string.  See L<basex_to_i64()|/basex_to_i64>
for details.

=head2 basex_to_i64

    my $int = $string->basex_to_i64($base);

Extract a 64-bit integer from a variable-base stringified version.
Expects an optional minus sign followed by base-x digits, stopping at
any non-digit character.  Returns zero if no digits are found.  If the
value exceeds the range of an C<int64_t>, the result is undefined.

=over

=item *

B<base> - A base between 2 and 36.

=back

=head2 to_f64

    my $float = $string->to_f64();

Convert a string to a floating-point number using the C library
function C<strtod>.

=head2 starts_with

    my $bool = $string->starts_with($prefix);

Test whether the String starts with C<prefix>.

=head2 ends_with

    my $bool = $string->ends_with($suffix);

Test whether the String ends with C<suffix>.

=head2 contains

    my $bool = $string->contains($substring);

Test whether the String contains C<substring>.

=head2 find

    my $string_iterator = $string->find($substring);

Return a L<StringIterator|Clownfish::StringIterator> pointing to the first occurrence of
C<substring> within the String, or undef if the substring does not
match.

=head2 length

    my $int = $string->length();

Return the number of Unicode code points the String contains.

=head2 get_size

    my $int = $string->get_size();

Return the number of bytes occupied by the String’s internal content.

=head2 to_bytebuf

    my $byte_buf = $string->to_bytebuf();

Return a ByteBuf which holds a copy of the String.

=head2 clone

    my $result = $string->clone();

Return a clone of the object.

=head2 compare_to

    my $int = $string->compare_to($other);

Indicate whether one String is less than, equal to, or greater than
another.  The Unicode code points of the Strings are compared
lexicographically.  Throws an exception if C<other> is not a String.

Returns: 0 if the Strings are equal, a negative number if C<self> is less
than C<other>, and a positive number if C<self> is greater than C<other>.

=head2 trim

    my $result = $string->trim();

Return a copy of the String with Unicode whitespace characters
removed from both top and tail.  Whitespace is any character that has
the Unicode property C<White_Space>.

=head2 trim_top

    my $result = $string->trim_top();

Return a copy of the String with leading Unicode whitespace
removed. Whitespace is any character that has the Unicode property
C<White_Space>.

=head2 trim_tail

    my $result = $string->trim_tail();

Return a copy of the String with trailing Unicode whitespace
removed. Whitespace is any character that has the Unicode property
C<White_Space>.

=head2 code_point_at

    my $int = $string->code_point_at($tick);

Return the Unicode code point located C<tick> code points in from the
top.  Return C<CFISH_STR_OOB> if out of bounds.

=head2 code_point_from

    my $int = $string->code_point_from($tick);

Return the Unicode code point located C<tick> code points counting
backwards from the end.  Return C<CFISH_STR_OOB> if out of bounds.

=head2 substring

    my $result = $string->substring(
        offset => $offset,  # required
        length => $length,  # required
    );

Return a new substring containing a copy of the specified range.

=over

=item *

B<offset> - Offset from the top, in code points.

=item *

B<length> - The desired length of the substring, in code points.

=back

=head2 top

    my $string_iterator = $string->top();

Return an iterator initialized to the start of the string.

=head2 tail

    my $string_iterator = $string->tail();

Return an iterator initialized to the end of the string.

=head1 INHERITANCE

Clownfish::String isa L<Clownfish::Obj>.

=cut