C module for working with dynamic strings.

CString works by initialising a "String" Data Structure which is defined in CString module. "String" is basically a struct which contains three fields.

The first field is "str" which is of char pointer type and stores the actual character data. "str" is stored in the heap memory and is allocated and controlled using malloc(), realloc() and free(), just like other data present in the heap memory.

The second field is "ulen" which is of 'int' type and stores the number of characters filled in the allocated heap memory. This is basically the "length of the dynamic string".

The third field is "alen" which is of 'int' type and stores the number of characters allocated to char pointer "str" in the heap memory.

'ulen' and 'alen' fields are maintained by the CString Module automatically as and when required.

While adding a character/"String", the module checks if "ulen" is less than "alen". If it is not, then the module calls realloc() and adds the required memory along with a standard buffer memory of 512 bytes to the "str" pointer.

This allows the module user to freely add as many characters as the user likes making it a dynamic string.

CString module does provide basic functions like substring(), index(), etc. even for char pointer data type directly. More details are given in "Functions" section.

Please do note that even though this module protects from attacks like Buffer Overflow, Stack Overflow, etc., it is still the responsibility of the module user to manage heap memory as the module will keep calling realloc() and adding memory to the "str" pointer until Memory Overflow happens, in which case the "str" pointer will be removed.

Simply include the "cstring.h" file in your program.

Simply use this code (Modify according to your needs):

#include <stdio.h>
#include "cstring.h"

void main()
{
    String string = newString(0);       //newString() will be explained in detail in the Functions section.
    addStr(string, "Abhay Tripathi");   //addStr() will be explained in detail in the Functions section.
    printf("Value of str: %s.\n", string.str);
    printf("Allocated Memory to str: %d.\n", string.alen);
    printf("Used Memory by str: %d.\n", string.ulen);
}

One can assign a char using direct index assigning method provided for char pointers in C. But, the index should be below and not equal to "ulen" field value for the String struct to work correctly. Failing to do so may result in Buffer Overflow or Undefined Behaviour.

For eg., if we execute:

String name = newString(5);     //newString() will be explained in detail in the Functions section.
addStr(name, "Abhay");          //addStr() will be explained in detail in the Functions section.

then "ulen" field value is equal to 5. So, if we execute:

name.str[2] = 't';
printf("%s", name.str);

it will print "Abtay" perfectly. But if we execute:

name.str[6] = 'w';
printf("%s", name.str);

then it will result in Buffer Overflow and in turn Undefined Behaviour varying from device to device as only 5 + 1 = 6 Bytes were allocated to "name.str" char pointer.

The functions provided by the CString Module is listed below. Click on the function to get detailed information about it.

• newString(int)
• val(String *)
• addChar(String *, char)
• add(String *, String *)
• addStr(String *, char *)
• indx(String *, String *)
• indxStr(String *, char *)
• sindx(char *, char *) - Direct char pointer function
• contains(String *, String *)
• containsStr(String *, char *)
• scontains(char *, char *) - Direct char pointer function
• replace(String *, String *, String *)
• replaceStr(String *, char *, char *)
• substring(String *, int, int)
• strsubstring(char *, int, int)
• ssubstring(char *, int, int) - Direct char pointer function
• trim(String *, int, int)
• strim(char *, int, int) - Direct char pointer function
• isNumeric(String *)
• isStrNumeric(char *) - Direct char pointer function
• toInteger(String *)
• strToInteger(char *) - Direct char pointer function
• clear(String *)
• freestr(String *)

The detailed information about the functions listed in the above section is provided below.

String string = newString(SIZE);

Creates char pointer and allocates SIZE Bytes using malloc() and assigns 0th index as "\0" (Because in C, String is always terminated by "\0"). If SIZE is 0, then STANDARD SIZE i.e. 512 Bytes are allocated. Then, creates new String struct defined in the module, sets ulen and alen as 0 (because at the time of creation, the allocated memory is empty apart from the "\0" character which is a null character and hence is not counted in the length of the String) and returns the new String struct.

char *actualCharValue = val(&string);

Returns char pointer of actual char value i.e. "str" field.

Parameters

• String: String of which the "str" field is required.

int addCharStatus = addChar(&string, c);

Concatenates char c to String string, updating the allocated memory if required and updating ulen and alen accordingly. Returns 0 if concatenation operation was successful or -1 if the operation failed due to Memory Overflow.

Parameters

• String: String on which the char has to be concatenated.
• char: char which has to be concatenated.

int addStatus = add(&string, &toBeConcatenated);

Concatenates String toBeConcatenated to String string, updating the allocated memory if required and updating ulen and alen accordingly. Returns 0 if concatenation operation was successful or -1 if the operation failed due to Memory Overflow.

Parameters

• String: String on which the String has to be concatenated.
• String: String which has to be concatenated.

int addStatus = addStr(&string, toBeConcatenated);

Concatenates char pointer toBeConcatenated to String string, updating the allocated memory if required and updating ulen and alen accordingly. Returns 0 if concatenation operation was successful or -1 if the operation failed due to Memory Overflow.

Parameters

• String: String on which the char pointer has to be concatenated.
• char pointer: char pointer which has to be concatenated.

int pos = indx(&string, &toBeFound);

Returns position of first occurence of String toBeFound if it is found, else returns -1.

Parameters

• String: String in which String toBeFound will be searched.
• String: String which has to be searched.

int pos = indxStr(&string, toBeFound);

Returns position of first occurence of char pointer toBeFound if it is found, else returns -1.

Parameters

• String: String in which char pointer toBeFound will be searched.
• char pointer: char pointer which has to be searched.

int pos = sindx(charString, toBeFound);

Returns position of first occurence of char pointer toBeFound if it is found, else returns -1.

Parameters

• char pointer: char pointer in which char pointer toBeFound will be searched.
• char pointer: char pointer which has to be searched.

int containsStatus = contains(&string, &toBeFound);

Returns 1 if String string contains String toBeFound else 0.

Parameters

• String: String in which String toBeFound will be searched.
• String: String which has to be searched.

int containsStatus = containsStr(&string, toBeFound);

Returns 1 if String string contains char pointer toBeFound else 0.

Parameters

• String: String in which char pointer toBeFound will be searched.
• char pointer: char pointer which has to be searched.

int containsStatus = scontains(charString, toBeFound);

Returns 1 if char pointer charString contains char pointer toBeFound else 0.

Parameters

• char pointer: char pointer in which char pointer toBeFound will be searched.
• char pointer: char pointer which has to be searched.

string = replace(&string, &toBeFound, &toBeReplaced);

Returns New String which was generated by replacing String toBeFound with String toBeReplaced on all occurences.

Parameters

• String: String in which String toBeFound will be searched and replaced with String toBeReplaced.
• String: String which has to be searched.
• String: String which has to be replaced with String toBeFound.

string = replaceStr(&string, toBeFound, toBeReplaced);

Returns New String which was generated by replacing char pointer toBeFound with char pointer toBeReplaced on all occurences.

Parameters

• String: String in which char pointer toBeFound will be searched and replaced with char pointer toBeReplaced.
• char pointer: char pointer which has to be searched.
• char pointer: char pointer which has to be replaced with char pointer toBeFound.

String subString = substring(&string, startIndex, endIndex);

Returns New String which was generated by characters which were present between startIndex and endIndex (including startIndex and excluding endIndex).

Parameters

• String: String for which substring will be generated.
• int: index from which the characters will be included (including the index itself).
• int: index till which the characters will be included (excluding the index itself).

String subString = strsubstring(charString, startIndex, endIndex);

Returns New String which was generated by characters which were present between startIndex and endIndex (including startIndex and excluding endIndex).

Parameters

• char pointer: char pointer for which substring will be generated.
• int: index from which the characters will be included (including the index itself).
• int: index till which the characters will be included (excluding the index itself).

char *subString = ssubstring(charString, startIndex, endIndex);

Returns New char pointer which was generated by characters which were present between startIndex and endIndex (including startIndex and excluding endIndex).

Parameters

• char pointer: char pointer for which substring will be generated.
• int: index from which the characters will be included (including the index itself).
• int: index till which the characters will be included (excluding the index itself).

trim(&string, startIndex, endIndex);

Trims String string by replacing whole char value with substring of char value using substring(&string, startIndex, endIndex).

Parameters

• Same as substring() function.

strim(charString, startIndex, endIndex);

Trims char pointer charString by replacing whole char value with substring of char value using ssubstring(charString, startIndex, endIndex).

Parameters

• Same as ssubstring() function.

int numericStatus = isNumeric(&string);

Returns 1 if String string is numeric else 0.

Parameters

• String: String to be checked.

int numericStatus = isStrNumeric(charString);

Returns 1 if char pointer charString is numeric else 0.

Parameters

• char pointer: char pointer to be checked.

int numericString = toInteger(&string);

Returns int version of String string. The algorithm ignores non-numeric characters.

Parameters

• String: String to be converted.

int numericString = strToInteger(charString);

Returns int version of char pointer charString. The algorithm ignores non-numeric characters.

Parameters

• char pointer: char pointer to be converted.

clear(&string);

Sets "ulen" field to 0, hence over-writing any existing data on subsequent add()/addChar() calls.

Warning

Calling clear() does not delete the existing data which was present in the allocated heap memory.

Parameters

• String: String to be cleared.

freestr(&string);

Frees "str" field i.e. char pointer containing the actual character value of the String using free(), freeing the allocated heap memory.

Parameters

• String: String to be freed.

This module is very useful for projects where huge amount of dynamic data is involved and efficiency and speed of C programming is required!