SimGrid: String related functions

SimGrid 3.10 Versatile Simulation of Distributed Systems

- Home page
- Online documentation
- Dev's Corner

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
String related functions
Grounding features

String manipulation functions. More...

## Functions
int | asprintf (char **ptr, const char *fmt,...) _XBT_GNUC_PRINTF(2
| print to allocated string (reimplemented when not provided by the system)
int int | vasprintf (char **ptr, const char *fmt, va_list ap)
| print to allocated string (reimplemented when not provided by the system)
char * | bvprintf (const char *fmt, va_list ap)
| print to allocated string
char * | bprintf (const char *fmt,...) _XBT_GNUC_PRINTF(1
| print to allocated string
ssize_t | xbt_getline (char **lineptr, size_t *n, FILE *stream)
| Get a single line from the stream (reimplementation of the GNU getline)
void | xbt_str_rtrim (char *s, const char *char_list)
| Strip whitespace (or other characters) from the end of a string.
void | xbt_str_ltrim (char *s, const char *char_list)
| Strip whitespace (or other characters) from the beginning of a string.
void | xbt_str_trim (char *s, const char *char_list)
| Strip whitespace (or other characters) from the end and the begining of a string.
xbt_dynar_t | xbt_str_split (const char *s, const char *sep)
| Splits a string into a dynar of strings.
xbt_dynar_t | xbt_str_split_quoted (const char *s)
| Splits a string into a dynar of strings, taking quotes into account.
xbt_dynar_t | xbt_str_split_quoted_in_place (char *s)
| Just like xbt_str_split_quoted (Splits a string into a dynar of strings), but without memory allocation.
xbt_dynar_t | xbt_str_split_str (const char *s, const char *sep)
| This functions splits a string after using another string as separator For example A!!B!!C splitted after !! will return the dynar {A,B,C}.
char * | xbt_str_join (xbt_dynar_t dynar, const char *sep)
| Join a set of strings as a single string.
char * | xbt_str_join_array (const char *const *strs, const char *sep)
| Join a set of strings as a single string.
void | xbt_str_subst (char *str, char from, char to, int amount)
| Substitutes a char for another in a string.
char * | xbt_str_varsubst (const char *str, xbt_dict_t patterns)
| Replaces a set of variables by their values.
void | xbt_str_strip_spaces (char *)
| Replace double whitespaces (but no other characters) from the string.
char * | xbt_str_diff (const char *a, const char *b)
| Compute the unified diff of two strings.
char * | xbt_str_from_file (FILE *file)
| creates a new string containing what can be read on a fd
static unsigned int | xbt_str_hash_ext (const char *str, int str_len)
| Returns the hash code of a string.
static unsigned int | xbt_str_hash (const char *str)
| Returns the hash code of a string.

## Detailed Description

String manipulation functions.

This module defines several string related functions. We redefine some quite classical functions on the platforms were they are not nativaly defined (such as xbt_getline() or asprintf()), while some other are a bit more exotic.

## Function Documentation

int asprintf | ( | char ** | ptr,
|  | const char * | fmt,
|  |  | ...
| ) |  |

print to allocated string (reimplemented when not provided by the system)

The functions asprintf() and vasprintf() are analogues of sprintf() and vsprintf(), except that they allocate a string large enough to hold the output including the terminating null byte, and return a pointer to it via the first parameter. This pointer should be passed to free(3) to release the allocated storage when it is no longer needed.

int int vasprintf | ( | char ** | ptr,
|  | const char * | fmt,
|  | va_list | ap
| ) |  |

print to allocated string (reimplemented when not provided by the system)

See asprintf()

char* bvprintf | ( | const char * | fmt,
|  | va_list | ap
| ) |  |

print to allocated string

Works just like vasprintf(), but returns a pointer to the newly created string, or aborts on error.

char* bprintf | ( | const char * | fmt,
|  |  | ...
| ) |  |

print to allocated string

Works just like asprintf(), but returns a pointer to the newly created string, or aborts on error.

ssize_t xbt_getline | ( | char ** | buf,
|  | size_t * | n,
|  | FILE * | stream
| ) |  |

Get a single line from the stream (reimplementation of the GNU getline)

This is a reimplementation of the GNU getline function, so that our code don't depends on the GNU libc.

xbt_getline() reads an entire line from stream, storing the address of the buffer containing the text into *buf. The buffer is null-terminated and includes the newline character, if one was found.

If *buf is NULL, then xbt_getline() will allocate a buffer for storing the line, which should be freed by the user program.

Alternatively, before calling xbt_getline(), *buf can contain a pointer to a malloc()-allocated buffer *n bytes in size. If the buffer is not large enough to hold the line, xbt_getline() resizes it with realloc(), updating *buf and *n as necessary.

In either case, on a successful call, *buf and *n will be updated to reflect the buffer address and allocated size respectively.

void xbt_str_rtrim | ( | char * | s,
|  | const char * | char_list
| ) |  |

Strip whitespace (or other characters) from the end of a string.

Strips the whitespaces from the end of s. By default (when char_list=NULL), these characters get stripped:

- " " (ASCII 32 (0x20)) space.
- "\t" (ASCII 9 (0x09)) tab.
- "\n" (ASCII 10 (0x0A)) line feed.
- "\r" (ASCII 13 (0x0D)) carriage return.
- "\0" (ASCII 0 (0x00)) NULL.
- "\x0B" (ASCII 11 (0x0B)) vertical tab.

Parameters

  s | The string to strip. Modified in place.
  char_list | A string which contains the characters you want to strip.

void xbt_str_ltrim | ( | char * | s,
|  | const char * | char_list
| ) |  |

Strip whitespace (or other characters) from the beginning of a string.

Strips the whitespaces from the begining of s. By default (when char_list=NULL), these characters get stripped:

- " " (ASCII 32 (0x20)) space.
- "\t" (ASCII 9 (0x09)) tab.
- "\n" (ASCII 10 (0x0A)) line feed.
- "\r" (ASCII 13 (0x0D)) carriage return.
- "\0" (ASCII 0 (0x00)) NULL.
- "\x0B" (ASCII 11 (0x0B)) vertical tab.

Parameters

  s | The string to strip. Modified in place.
  char_list | A string which contains the characters you want to strip.

void xbt_str_trim | ( | char * | s,
|  | const char * | char_list
| ) |  |

Strip whitespace (or other characters) from the end and the begining of a string.

Strips the whitespaces from both the beginning and the end of s. By default (when char_list=NULL), these characters get stripped:

- " " (ASCII 32 (0x20)) space.
- "\t" (ASCII 9 (0x09)) tab.
- "\n" (ASCII 10 (0x0A)) line feed.
- "\r" (ASCII 13 (0x0D)) carriage return.
- "\0" (ASCII 0 (0x00)) NULL.
- "\x0B" (ASCII 11 (0x0B)) vertical tab.

Parameters

  s | The string to strip.
  char_list | A string which contains the characters you want to strip.

xbt_dynar_t xbt_str_split | ( | const char * | s,
|  | const char * | sep
| ) |  |

Splits a string into a dynar of strings.

Parameters

  s,: | the string to split
  sep,: | a string of all chars to consider as separator.

By default (with sep=NULL), these characters are used as separator:

- " " (ASCII 32 (0x20)) space.
- "\t" (ASCII 9 (0x09)) tab.
- "\n" (ASCII 10 (0x0A)) line feed.
- "\r" (ASCII 13 (0x0D)) carriage return.
- "\0" (ASCII 0 (0x00)) NULL.
- "\x0B" (ASCII 11 (0x0B)) vertical tab.

xbt_dynar_t xbt_str_split_quoted | ( | const char * | s | ) |

Splits a string into a dynar of strings, taking quotes into account.

It basically does the same argument separation than the shell, where white spaces can be escaped and where arguments are never split within a quote group. Several subsequent spaces are ignored (unless within quotes, of course). You may want to trim the input string, if you want to avoid empty entries

xbt_dynar_t xbt_str_split_quoted_in_place | ( | char * | s | ) |

Just like xbt_str_split_quoted (Splits a string into a dynar of strings), but without memory allocation.

The string passed as argument must be writable (not const) The elements of the dynar are just parts of the string passed as argument. So if you don't store that argument elsewhere, you should free it in addition to freeing the dynar. This can be done by simply freeing the first argument of the dynar: free(xbt_dynar_get_ptr(dynar,0));

Actually this function puts a bunch of \0 in the memory area you passed as argument to separate the elements, and pushes the address of each chunk in the resulting dynar. Yes, that's uneven. Yes, that's gory. But that's efficient.

xbt_dynar_t xbt_str_split_str | ( | const char * | s,
|  | const char * | sep
| ) |  |

This functions splits a string after using another string as separator For example A!!B!!C splitted after !! will return the dynar {A,B,C}.

Returns
  An array of dynars containing the string tokens

char* xbt_str_join_array | ( | const char *const * | strs,
|  | const char * | sep
| ) |  |

Join a set of strings as a single string.

The parameter must be a NULL-terminated array of chars, just like xbt_dynar_to_array() produces

void xbt_str_subst | ( | char * | str,
|  | char | from,
|  | char | to,
|  | int | occurence
| ) |  |

Substitutes a char for another in a string.

Parameters

  str | the string to modify
  from | char to search
  to | char to put instead
  occurence | number of changes to do (=0 means all)

char* xbt_str_varsubst | ( | const char * | str,
|  | xbt_dict_t | patterns
| ) |  |

Replaces a set of variables by their values.

Parameters

  str | The input of the replacement process
  patterns | The changes to apply

Returns
  The string modified

Both '$toto' and '${toto}' are valid (and the two writing are equivalent).

If the variable name contains spaces, use the brace version (ie, ${toto tutu})

You can provide a default value to use if the variable is not set in the dict by using '${var:=default}' or '${var:-default}'. These two forms are equivalent, even if they shouldn't to respect the shell standard (:= form should set the value in the dict, but does not) (BUG).

void xbt_str_strip_spaces | ( | char * | s | ) |

Replace double whitespaces (but no other characters) from the string.

The function modifies the string so that each time that several spaces appear, they are replaced by a single space. It will only do so for spaces (ASCII 32, 0x20).

Parameters

  s | The string to strip. Modified in place.

char* xbt_str_from_file | ( | FILE * | file | ) |

creates a new string containing what can be read on a fd