libstree Manual
Prev |  | Next

# lst_string

## Name

lst_string --

## Synopsis

    #define     LST_STRING_END
    #define     LST_EMPTY_STRING
    void        (*LST_StringCB)                 (LST_String *string,
                                                 void *data);
    int         (*LST_StringItemCmpFunc)        (void *item1,
                                                 void *item2);
    char*       (*LST_StringPrintFunc)          (LST_StringIndex *index);
    void        (*LST_StringItemCopyFunc)       (void *src,
                                                 void *dst);
    LST_String* lst_string_new                  (void *data,
                                                 u_int item_size,
                                                 u_int num_items);
    void        lst_string_init                 (LST_String *string,
                                                 void *data,
                                                 u_int item_size,
                                                 u_int num_items);
    void        lst_string_free                 (LST_String *string);
    void*       lst_string_free_keep_data       (LST_String *string);
    u_int       lst_string_get_length           (LST_String *string);
    void*       lst_string_get_item             (LST_String *string,
                                                 u_int index);
    const char* lst_string_print                (LST_String *string);
    void        lst_string_item_copy            (LST_String *src,
                                                 u_int src_index,
                                                 LST_String *dst,
                                                 u_int dst_index);
    int         lst_string_eq                   (LST_String *s1,
                                                 u_int item1,
                                                 LST_String *s2,
                                                 u_int item2);
    u_int       lst_string_items_common         (LST_String *s1,
                                                 u_int off1,
                                                 LST_String *s2,
                                                 u_int off2,
                                                 u_int max_len);
    char*       lst_string_print_hex            (LST_StringIndex *index);
    LST_StringClass* lst_stringclass_new        (LST_StringItemCmpFunc cmp_func,
                                                 LST_StringItemCopyFunc copy_func,
                                                 LST_StringPrintFunc print_func);
    void        lst_stringclass_free            (LST_StringClass *sclass);
    void        lst_stringclass_set_defaults    (LST_StringItemCmpFunc cmp_func,
                                                 LST_StringItemCopyFunc copy_func,
                                                 LST_StringPrintFunc print_func);
    LST_StringClass* lst_string_set_class       (LST_String *string,
                                                 LST_StringClass *sclass);
    void        lst_string_index_init           (LST_StringIndex *index);
    void        lst_string_index_copy           (LST_StringIndex *src,
                                                 LST_StringIndex *dst);
    LST_StringSet* lst_stringset_new            (void);
    void        lst_stringset_add               (LST_StringSet *set,
                                                 LST_String *string);
    void        lst_stringset_remove            (LST_StringSet *set,
                                                 LST_String *string);
    void        lst_stringset_foreach           (LST_StringSet *set,
                                                 LST_StringCB callback,
                                                 void *user_data);
    void        lst_stringset_free              (LST_StringSet *set);

## Description

## Details

### LST_STRING_END

    #define LST_STRING_END   UINT_MAX

### LST_EMPTY_STRING

    #define LST_EMPTY_STRING UINT_MAX

### LST_StringCB ()

    void        (*LST_StringCB)                 (LST_String *string,
                                                 void *data);

`string` :

  string passed in.

`data` :

  arbitrary user data.

### LST_StringItemCmpFunc ()

    int         (*LST_StringItemCmpFunc)        (void *item1,
                                                 void *item2);

The function compares two string items.

`item1` :

  first string item.

`item2` :

  second string item.

Returns :

  0 when equal, -1 when the first item is "smaller" than the second, 1 when the first is "larger" than the second.

### LST_StringPrintFunc ()

    char*       (*LST_StringPrintFunc)          (LST_StringIndex *index);

The function creates a string representation of the subrange of the string specified in `index` and returns it. The result should be statically allocated and not need to be freed by the caller. To make the function more robust you should make it work even if it is called multiple times withing the same `printf()`-like function.

`index` :

  substring specifier.

Returns :

  string representation.

### LST_StringItemCopyFunc ()

    void        (*LST_StringItemCopyFunc)       (void *src,
                                                 void *dst);

Functions of this signature copy a string item at `src` over to a string item at *dst.

`src` :

  address of source item.

`dst` :

  address of destination item.

### lst_string_new ()

    LST_String* lst_string_new                  (void *data,
                                                 u_int item_size,
                                                 u_int num_items);

The function creates `item_size` * `num_items` bytes of memory and copies `data` into that area, then returns the new string.

`data` :

  data to store in string.

`item_size` :

  size of a single string item, in bytes.

`num_items` :

  number of items the string stores.

Returns :

  new string, or `NULL` when out of memory.

### lst_string_init ()

    void        lst_string_init                 (LST_String *string,
                                                 void *data,
                                                 u_int item_size,
                                                 u_int num_items);

The function initializes an existing string object, making it use the passed data directly without copying it. It is thus faster than lst_string_new, and recommended for tight loops, etc.

`string` :

  string object to initialize.

`data` :

  string data to initialize with.

`item_size` :

  size of a single string item, in bytes.

`num_items` :

  length of string.

### lst_string_free ()

    void        lst_string_free                 (LST_String *string);

The function cleans up all of the memory occupied by `string`. It is safe to call this on strings initialized using `lst_string_init()` which are using external data, as in that case the string data itself is not touched.

`string` :

  string to clean up.

### lst_string_free_keep_data ()

    void*       lst_string_free_keep_data       (LST_String *string);

The function cleans up the memory occupied by `string` without releasing the actual string data, which it returns to the caller.

`string` :

  string to clean up.

Returns :

  actual string data.

### lst_string_get_length ()

    u_int       lst_string_get_length           (LST_String *string);

The function returns the number of items in the string. Always use this function and never access any of the string members directly to obtain that value.

`string` :

  string to return length of.

Returns :

  length of `string`.

### lst_string_get_item ()

    void*       lst_string_get_item             (LST_String *string,
                                                 u_int index);

`string` :

  string to look up item in.

`index` :

  number of element in string to find, starting at 0.

Returns :

  a pointer to the element in the string at position `index`, or `NULL` when the index is invalid.

### lst_string_print ()

    const char* lst_string_print                (LST_String *string);

The creates an ASCII string verions of `string` and returns it as a pointer to static memory. The way this mapping is implemented depends on the string class active for this string, see @`lst_string_set_class()`.

`string` :

  string to print.

Returns :

  pointer to static string buffer.

### lst_string_item_copy ()

    void        lst_string_item_copy            (LST_String *src,
                                                 u_int src_index,
                                                 LST_String *dst,
                                                 u_int dst_index);

The function copies the item found at `src_index` in `src` into the item `dst_index` of string `dst`.

`src` :

  source string.

`src_index` :

  item in source string, starting at 0.

`dst` :

  destination string.

`dst_index` :

  item to copy to.

### lst_string_eq ()

    int         lst_string_eq                   (LST_String *s1,
                                                 u_int item1,
                                                 LST_String *s2,
                                                 u_int item2);

The function compares the items specified via the input parameters. The way this is implemented depends on the string class for the strings involved, see `lst_string_set_class()`.

`s1` :

  first string.

`item1` :

  item in `s1`.

`s2` :

  second string.

`item2` :

  item in `s2`.

Returns :

  value > 0 when equal, 0 otherwise.

### lst_string_items_common ()

    u_int       lst_string_items_common         (LST_String *s1,
                                                 u_int off1,
                                                 LST_String *s2,
                                                 u_int off2,
                                                 u_int max_len);

The function compares items in `s1` and `s2` from the given offsets, counting how many are equal. The way the comparison works depends on the string class active for the strings involved, see `lst_string_set_class()`.

`s1` :

  first string.

`off1` :

  item in `s1`.

`s2` :

  second string.

`off2` :

  item in `s2`.

`max_len` :

  maximum number of items to compare.

Returns :

  number of identical items.

### lst_string_print_hex ()

    char*       lst_string_print_hex            (LST_StringIndex *index);

For convenience, this is a printer implementation that returns a hex representation of the data contained in the string. You can call this function up to three times from within the same `printf()`-like function.

`index` :

  string region to print.

Returns :

  hex representation in statically allocated string, copy this if you need to keep it around.

### lst_stringclass_new ()

    LST_StringClass* lst_stringclass_new        (LST_StringItemCmpFunc cmp_func,
                                                 LST_StringItemCopyFunc copy_func,
                                                 LST_StringPrintFunc print_func);

Strings are made generic in libstree through virtualization of the essential string operations. Each string in libstree has a string class specifying how these operations are implemented. By default, the strings support ASCII strings of single-byte characters as normally used. Using this function, you can create your own string classes. If you want to keep some of the default implementations, just pass `NULL` for those. Get rid of the class using `lst_stringclass_free()`.

`cmp_func` :

  string item compare function.

`copy_func` :

  string item copy function.

`print_func` :

  string print function.

Returns :

  new string class.

### lst_stringclass_free ()

    void        lst_stringclass_free            (LST_StringClass *sclass);

The function releases the memory occupied by `sclass`.

`sclass` :

  class to clean up.

### lst_stringclass_set_defaults ()

    void        lst_stringclass_set_defaults    (LST_StringItemCmpFunc cmp_func,
                                                 LST_StringItemCopyFunc copy_func,
                                                 LST_StringPrintFunc print_func);

This function sets new default string manipulation functions for all strings. Beware, this will also implicitly change the implementations for all previously created strings with default handlers. If you want the original handler, pass `NULL` for the implementation desired.

`cmp_func` :

  string item compare function.

`copy_func` :

  string item copy function.

`print_func` :

  string print function.

### lst_string_set_class ()

    LST_StringClass* lst_string_set_class       (LST_String *string,
                                                 LST_StringClass *sclass);

Use this function to set a string's class. Pass `NULL` to reset to default class.

`string` :

  string to change string class for.

`sclass` :

  new string class.

Returns :

  the previously set string class.

### lst_string_index_init ()

    void        lst_string_index_init           (LST_StringIndex *index);

The function initializes a string index. Used internally.

`index` :

  index initialized.

### lst_string_index_copy ()

    void        lst_string_index_copy           (LST_StringIndex *src,
                                                 LST_StringIndex *dst);

Used internally.

`src` :

  source index.

`dst` :

  destination index.

### lst_stringset_new ()

    LST_StringSet* lst_stringset_new            (void);

The function creates a new stringset. Stringsets are the way you pass multiple strings to an algorithm. You basically create a string set, then add strings to the set, pass the set to an algorithm, and clean up the set afterwards.

Returns :

  new, empty set.

### lst_stringset_add ()

    void        lst_stringset_add               (LST_StringSet *set,
                                                 LST_String *string);

The function adds a string to the set.

`set` :

  set to add string to.

`string` :

  string to add.

### lst_stringset_remove ()

    void        lst_stringset_remove            (LST_StringSet *set,
                                                 LST_String *string);

The function removes a string from a string set.

`set` :

  set to remove string from.

`string` :

  string to remove.

### lst_stringset_foreach ()

    void        lst_stringset_foreach           (LST_StringSet *set,
                                                 LST_StringCB callback,
                                                 void *user_data);

The function calls `callback` for each string in `set`, passing it that string and `user_data`.

`set` :

  set to iterate.

`callback` :

  callback to call for each item.

`user_data` :

  arbitrary data passed through to `callback`.

### lst_stringset_free ()

    void        lst_stringset_free              (LST_StringSet *set);

The function releases all the memory claimed by `set`, including all the strings it contains.

`set` :

  set to clean up.

Prev | Home | Next
lst_structs | Up | lst_debug