cstring

C-style strings is a small, standalone library, that provides extensible C-style string instances and extensible arrays of such, for Unix and Windows.

Table of Contents

• Installation
• Components
  • Types
  • String API
    • Status and capacity
    • Creation/destruction functions
    • Modification functions**
    • File functions**
  • Vector API
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
  • Related projects
  • License

Installation

Detailed instructions - via CMake, via bundling - are provided in the accompanying INSTALL.md file.

Components

Types

The C API is based around two structures:

• cstring_t, which represents a resizeable string instance; and

  struct cstring_t
  {
    size_t          len;        /*!< Number of characters.                              */
    cstring_char_t* ptr;        /*!< Pointer to the string. If capacity is 0, the value
                                     of this member is undetermined.                    */
    size_t          capacity;   /*!< Number of bytes available.                         */
    cstring_flags_t flags;      /*!< Flags. This field belongs to the implementation,
                                     and must not be modified by any application code.  */
  };

• cstring_vector_t, which represents a sequence of cstring_t instances;

  struct cstring_vector_t
  {
    size_t          len;        /*!< Number of strings.                                 */
    cstring_t*      ptr;        /*!< Pointer to the first string. If capacity is 0, the
                                     value of this member is undetermined.              */
    size_t          capacity;   /*!< Number of instances available.                     */
    cstring_flags_t flags;      /*!< Flags. This field belongs to the implementation,
                                     and must not be modified by any application code.  */
  };

String API

Defined in cstring/cstring.h:

Status and capacity

• cstring_getStatusCodeString() — returns a nul-terminated description of a CSTRING_RC code;
• cstring_setCapacity() — adjusts capacity (subject to fixed / borrowed / readonly rules);
• cstring_yield2() — yields ownership of the payload (and raw buffer) to the caller;

Creation/destruction functions

• cstring_init() — initialises an instance to default values (and does not require a following call to cstring_destroy());
• cstring_create() — creates an instance from a C-style string;
• cstring_createLen() — creates an instance from a (portion of a) C-style string;
• cstring_createN() — creates an instance from a number of repetitions of a character value;
• cstring_createEx() — creates an instance with special characteristics (borrowed buffer, allocator flags, …);
• cstring_createLenEx() — as cstring_createEx(), from a fixed number of characters;
• cstring_destroy() — releases resources and resets the instance;

Modification functions**

• cstring_assign() — assigns a C-style string (may reallocate);
• cstring_assignLen() — assigns a fixed character count (embedded NULs allowed);
• cstring_copy() — copies one cstring_t into another;
• cstring_append() — appends a C-style string;
• cstring_appendLen() — appends a fixed character count;
• cstring_insert() — inserts a C-style string at an index (CSTRING_FROM_END supported);
• cstring_insertLen() — inserts a fixed character count at an index;
• cstring_replace() — replaces a section at an index with a C-style string;
• cstring_replaceLen() — replaces a section at an index with a fixed character count;
• cstring_replaceAll() — replaces all occurrences of one substring with another;
• cstring_truncate() — shortens the logical length (capacity unchanged);
• cstring_swap() — swaps the contents of two instances;

File functions**

• cstring_readline() — reads a line of text from the given text stream into the instance;
• cstring_write() — writes the string to the given text stream;
• cstring_writeline() — writes the string followed by a newline to the given text stream;

Vector API

Defined in cstring/cstring.vector.h:

• cstring_vector_init() — initialises a vector, optionally with a minimum capacity;
• cstring_vector_create() — creates a vector of a given initial size (elements default-initialised);
• cstring_vector_destroy() — destroys each element and frees the vector buffer;
• cstring_vector_truncate() — shortens the vector, destroying trailing elements;
• cstring_vector_insertAt() — inserts one or more cstring_t instances at a position;
• cstring_vector_append() / cstring_vector_prepend() — macros over cstring_vector_insertAt();
• cstring_vector_readLines() — reads lines from a stream into the vector;

Examples

Examples live under examples/ (c/ and cpp/), each with a short README.md. Build them with BUILD_EXAMPLES (on by default); run via run_all_examples.sh.

Example	Language	Notes
example.c.auto_buffer	C	Borrowed buffer that may grow to the heap
example.c.cstring	C	Core cstring_t create / assign / append / truncate / copy / swap
example.c.cstring_create	C	Minimal cstring_create()
example.c.cstring_vector	C	Read lines into cstring_vector_t and sort (requires input path or --)
example.cpp.cstring.dynload	C++	Windows-only dynamic load of the cstring DLL
example.cpp.HGLOBAL_on_x64	C++	Windows-only CSTRING_F_USE_WIN32_GLOBAL_MEMORY

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/cstring.

Dependencies

The C API has no non-standard dependencies.

Dependency	Role	Required?
STLSoft 1.11	Test headers / remaining C++ tests and examples	⚪ Tests only (BUILD_TESTING)
xTests (≥ 0.26)	Unit / component / scratch tests	⚪ Tests only (BUILD_TESTING)
shwild	Enhanced pattern-match assertions in xTests	⚪ Optional; tests only (unless NO_SHWILD / --no-shwild)

When supplying '--no-cpp' to prepare_cmake.sh — sets the CMake option NO_CSTRING_CPP_API=ON — C++ examples and remaining C++ tests are omitted; the C unit-tests still require STLSoft and xTests.

When supplying '--no-shwild' — sets NO_SHWILD=ON — shwild is not recognised and pattern-match assertions are compiled out; other unit-tests still run.

Related projects

Projects in which cstring is used include:

• shwild.fnmatch

License

cstring is released under the 3-clause BSD license. See LICENSE for details.