std/string

=encoding utf8

=head1 NAME

std/string - String utilities for ZuzuScript modules.

=head1 SYNOPSIS

  from std/string import *;

  let s := "abcdef";
  say( substr( s, 1, 3 ) );     # bcd
  say( index( s, "cd" ) );      # 2
  say( replace( s, "cd", "XY" ) );
  let label := "Zia.+";
  let safe := /^${quotemeta(label)}:/i;
  let rx := pattern_to_regexp( "cd", true );
  say( search( s, rx ) );       # CD (if present)
  say( trim("  hello  ") );     # hello
  say( title("hello_world") );  # Hello World

=head1 IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

=head1 DESCRIPTION

This module provides helper functions that are useful when writing
higher-level parsers and serializers in ZuzuScript.

=head1 EXPORTS

=head2 Functions

=over

=item * C<substr(String text, Number start, Number length?)>

Parameters: C<text> is source text, C<start> is a zero-based character
offset, and C<length> is optional. Returns: C<String>. Returns a
substring.

=item * C<index(String text, String needle, Number start?)>

Parameters: C<text> is source text, C<needle> is the text to find, and
C<start> is optional. Returns: C<Number>. Returns the first matching
index or C<-1>.

=item * C<rindex(String text, String needle, Number start?)>

Parameters: C<text> is source text, C<needle> is the text to find, and
C<start> is optional. Returns: C<Number>. Returns the last matching
index or C<-1>.

=item * C<contains(String text, String needle)>

Parameters: C<text> is source text and C<needle> is the text to find.
Returns: C<Boolean>. Returns true when C<needle> occurs in C<text>.

=item * C<starts_with(String text, String prefix)>

Parameters: C<text> is source text and C<prefix> is the expected prefix.
Returns: C<Boolean>. Returns true when C<text> starts with C<prefix>.

=item * C<ends_with(String text, String suffix)>

Parameters: C<text> is source text and C<suffix> is the expected suffix.
Returns: C<Boolean>. Returns true when C<text> ends with C<suffix>.

=item * C<chr(Number codepoint)>

Parameters: C<codepoint> is a Unicode codepoint. Returns: C<String>.
Returns the character for C<codepoint>.

=item * C<ord(String text, Number index?)>

Parameters: C<text> is source text and C<index> is an optional character
offset. Returns: C<Number>. Returns the codepoint at C<index>.

=item * C<replace(String text, String pattern, String replacement, String flags?)>

Parameters: C<text> is source text, C<pattern> is a string or regexp,
C<replacement> is replacement text, and C<flags> are optional regexp
flags. Returns: C<String>. Replaces matching text.

=item * C<search(String text, String pattern, String flags?)>

Parameters: C<text> is source text, C<pattern> is a string or regexp,
and C<flags> are optional regexp flags. Returns: match value or
C<null>. Finds the first match.

=item * C<matches(String text, String pattern, String flags?)>

Parameters: C<text> is source text, C<pattern> is a string or regexp,
and C<flags> are optional regexp flags. Returns: C<Boolean>. Returns
true when C<text> matches C<pattern>.

=item * C<pattern_to_regexp(String pattern, Boolean case_insensitive?)>

Parameters: C<pattern> is a pattern string and C<case_insensitive>
requests case-insensitive matching. Returns: C<Regexp>. Compiles a
regexp from a string pattern.

=item * C<quotemeta(String text)>

Parameters: C<text> is source text. Returns: C<String>. Prefixes
regexp metacharacters, slash delimiters, and quote characters with
C<\> so the result can be safely interpolated into a regexp as literal
text, for example C<< /^${quotemeta(label)}:/i >>.

=item * C<sprint(String format, ...args)>

Parameters: C<format> is a format string and C<args> are replacement
values. Returns: C<String>. Formats text.

=item * C<split(String text, String separator_or_regexp, Number limit?)>

Parameters: C<text> is source text, C<separator_or_regexp> is the split
separator, and C<limit> is optional. Returns: C<Array>. Splits text into
parts.

=item * C<join(String separator, Array values)>

Parameters: C<separator> joins items and C<values> is an array. Returns:
C<String>. Joins values into one string.

=item * C<trim(String text)>

Parameters: C<text> is source text. Returns: C<String>. Removes leading
and trailing whitespace.

=item * C<pad(String text, Number width, String pad_char?, String side?)>

Parameters: C<text> is source text, C<width> is target width,
C<pad_char> is optional, and C<side> selects padding side. Returns:
C<String>. Pads text to the requested width.

=item * C<chomp(String text)>

Parameters: C<text> is source text. Returns: C<String>. Removes one
trailing line ending.

=item * C<title(String text)>

Parameters: C<text> is source text. Returns: C<String>. Converts text to
title case.

=item * C<snake(String text)>

Parameters: C<text> is source text. Returns: C<String>. Converts text to
snake_case.

=item * C<kebab(String text)>

Parameters: C<text> is source text. Returns: C<String>. Converts text to
kebab-case.

=item * C<camel(String text)>

Parameters: C<text> is source text. Returns: C<String>. Converts text to
camelCase.

=back

=head1 PORTABILITY

Regex-heavy and Unicode-sensitive primitives may be runtime-supported,
while higher-level API composition is validated through shared fixtures
so module behaviour stays portable across runtimes.

=head1 COPYRIGHT AND LICENCE

B<< std/string >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut
Module
