c_constants.scad

/*
                    OpenSCAD compat © 2025 Alexander Hajnal
                    ---------------------------------------
                       C and Perl compatible functions

                              c_constants  v1.0.0
  
A set of useful constants for OpenSCAD that closely follow those in the 
C standard library and Perl.
  
License: CC BY-NC-SA
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
https://creativecommons.org/licenses/by-nc-sa/4.0/

*/

{ // Release notes =============================================================

{ /* Overview ------------------------------------------------------------------

This file defines various constants that can be used to determine system 
characteristics and can also be used to avoid having "magic numbers" in 
one's code.

*/ } // END Overview

{ /* ASCII special characters ==================================================

A number of variables are defined containing strings that represent various 
special characters in 7-bit ASCII character set.  These are:

 • `compat_SOH` = 0x01 → SOH (start of heading)
 • `compat_STX` = 0x02 → STX (start of text)
 • `compat_ETX` = 0x03 → ETX (end of text)
 • `compat_EOT` = 0x04 → EOT (end of transmission)
 • `compat_ENQ` = 0x05 → ENQ (enquiry)
 • `compat_ACK` = 0x06 → ACK (acknowledge)
 • `compat_BEL` = 0x07 → BEL (bell)
 • `compat_BS`  = 0x08 → BS (backspace)
 • `compat_HT`  = 0x09 → HT (horizontal tab)
 • `compat_LF`  = 0x0A → LF (new line)
 • `compat_VT`  = 0x0B → VT (vertical tab)
 • `compat_FF`  = 0x0C → FF (form feed)
 • `compat_CR`  = 0x0D → CR (carriage ret)
 • `compat_SO`  = 0x0E → SO (shift out)
 • `compat_SI`  = 0x0F → SI (shift in)
 • `compat_DLE` = 0x10 → DLE (data link escape)
 • `compat_DC1` = 0x11 → DC1 (device control 1)
 • `compat_DC2` = 0x12 → DC2 (device control 2)
 • `compat_DC3` = 0x13 → DC3 (device control 3)
 • `compat_DC4` = 0x14 → DC4 (device control 4)
 • `compat_NAK` = 0x15 → NAK (negative acknowledge)
 • `compat_SYN` = 0x16 → SYN (synchronous idle)
 • `compat_ETB` = 0x17 → ETB (end of trans. blk)
 • `compat_CAN` = 0x18 → CAN (cancel)
 • `compat_EM`  = 0x19 → EM (end of medium)
 • `compat_SUB` = 0x1A → SUB (substitute)
 • `compat_ESC` = 0x1B → ESC (escape; non-standard escape sequence)
 • `compat_FS`  = 0x1C → FS (file separator)
 • `compat_GS`  = 0x1D → GS (group separator)
 • `compat_RS`  = 0x1E → RS (record separator)
 • `compat_US`  = 0x1F → US (unit separator)
 • `compat_DEL` = 0x7F → DEL (delete)

The null character (NULL, 0x00) is not representable in OpenSCAD.

In addition to the single characters above the `compat_WHITESPACE` variable 
contains all of the valid 7-bit ASCII whitespace characters (space, FF, NL 
[a.k.a. LF], CR, HT, and VT).

*/

} // END ASCII special characters

{ /* Library version numbers ---------------------------------------------------
 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.

*/ } // END Library version numbers

{ /* Library version number 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.
   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.

*/ } // END Library version number related functions


} // END Release notes






{ // ASCII special characters ==================================================

//compat_NUL = chr(0);   // NUL (null character)    NOT REPRESENTABLE IN OPENSCAD
compat_SOH = "\u0001"; // SOH (start of heading)
compat_STX = "\u0002"; // STX (start of text)
compat_ETX = "\u0003"; // ETX (end of text)
compat_EOT = "\u0004"; // EOT (end of transmission)
compat_ENQ = "\u0005"; // ENQ (enquiry)
compat_ACK = "\u0006"; // ACK (acknowledge)
compat_BEL = "\u0007"; // BEL (bell)
compat_BS  = "\u0008"; // BS (backspace)
compat_HT  = "\u0009"; // HT (horizontal tab)
compat_LF  = "\u000A"; // LF (new line)
compat_VT  = "\u000B"; // VT (vertical tab)
compat_FF  = "\u000C"; // FF (form feed)
compat_CR  = "\u000D"; // CR (carriage ret)
compat_SO  = "\u000E"; // SO (shift out)
compat_SI  = "\u000F"; // SI (shift in)
compat_DLE = "\u0010"; // DLE (data link escape)
compat_DC1 = "\u0011"; // DC1 (device control 1)
compat_DC2 = "\u0012"; // DC2 (device control 2)
compat_DC3 = "\u0013"; // DC3 (device control 3)
compat_DC4 = "\u0014"; // DC4 (device control 4)
compat_NAK = "\u0015"; // NAK (negative acknowledge)
compat_SYN = "\u0016"; // SYN (synchronous idle)
compat_ETB = "\u0017"; // ETB (end of trans. blk)
compat_CAN = "\u0018"; // CAN (cancel)
compat_EM  = "\u0019"; // EM (end of medium)
compat_SUB = "\u001A"; // SUB (substitute)
compat_ESC = "\u001B"; // ESC (escape; non-standard escape sequence)
compat_FS  = "\u001C"; // FS (file separator)
compat_GS  = "\u001D"; // GS (group separator)
compat_RS  = "\u001E"; // RS (record separator)
compat_US  = "\u001F"; // US (unit separator)
compat_DEL = "\u007F"; // DEL (delete)

compat_WHITESPACE = str(" ",compat_FF,"\n\r\t",compat_VT);

} // END ASCII special characters




{ // Version number related functions ==========================================
  
function c_constants_version()
  = [ c_constants_version_major(), 
      c_constants_version_minor(), 
      c_constants_version_subminor(), 
      c_constants_version_suffix() ];

function c_constants_version_string() 
  = str(
         c_constants_version_major(), ".", 
         c_constants_version_minor(), ".", 
         c_constants_version_subminor(), c_constants_version_suffix()
       );
function c_constants_version_major() = 1;
function c_constants_version_minor() = 0;
function c_constants_version_subminor() = 0;
function c_constants_version_suffix() = "";

// Run-time version checks
// 
// To require any version of c_constants with a given major (i.e. with a compatible
// API but with at least a given revision (minor or minor.subminor) use e.g.:
// 
// c_constants_require_exact(major=1);     // Any 1.x.y version
// c_constants_require(major=1, minor=2);  // Version 1.2.y or later

// Require at least the specified version of c_constants
module c_constants_require(major=0,minor=0,subminor=0) {
  assert( ( is_num(major) && is_num(minor) && is_num(subminor) ),
          "All arguments to c_constants_require(…) must be numbers!" );
  assert(
          ( major <= c_constants_version_major() )
          , sprintf(
                     "FATAL c_constants version %i.%i.%i or greater is required (this is version %s)", 
                     [ major, minor, subminor, c_constants_version_string() ]
            ) 
        );
  if ( major == c_constants_version_major() ) {
    assert(
            ( minor <= c_constants_version_minor() )
            , sprintf(
                       "FATAL c_constants version %i.%i.%i or greater is required (this is version %s)", 
                       [ major, minor, subminor, c_constants_version_string() ]
              ) 
          );
    if ( minor == c_constants_version_minor() ) {
      assert(
              ( subminor <= c_constants_version_subminor() )
              , sprintf(
                         "FATAL c_constants version %i.%i.%i or greater is required (this is version %s)", 
                         [ major, minor, subminor, c_constants_version_string() ]
                ) 
            );
    }
  }
}

// Require a specified version of c_constants
module c_constants_require_exact(major,minor,subminor) {
  assert( (
               ( is_undef(major)    || is_num(major) )
            && ( is_undef(minor)    || is_num(minor) )
            && ( is_undef(subminor) || is_num(subminor) )
          ), "All arguments to c_constants_require(…) must be numbers!" );
  if ( is_undef(major) ) {
    // Any major is accepted
    // (NOOP)
  } else {
    // Specific major required
    if ( is_undef(minor) ) {
      // Any minor is accepted
      assert(
              ( major == c_constants_version_major() )
              , sprintf(
                         "FATAL c_constants version %i is required (this is version %i)", 
                         [ major, c_constants_version_major() ]
                ) 
            );
    } else {
      // Specific minor is required
      if ( is_undef(subminor) ) {
        // Any subminor is accepted
        assert(
                (    major == c_constants_version_major()
                  && minor == c_constants_version_minor() )
                , sprintf(
                           "FATAL c_constants version %i.%i is required (this is version %i.%i)", 
                           [ major, minor, c_constants_version_major(), c_constants_version_minor() ]
                  ) 
              );
      } else {
        // Specific subminor is required
        assert(
                (    major    == c_constants_version_major()
                  && minor    == c_constants_version_minor()
                  && subminor == c_constants_version_subminor() )
                , sprintf(
                           "FATAL c_constants version %i.%i.%i is required (this is version %s)", 
                           [ major, minor, subminor, c_constants_version_string() ]
                  ) 
              );
      }
    }
  }
}

} // END Version number related functions