Safe Strings Library Reference Manual

Safe Strings library, version 2.0.1
Back  Home  Next

2. SStrings Basics

  1. Basic types
  2. Error model
  3. Using the Garbage Collector
  4. "Hello World" with SStrings
  5. Installing SString
  6. Using SString

I. Basic types top Top

SStrings declares only one custom type ss_string, which is a C struct. Note: This struct will be called in this document ss_string Object.

SStrings Library Code  
typedef struct {
        char *str; /* pointer to allocated string */
        size_t len; /* length of the string */
        size_t bytes; /* how many bytes are allocated */
 
} ss_string;

The ss_string-Object has 3 variables:
  • a pointer to a char* (str) which saves the C string. The memory of this pointer is dynamically allocated.
  • a size_t variable (len) which saves the length of the string saved in str.
  • a size_t variable (bytes) which saves how many bytes are allocated (at the moment) in str.
We have 2 reasons why we save the length of the string in len.
1st: strlen works in O(n). We don't need then to call strlen to determine the length of the string. (It works in O(1))
2nd: The information saved in bytes helps by determining how may bytes are (re)allocated. SStrings allocates the needed space of memory, when a string gets smaller then SString won't reallocate the memory to fit the string length plus one. The advantage of such a strategie is that next time the ss_string Object has to expand memory, SStrings won't need to reallocate too much memory, in most cases it won't be even necessary to reallocate new memory.

If you want to read the length of the string then read the len element of the ss_string Object.

II. Error model top Top

Since SStrings is written in C, we are not able to handle with errors with exceptions. SString declares the new variable ss_errno that can be used just like the C errno variable. This variable is always set if a SString function terminates with a fault. In that case ss_errno is assigned with one of the following error constants:

SStrings Library Code  
/* DON'T DECLARE THIS VARIABLE IN YOUR SOURCE CODE */
extern short ss_errno;
 
/* error model */
enum {
        SS_NOERR = 0,
        SS_NOMEM,
        SS_NULL,
        SS_EINVAL,
        SS_NUM  /* number of errors */
};

SS_NOERR The function was successful
SS_NOMEM The function could not (re)allocate the requested memory space because of lack of memory. The actual ss_string-Object and its string are not modified
SS_NULL The function does not know what to do because one of its arguments (that shouldn't be NULL) is NULL. The actual ss_string-Object and its string are not modified
SS_EINVAL One argument has an invalid value, for example passing an invalid ss_string-Object or a wrong string position. The actual ss_string-Object and its string are not modified
SS_NUM This constant is used by SStrings only! It helps determining the number of error codes available.

III. Using the Garbage Collector top Top

SStrings implements an experimental gargabe collector and should be used at your own risk. Do not use this function if your program has already executed a SString function. Use it at the top of every program. This garbage collector can be used if you don't want to free the ss_string-Objects manually.

SStrings Library Code 
#include <sstrings2.h>
 
void ss_string_enable_gc(void);

WARNING!!! This function must always be used before you call any other function of this library. If you call this function after having called other SStrings functions then you have to remeber which variables were not allocated with the garbage collector and free them manually! If you don't do this and your program crashes then don't come crying to us! You have been warned.

IV. "Hello World" with SStrings top Top

This is the basic "Hello World" programm using SStrings (without the garbage collector):

"Hello World" Example 
#include <sstrings2.h>
#include <stdio.h>
 
int main(void)
{
    ss_string *string;
 
    string = ss_string_new("Hello, World!");
 
    if(!string)
    {
         ss_string_perror("ss_string_new");
         return 1;
    }
 
    printf("The ss_string object saves:\nstring = %s\n length = %d\nbytes = %d\n", 
            string->str, string->len, string->bytes);
 
    ss_string_free(string, 1);
 
    return 0;
}

This is the basic "Hello World" programm using SStrings (using the garbage collector):

"Hello World" Example 
#include <sstrings2.h>
#include <stdio.h>
 
int main(void)
{
    ss_string *string;
 
    if(!ss_string_enable_gc())
    {
        fprintf(stderr, "Gargabe collector failed. Aborting...\n");
        return 1;
    }
 
    string = ss_string_new("Hello, World!");
 
    if(!string)
    {
         ss_string_perror("ss_string_new");
         return 1;
    }
 
    printf("The ss_string object saves:\nstring = %s\n length = %d\nbytes = %d\n", 
            string->str, string->len, string->bytes);
 
 
    return 0;
}

You don't strictly need the GNU GCC to compile your source code with SString support. But I will show GCC examples only!

BASH 
$ gcc -ohello hello.c -lsstrings2

V. Installing SStrings top Top

You first need to fetch the tarballs

After having decompressed the tarball you must execute in your shell:

BASH 
$ cd sstring-2.0.1
$ ./configure --prefix=/usr
$ make
$ make install # this must be done as 'root'
 
$ make test # if you want the autotest to be executed 
 

For more information about the installation take a look at the INSTALL file in the tarball.

VI. Using SStrings top Top

You have to include the sstrings2.h in your source code. To link with the GNU GCC you have to use the -lsstrings2 option. Take a look at "Hello World" with SStrings.

Valid XHTML 1.0 Strict   Valid CSS! This document is release under the terms of the GPL-2. Written by Pablo Yanez Trujillo