Skip to content
A simpler string library for C
C Shell M4 Makefile
Branch: master
Clone or download
Latest commit 78d3967 Feb 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE language detection Dec 11, 2018
build-aux Switch to std=c89 from c90, add strdup check Dec 12, 2018
src fix xstr_insert and xstr_push... I'm an idiot Feb 20, 2019
.gitignore update gitignore Dec 12, 2018
.travis.yml .travis.yml:remove windows Dec 12, 2018 implement travis for code integration testing Dec 12, 2018
LICENSE use build-aux directory Dec 11, 2018 apply Dec 14, 2018 implement travis for code integration testing Dec 12, 2018
configure dependency tracking Dec 12, 2018
package.json update package.json Feb 20, 2019 ununsed include path Dec 12, 2018

xstr: A simpler string library

License CodeFactor Build Status

What is this:

xstr is a library for managing and manipulating dynamic strings in a simple way.

Why use this over other string libraries:

  • It's public domain
  • You can access the internal string using *str instead of having to do get_val(str) or str.val
  • Compatible with C90/C89, not just C99
  • Consistent, simple interface. All functions take dest as the first argument and return an x_error_t.

Why not to use this library:

  • You don't have libc available
  • You're using a custom allocator
  • You have no allocator
  • You need really high performance
  • You're a programming-masochist
  • You're using Python

How to get it:

If you have clib:

clib install the-sushi/xstr

If you don't have clib:

Either get clib, or do this:

mkdir deps deps/xstr
git clone /tmp/xstr
cp /tmp/xstr/src/* deps/xstr/

If you like this lib enough to install it everywhere

git clone
cd xstr
mkdir build
cd build
../configure [--help]
(optionally) make install

Build example.c

From the build directory:

make example -C src


Without any error handling:

#include <lib-x/str.h>
#include <stdio.h>

int main(void)
	xstr_t thing;

	xstr_init_set(&thing, "hello");
	xstr_cat_c(thing, " world");
	xstr_delete(thing, 0, 4);
	xstr_insert_c(thing, "Hi there,", 0);
	xstr_push(thing, '!');

	printf("End result: %s\n", *thing);

	return 0;

With basic example error handling:

#include <lib-x/str.h>
#include <stdio.h>

int main(void)
	xstr_t thing;
	x_error_t e;

	e = xstr_init_set(&thing, "hello");
	if (error != XE_NONE) return 1;

	e = xstr_cat_c(thing, " world");
	if (error != XE_NONE) return 1;

	e = xstr_delete(thing, 0, 4);
	if (error != XE_NONE) return 1;

	e = xstr_insert_c(thing, "Hi there,", 0);
	if (error != XE_NONE) return 1;

	e = xstr_push(thing, '!');
	if (error != XE_NONE) return 1;

	printf("End result: %s\n", *thing);

	return 0;

Case/Switch error handling:

#include <lib-x/str.h>
#include <stdio.h>

int main(void)
	xstr thing;
	x_error_t e;

	e = xstr_init_set(&thing, "Hello, world!");
	switch (e)
		case XE_NONE:
		case XE_ALLOC:
			perror("Error allocating string");
			return 1;
			fprintf(stderr, "Unknown error.  This should not be happening");
			return 1;

	return 0;




typedef enum
} x_error_t;

All functions return this.


typedef char ** xstr_t;


typedef struct _xstr_s
	char * val;
	size_t cap;
	size_t len;

Internal representation of an xstr.


#define xstrlen(x)   (((_xstr_s *) x)->len)

Get length of an xstring

#define xstr_init_set(dest, src)         xstr_init_set_n((dest), (src), strlen(src))

Initializes an xstring with specified C-string value

#define xstr_cpy_c(dest, src)            xstr_cpy_c_n((dest), (src), strlen(src))

Copies specfied C-string to specified xstring

#define xstr_cat_c(dest, src)            xstr_cat_c_n((dest), (src), strlen(src))

Appends specified C-string to specified xstring

#define xstr_insert_c(dest, src, index)  xstr_insert_c_n((dest), (src), index, strlen(src))

Inserts specified C-string into xstring at specified location


x_error_t xstr_init(xstr_t * dest, size_t size);

Initializes an xstring

x_error_t str_init_set_n(xstr_t * dest, char * src, size_t src_len);

Initializes and sets an xstring to src, assuming src is src_len chars long

x_error_t xstr_cpy(xstr_t dest, xstr_t src);

Copies one xstring to another

x_error_t xstr_cpy_c_n(xstr_t dest, char * src, size_t len);

Copies a C-string that is len chars long into an xstring

x_error_t xstr_cat(xstr_t dest, xstr_t src);

Append an xstring to an xstring

x_error_t xstr_cat_c_n(xstr_t dest, char * src, size_t src_len);

Appends a C-string that is src_len chars long into an xstring.

x_error_t xstr_insert(xstr_t dest, char * src, size_t index);

Inserts an xstring into another xstring at specified index

x_error_t xstr_insert_c_n(xstr_t dest, char * src, size_t index, size_t src_len);

Inserts a C-string that is src_len chars long into an xstring at specified index

x_error_t xstr_delete(xstr_t dest, size_t start, size_t end);

Deletes part of an xstring. (from index of start until end)

x_error_t xstr_push(xstr_t dest, char ch);

Appends a single character to an xstring

x_error_t xstr_free(xstr_t src);

Deallocates an xstring

You can’t perform that action at this time.