SoylentNews

I've recently done some touchups to my SubStrings library, and have reminded myself of my own undying glory, er, I mean, come to the conclusion that it's useful enough to warrant me advertising it a little bit. I use it in a large percentage of my projects nowadays. I thought I'd showcase part of what makes it awesome to me.

Before we begin, there is one thing I must mention: SubStrings is only designed to work well with null terminated strings only. It's almost certainly unsafe to use it for anything else.
And, one last thing: This is indeed a C library, written in C89 and works in C. The OOP appearance, such as SubStrings.Length(), is function pointer trickery for cleanliness' sake. SubStrings is also a non-hosted library, meaning it has no dependencies, and can thus even be used in your bootloader's source code.

String copy and concatenation, truly safe
SubStrings copy and concatenation functions have precise bounds checking, and always result in a null terminated string, and, if the size parameter is given accurately, SubStrings never has buffer overflows. Let's illustrate.

#include "substrings/substrings.h"

void MyFunc(void)
{
   char Array[1024];

   //So, the maximum string data copied will be sizeof Array - 1, so there is room for the '\0'.
   SubStrings.Copy(Array, "My string is awesome!", sizeof Array);

   /*SubStrings.Cat's size parameter needs to be the *maximum capacity* of the destination. You don't need to subtract from
   the max size each iteration of a loop. SubStrings knows how to do it.*/
   SubStrings.Cat(Array, " And it merges really nice too!", sizeof Array);
}

strcpy and strcat() are in general, unsafe, and strncat and strncpy have differing and confusing behavior. SubStrings eliminates these problems with one consistent approach for concatenation and copy operations.

All the necessities provided

SubStrings also provides all the other functions you might want for basic string operations, including Length(), Compare(), NCompare() [analogous to strncmp()], Find(), and CFind() [Find a single character], and FindAnyOf() [Analogous to strchr()].
Find() and CFind() accept another, new argument, allowing you to directly request the N-th occurrence of the matching string/characters. There is also IsLowerS, IsLowerC, IsUpperC, and conversion functions like LowerS, LowerC, UpperS, and UpperC.

In general, functions ending in S deal with strings, and functions ending in C deal with single characters.

High level stuff is here too
Some of the cooler stuff is stuff you might expect to find in Python.
Stuff like StartsWith, EndsWith, Replace, Strip, Reverse, and StripLeadingChars and StripTrailingChars.

And some original ideas too
There are other functions, like Extract(), which pulls the string content that's in between two sequences.
Let's have an example.

#include "substrings/substrings.h"

int main(int argc, char **argv)
{
    int Inc = 1;
    char Buf[256];

    for (; Inc < argc; ++Inc)
    {
        if (SubStrings.StartsWith("--config=", argv[Inc]))
        {
             SubStrings.Extract(Buf, sizeof Buf, "=", NULL, argv[Inc]);
             DoSomething(Buf);
         }
     }
}

What's happening here is that Extract is pulling the data that starts after the =, and since the next parameter is NULL, it reads on until the end of the string. This makes handling command line arguments marginally simpler.

There's other goodies, like SubStrings.CopyUntil(). Let's take a look.

#include "substrings/substrings.h"

void MyFunc(void)
{
    const char *const String = "Wibble[END]Nurble[END]Aburble[END]Farts";
    const char *Iter = String;
    char Buf[256];
    while (SubStrings.CopyUntil(Buf, sizeof Buf, &Iter, "[END]", true))
    {
         puts(Buf);
    }
}

This produces the output:

Wibble
Nurble
Aburble
Farts

I actually find myself using CopyUntil and its sister function CopyUntilC quite often. Then there's SubStrings.Line.GetLine(), which is a specialized CopyUntil that helps with processing multi-line C strings.

Lastly, there's another useful function, Split().

#include "substrings/substrings.h"

void MyFunc(void)
{
    const char *String = "Gerbil|Wibble";
    char One[256], Two[256];

    SubStrings.Split(One, Two, "|", String, SPLIT_HALFONE);
}

Now, One[] contains "Gerbil|" and Two[] contains "Wibble". You can specify to discard the split tokens, or put them in half one or two. The options are SPLIT_NOKEEP, SPLIT_HALFONE, and SPLIT_HALFTWO. Because Split() doesn't ask for buffer sizes for the sake of convenience, the way to do it safely is to make sure that both One and Two will be able to hold the entire length of String, if needed.

This library is getting more touchups. You can find the github here, and the SubStrings homepage here.

Thoughts, ideas or suggestions? Let me know.