libunistring

Guidance last updated: 20 October 2026

Text files are nowadays usually encoded in Unicode, and may consist of very different scripts - from Latin letters to Chinese Hanzi, with many kinds of special characters: accents, right-to-left writing marks, hyphens, Roman numbers, and much more. But the POSIX platform APIs for text do not contain adequate functions for dealing with particular properties of many Unicode characters. In fact, the POSIX APIs for text have several assumptions at their base which don’t hold for Unicode text.

This library provides functions for manipulating Unicode strings and for manipulating C strings according to the Unicode standard.

Usage

After connecting to Stanage (see Establishing a SSH connection), start an interactive session:

salloc

You can load a specific version with the following command:

module load libunistring/1.4.1-GCCcore-15.2.0
module load libunistring/1.3-GCCcore-14.3.0
module load libunistring/1.3-GCCcore-14.2.0

module load libunistring/1.4.1-GCCcore-15.2.0
module load libunistring/1.3-GCCcore-14.3.0
module load libunistring/1.3-GCCcore-14.2.0

The module loads the matching compiler and makes the headers and libraries available for compiling C programs.

Example

Save the following as unicode-example.c. It converts the UTF-8 string Straße to STRASSE, including the expansion of ß to SS:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unicase.h>

int main(void)
{
    const uint8_t input[] = "Straße";
    const char expected[] = "STRASSE";
    size_t length = 0;
    uint8_t *upper = u8_toupper(input, sizeof(input) - 1,
                               NULL, NULL, NULL, &length);
    if (upper == NULL) {
        perror("u8_toupper");
        return EXIT_FAILURE;
    }
    if (length != sizeof(expected) - 1 ||
        memcmp(upper, expected, length) != 0) {
        fprintf(stderr, "Unexpected uppercase result\n");
        free(upper);
        return EXIT_FAILURE;
    }
    fwrite(upper, 1, length, stdout);
    putchar('\n');
    free(upper);
    return EXIT_SUCCESS;
}

The following example batch submission script compiles and runs the program:

#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=1000
#SBATCH --time=00:05:00

set -e
module load libunistring/1.4.1-GCCcore-15.2.0
gcc -Wall -Wextra -O2 unicode-example.c -o unicode-example -lunistring
./unicode-example

Submit it from the directory containing unicode-example.c using sbatch. The program prints STRASSE and returns a non-zero exit status if the result is incorrect.

Installation notes

libunistring was installed using Easybuild, build details can be found in $EBROOTLIBUNISTRING/easybuild with a given module loaded.