std/string

NAME

std/string - String utilities for ZuzuScript modules.

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
  say( repeat(4, "bar", "|") ); # bar|bar|bar|bar

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

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

EXPORTS

Functions

substr(String text, Number start, Number length?)
Parameters: text is source text, start is a zero-based character offset, and length is optional. Returns: String. Returns a substring.
index(String text, String needle, Number start?)
Parameters: text is source text, needle is the text to find, and start is optional. Returns: Number. Returns the first matching index or -1.
rindex(String text, String needle, Number start?)
Parameters: text is source text, needle is the text to find, and start is optional. Returns: Number. Returns the last matching index or -1.
contains(String text, String needle)
Parameters: text is source text and needle is the text to find. Returns: Boolean. Returns true when needle occurs in text.
starts_with(String text, String prefix)
Parameters: text is source text and prefix is the expected prefix. Returns: Boolean. Returns true when text starts with prefix.
ends_with(String text, String suffix)
Parameters: text is source text and suffix is the expected suffix. Returns: Boolean. Returns true when text ends with suffix.
chr(Number codepoint)
Parameters: codepoint is a Unicode codepoint. Returns: String. Returns the character for codepoint.
ord(String text, Number index?)
Parameters: text is source text and index is an optional character offset. Returns: Number. Returns the codepoint at index.
replace(String text, String pattern, String replacement, String flags?)
Parameters: text is source text, pattern is a string or regexp, replacement is replacement text, and flags are optional regexp flags. Returns: String. Replaces matching text.
search(String text, String pattern, String flags?)
Parameters: text is source text, pattern is a string or regexp, and flags are optional regexp flags. Returns: match value or null. Finds the first match.
matches(String text, String pattern, String flags?)
Parameters: text is source text, pattern is a string or regexp, and flags are optional regexp flags. Returns: Boolean. Returns true when text matches pattern.
pattern_to_regexp(String pattern, Boolean case_insensitive?)
Parameters: pattern is a pattern string and case_insensitive requests case-insensitive matching. Returns: Regexp. Compiles a regexp from a string pattern.
quotemeta(String text)
Parameters: text is source text. Returns: String. Prefixes regexp metacharacters, slash delimiters, and quote characters with \ so the result can be safely interpolated into a regexp as literal text, for example /^${quotemeta(label)}:/i.
sprint(String format, ...args)
Parameters: format is a format string and args are replacement values. Returns: String. Formats text.
repeat(Number count, String|BinaryString text, String|BinaryString separator?)
Parameters: count is the number of repetitions, text is the value to repeat, and separator is optional text to place between repeated values. Returns: String or BinaryString. Repeats text floor(count) times, inserting separator between copies when given. count must not be negative. text and separator may both be character strings or both be byte strings; mixing String and BinaryString throws an exception.
split(String text, String separator_or_regexp, Number limit?)
Parameters: text is source text, separator_or_regexp is the split separator, and limit is optional. Returns: Array. Splits text into parts.
join(String separator, Array values)
Parameters: separator joins items and values is an array. Returns: String. Joins values into one string.
trim(String text)
Parameters: text is source text. Returns: String. Removes leading and trailing whitespace.
pad(String text, Number width, String pad_char?, String side?)
Parameters: text is source text, width is target width, pad_char is optional, and side selects padding side. Returns: String. Pads text to the requested width.
chomp(String text)
Parameters: text is source text. Returns: String. Removes one trailing line ending.
title(String text)
Parameters: text is source text. Returns: String. Converts text to title case.
snake(String text)
Parameters: text is source text. Returns: String. Converts text to snake_case.
kebab(String text)
Parameters: text is source text. Returns: String. Converts text to kebab-case.
camel(String text)
Parameters: text is source text. Returns: String. Converts text to camelCase.

FORMAT STRINGS (SPRINT)

sprint uses printf-style format strings. Ordinary text is copied to the result. A conversion starts with %, consumes one positional argument, and inserts the formatted value. %% inserts a literal percent sign and does not consume an argument.

The portable conversion codes are:

%s
Formats the value as text.
%d and %i
Formats the value as a signed decimal integer. Fractional Number values are truncated toward zero before formatting.
%u
Formats the value as an unsigned decimal integer. Use non-negative numbers for portable results.
%x and %X
Formats the value as hexadecimal, using lowercase or uppercase letters.
%o
Formats the value as octal.
%f
Formats the value as fixed-point decimal. Without an explicit precision, the Perl and Rust runtimes use the usual printf default of six digits after the decimal point.
%e and %E
Formats the value in exponential notation, using lowercase or uppercase e.
%g and %G
Formats the value using the shorter of fixed-point or exponential notation, using lowercase or uppercase exponent markers when exponential notation is chosen.
%c
Formats a number as a Unicode codepoint.

Conversions may include flags, a minimum width, and a precision before the conversion code:

  %[flags][width][.precision]code

The portable flags are:

-
Left-aligns the formatted value within the field width.
0
Pads numeric fields with zeroes instead of spaces.
+
Always prints a sign for signed numeric conversions.
space
Prefixes positive signed numeric values with a space.
#
Uses an alternate form where the conversion defines one, such as 0x for %#x, 0X for %#X, or a leading 0 for %#o.

width is a decimal minimum field width. Values shorter than the width are padded on the left by default, or on the right when - is used. precision is written as .N. For %s, it limits the number of characters copied. For %f, %e, and %E, it controls the number of digits after the decimal point. For %g and %G, it controls the number of significant digits.

Arguments are converted according to the placeholder:

String
%s inserts the text. Numeric placeholders should only be used with numeric text when the value is intentionally being coerced.
BinaryString
%s treats byte strings as text. ASCII bytes are portable; for arbitrary binary data, encode it first, for example as Base64 or hex, instead of formatting raw bytes directly.
Number
Numeric placeholders use the numeric value. %d and %i truncate fractions toward zero. %c treats the number as a Unicode codepoint.
Null
%s formats null as the empty string. Numeric placeholders treat null as zero.
Other values
%s uses the value's normal string rendering. Numeric placeholders are intended for values with numeric semantics; using other values is not portable.

Field width is formatter width, not necessarily terminal display width. Avoid relying on exact padding for non-ASCII text, combining characters, or emoji.

Examples

  say sprint( "%s = %d", "count", 7 );
  // count = 7

  say sprint( "|%8s|%-8s|", "cat", "cat" );
  // |     cat|cat     |

  say sprint( "%04x %#x %#o", 10, 255, 64 );
  // 000a 0xff 0100

  say sprint( "%+.2f", 3.5 );
  // +3.50

  say sprint( "%.3s", "abcdef" );
  // abc

  say sprint( "%c", 9731 );
  // ☃

  say sprint( "[%s][%d]", null, null );
  // [][0]

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.

COPYRIGHT AND LICENCE

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.

Module