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

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.
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.

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