Skip to content
A simpler string library for C
C Shell M4 Makefile
Branch: master
Clone or download
Latest commit 78d3967 Feb 20, 2019
Permalink
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
.gitattributes
.gitignore update gitignore Dec 12, 2018
.travis.yml .travis.yml:remove windows Dec 12, 2018
.travis_before_install.sh implement travis for code integration testing Dec 12, 2018
LICENSE
Makefile.am use build-aux directory Dec 11, 2018
Makefile.in apply Dec 14, 2018
README.md implement travis for code integration testing Dec 12, 2018
aclocal.m4
configure
configure.ac configure.ac:disable dependency tracking Dec 12, 2018
package.json update package.json Feb 20, 2019
xstr.pc.in xstr.pc.in:remove ununsed include path Dec 12, 2018

README.md

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 https://github.com/the-sushi/xstr.git /tmp/xstr
cp /tmp/xstr/src/* deps/xstr/

If you like this lib enough to install it everywhere

git clone https://github.com/the-sushi/xstr.git
cd xstr
mkdir build
cd build
../configure [--help]
make
(optionally) make install

Build example.c

From the build directory:

make example -C src

Example:

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:
			break;
		case XE_ALLOC:
			perror("Error allocating string");
			return 1;
		default:
			fprintf(stderr, "Unknown error.  This should not be happening");
			return 1;
	}

	puts(*thing);
	return 0;
}

API:

Types:

x_error_t

typedef enum
{
	XE_NONE,
	XE_ALLOC,
	XE_DUP,
	XE_NORANGE,
	XE_OVERFLOW,
	XE_ISNULL
} x_error_t;

All functions return this.


xstr_t

typedef char ** xstr_t;

_xstr_s

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

Internal representation of an xstr.

Macros:

#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

Functions:

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.