c_string.md

OpenSCAD compat

c_string

© 2025 Alexander Hajnal v1.0.0

A set of string-related functions for OpenSCAD that closely follow those in the C standard library and Perl.

These include printf and sprintf [from stdio.h] plus various string-related functions from the C library (strchr, strlen, strpbrk, strstr, strtok [all from string.h], index, and rindex [both from strings.h]) and from Perl (index, rindex, and substr [see perlfunc(1)]).

The semantics are usually similar but not identical to their C and Perl equivalents so cf. the syntax descriptions below. The first characters of all strings is at index 0 a.k.a. offset 0 (e.g. for ABC the letter A is at index 0). As a general rule, all C pointers are changed to string indices and all C NULL values are changed to undef.

To include in your code by placing this file in the same directory as your OpenSCAD script and including the following in your script:

include <c_constants.scad>;
use <c_string.scad>;

A stand-alone demo/test script can be found in c_string-test.scad.

Some functions are for internal use only and they should never be called from user code. These function are indicated by the name ending in an underscore followed by uppercase letters or underscores, optionally followed by additionalalphanumeric characters. Some examples:

function something_PRIVATE_FUNCTION(args) = …
function something_PRIVATE_variant(args) = …

Please submit any bug reports or feature requests via GitHub.

printf and sprintf:

• printf(format, arguments) Write formatted string to the console.

  This is a module and returns no value. See sprintf(…) below for details.

• sprintf(format, arguments) Returns a formatted string.

  Note that arguments is an OpenSCAD list; this can be a list variable or an inline list (surrounded by square brackets), e.g. [ "arg1", 2, arg3 ]

  A subset of the C library conversion specifications are supported:

  • %% → a literal % character
  • %s → string
  • %d → integer
  • %i → integer
  • %f → floating point to rounded to 6 significant digits (zero-padding on the right)
  • %.Nf → floating point to rounded to N significant digits after the decimal point (zero-padding on the right)

  See the printf(3) manpage for details.

C-like string functions:

• index(string, character) Returns the index of the first occurrence of the single character in string or undef if it is not found.

  This is implemented as a call to the Perl-like function of the same name so character can actually be a multi-character string.

• rindex(string, character) Returns the index of the last occurrence of the single character in string or undef if it is not found.

  This is implemented as a call to the Perl-like function of the same name so character can actually be a multi-character string.

• strchr(string, character) Returns the index of the first occurrence of the single character in string or undef if it is not found.

• strcspn(string, reject) Returns the length in characters of the left-most part of string that does not contain any of the characters found in the reject string.

• strlen(string) Returns the length of the string in characters. (This is identical to the OpenSCAD len(…) function.)

• strpbrk(string, characters) Returns the index of the first occurrence in string of any character in the characters string or undef if it is not found.

• strrchr(string, character) Returns the index of the last occurrence of the single character in string or undef if it is not found.

• strspn(string, accept) Returns the length in characters of the left-most part of string that only contains characters found in the accept string.

• strstr(haystack, needle) Returns the index of the first occurrence of the complete string needle in the haystack string or undef if it is not found.

• strtok(string, delimers) strtok_r(string, delimers) strtok(string, delimers, output_delmiters) strtok_r(string, delimers, output_delmiters) Splits string into a list of tokens that are separated by any of the characters in the delimiters string.

  If no delimiter is found then the return value is a single-element list containing the entire input string, e.g. [ string ]

  If output_delimiters is true then the returned list will also include the delimiters found (default is false).

Perl-like string functions:

• index(haystack, needle) index(haystack, needle, offset) Returns the index of the first occurrence of the string needle in the string haystack.

  Returns -1 if needle is not found. (Note: C returns NULL in this case)

  If offset is specified then the search begins that many characters from the beginning of haystack.

• rindex(haystack, needle) rindex(haystack, needle, offset) Returns the index of the last occurrence of the string needle in the string haystack (searching backwards from the end).

  Returns undef if needle is not found. (Note: C returns NULL in this case)

  If offset is specified then the search begins that many characters from the end of haystack.

• split(string, delimiters, limit=0, output_delimiters=false) split(string, lambda, limit=0, output_delimiters=false) Splits string into a list of strings that are separated by any of the characters in the delimiters string; a user-provided function can instead be used to identify arbitrary delimiters. If no delimiter is found then the return value is a single-element list containing the entire input string, e.g. [ string ]. The maximum number of tokens to return can optionally be specified and delimiters found can be optionally also be returned.

• substr(string, offset) substr(string, offset, length) Extracts the substring of given length from string starting at the index offset. The first character is at offset 0.

  If offset is negative then the start offset is that many characters from the end of the string. If the length is omitted then all characters from offset to the end of the string are returned. If length is negative then that many characters are omitted from the end of the string.

  Note that unlike in Perl, substr(…) cannot be used as an lvalue.

  Examples (adapted from perlfunc(1)):

s          = "The black cat climbed the green tree";
color      = substr(s, 4, 5);    // black
middle     = substr(s, 4, -11);  // black cat climbed the
tail       = substr(s, -4);      // tree
z          = substr(s, -4, 2);   // tr
trim_left  = substr(s, 4);       // black cat climbed the green tree
trim_right = substr(s, 0, -5);   // The black cat climbed the green

Library version numbers

Major versions indicate a non-backwards-compatible change to the API.

Minor versions indicate substantial new features or bug fixes.

Subminor versions indicate changes that don't [yet] warrant incrementing the minor version number.

A suffix may be added when the changes are so inconsequential that incrementing the version number isn't warranted. This may include things like tweaks to comment formatting, indents, and the like. It does not include any changes to the code's logic or syntax.

Library version related functions

• c_string_version() Returns the c_string library version as an OpenSCAD list: [ Major, Minor, Subminor, Suffix ]

  (e.g. [ 1, 0, 2, "bis" ])

• c_string_version_string() Returns the c_string library version as an OpenSCAD list: "Major.Minor.SubminorSuffix"

  (e.g. "1.0.2bis")

• c_string_require( major, minor, subminor ) Require at least the specified version of c_string. Throws a fatal error if the c_string library version is less than the one specified. All arguments are optional. Note that the suffix is ignored.

  Throws a fatal error if the c_string library version is less than the one specified.

  This is a module and returns no value.

• c_string_require_exact(major,minor,subminor) Require a specific version of c_string

  Throws a fatal error if the c_string library version does not equal the one specified. All arguments are optional. Note that the suffix is ignored.

  This is a module and returns no value.

Note: To require any version of c_string with a specific major (i.e. with a compatible API) but with at least a given revision (minor or minor.subminor) use e.g.:

c_string_require_exact(major=1);     // Any 1.x.y version
c_string_require(major=1, minor=2);  // Version 1.2.y or later

• c_string_version_major() Returns the c_string library major version number as an integer.

• c_string_version_minor() Returns the c_string library minor version number as an integer.

• c_string_version_subminor() Returns the c_string library subminor version number as an integer.

• c_string_version_suffix() Returns the c_string library version suffix as a string.

Version history

1.0.0 [2025-11-24] Initial public release

• Initial version