# ***********************************************
# 
# !!!! 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::StringIterator - Iterate Unicode code points in a String.

=head1 SYNOPSIS

    my $iter = $string->top;
    while (my $code_point = $iter->next) {
        ...
    }

=head1 DESCRIPTION

=head1 METHODS

=head2 clone

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

Return a clone of the object.

=head2 assign

    $string_iterator->assign($other);

Assign the source string and current position of C<other> to C<self>.

=head2 compare_to

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

Indicate whether one StringIterator is less than, equal to, or
greater than another by comparing their character positions. Throws an
exception if C<other> is not a StringIterator pointing to the same
source string as C<self>.

Returns: 0 if the StringIterators 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 has_next

    my $bool = $string_iterator->has_next();

Return true if the iterator is not at the end of the string.

=head2 has_prev

    my $bool = $string_iterator->has_prev();

Return true if the iterator is not at the start of the string.

=head2 next

    my $code_point = $iter->next;

Return the code point after the current position and advance the
iterator. Returns undef at the end of the string. Returns zero
but true for U+0000.

=head2 prev

    my $code_point = $iter->prev;

Return the code point before the current position and go one step back.
Returns undef at the start of the string. Returns zero but true for
U+0000.

=head2 advance

    my $int = $string_iterator->advance($num);

Skip code points.

=over

=item *

B<num> - The number of code points to skip.

=back

Returns: the number of code points actually skipped. This can be less
than the requested number if the end of the string is reached.

=head2 recede

    my $int = $string_iterator->recede($num);

Skip code points backward.

=over

=item *

B<num> - The number of code points to skip.

=back

Returns: the number of code points actually skipped. This can be less
than the requested number if the start of the string is reached.

=head2 skip_whitespace

    my $int = $string_iterator->skip_whitespace();

Skip whitespace.  Whitespace is any character that has the Unicode
property C<White_Space>.

Returns: the number of code points skipped.

=head2 skip_whitespace_back

    my $int = $string_iterator->skip_whitespace_back();

Skip whitespace backward.  Whitespace is any character that has the
Unicode property C<White_Space>.

Returns: the number of code points skipped.

=head2 starts_with

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

Test whether the content after the iterator starts with C<prefix>.

=head2 ends_with

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

Test whether the content before the iterator ends with C<suffix>.

=head1 INHERITANCE

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

=cut