- Main Page
- Data Structures
- Files
- Related Pages

# stringop.h File Reference

String Operations. More...

`#include "generic.h"`

Go to the source code of this file.

## Enumerations
enum | { VL_PROT_UNKNOWN = -1, VL_PROT_NONE = 0, VL_PROT_ASCII, VL_PROT_BINARY }
| File protocols. More...
## Functions
int | vl_string_copy (char *dst, int n, char const *src)
| Copy string.
int | vl_string_copy_sub (char *dst, int n, char const *beg, char const *end)
| Copy substring.
char * | vl_string_parse_protocol (char const *str, int *prot)
| Parse string prefix for file protocol.
char const * | vl_string_protocol_name (int prot)
| Get protocol name.
int | vl_string_basename (char *dst, int n, char const *src, int n_ext)
| Extract base of file name.
int | vl_string_replace_wildcard (char *dst, int n, char const *src, char wild, char esc, char const *repl)
| Replace wildcard by string.
char * | vl_string_find_char_rev (char const *beg, char const *end, char c)
| Search character in reversed order.
int | vl_string_length (char const *str)
| Calculate string length.
int | vl_string_casei_cmp (const char *s1, const char *s2)
| Compare strings case-insensitive.

## Detailed Description

Author:
  Andrea Vedaldi

This module impelements common strings operations. All functions that write to strings use range checking, which makes them safer and more robust than standard POSIX equivalent (see Detecting overflow).

## Detecting overflow

Functions of this module may write a string as a result of their operation. The string is written to a buffer passed to the function along with its length `n` and is `NUL` terminated. The function never writes more than `n` characters, thus preventing overflow (this includes the `NUL` character terminating the string). The function also returns the total number `r` of chatarcters that would have been written if the buffer was big enough (not counting the terminating `NUL`). Thus:

- overflow errors are be detected by testing whether `r` >= `n`;
- `r` can be used to re-allocate a sufficiently large buffer and repeat the operation;
- as long as n >= 0 the result is always `NUL` terminated;
- if n = 0 nothing is actually written.

Author:
  Andrea Vedaldi

## Enumeration Type Documentation

anonymous enum

The following is a list of the supported protocols with their symbolic names:

- ASCII protocol (VL_PROT_ASCII). Symbolic name: `ascii`.
- Binary protocol (VL_PROT_BINARY). Symbolic name: `binary`.

Enumerator:

  VL_PROT_UNKNOWN | unknown protocol
  VL_PROT_NONE | no protocol
  VL_PROT_ASCII | ASCII protocol
  VL_PROT_BINARY | Binary protocol

## Function Documentation

int vl_string_basename | ( | char * | dst,
|  | int | n,
|  | char const * | src,
|  | int | n_ext |
| ) |  |  |

Parameters:

  | dst | destination buffer.
  | n | size of destination buffer.
  | src | string to process.
  | n_ext | maximum number of extensions to strip.

The function removes leading path and (at most) `n_ext` trailing extensions from the string src and writes the result to the buffer dst of length n.

The leading path is the suffix that ends with the last occurence of the ``\'` or ``/'` characters. A trailing extension is the shortest suffix starting with the ``.'` character.

Returns:
  length of the result.

See also:
  vl-stringop-err.

int vl_string_casei_cmp | ( | const char * | s1,
|  | const char * | s2 |
| ) |  |  |

Parameters:

  | s1 | fisrt string.
  | s2 | second string.

Returns:
  0 if the strings are equal, >0 if the first string is greater (in lexicographical order) and <0 otherwise.

int vl_string_copy | ( | char * | dst,
|  | int | n,
|  | char const * | src |
| ) |  |  |

Parameters:

  | dst | output buffer.
  | n | size of output buffer.
  | src | string to copy.

The function copies the string src to the buffer dst of size n.

Returns:
  length of src.

See also:
  vl-stringop-err.

int vl_string_copy_sub | ( | char * | dst,
|  | int | n,
|  | char const * | beg,
|  | char const * | end |
| ) |  |  |

Parameters:

  | dst | output buffer.
  | n | size of output buffer.
  | beg | start of the source string.
  | end | end of the source string.

The function copies the substring from at beg to end to the buffer dst of size n. The substring terminates when either a `NUL` is found or end is reached (the character pointed by end is not included).

Returns:
  length of the result.

See also:
  vl-stringop-err.

char* vl_string_find_char_rev | ( | char const * | beg,
|  | char const * | end,
|  | char | c |
| ) |  |  |

Parameters:

  | beg | substring beginning.
  | end | substring ending.
  | c | character to search for.

The function searches for the last occurence of the character c in the substring from beg to end (the lattern not being included).

Returns:
  pointer to last occurrence of c, or 0 if none.

int vl_string_length | ( | char const * | str | ) |

Parameters:

  | str | string.

Returns:
  string length.

char* vl_string_parse_protocol | ( | char const * | str,
|  | int * | prot |
| ) |  |  |

Parameters:

  | str | string.
  | prot | protocol code (output).

The function extracts the prefix of the string str terminated by the first occurence of the ``:'` character (if any). It then matches the suffix to the supported protocols. The corresponding protocol code is wrote to prot.

Returns:
  A pointer to the first character after the protocol prefix. The function writes to prot the value VL_PROT_NONE if no suffix is detected and VL_PROT_UNKNOWN if there is a suffix but it cannot be recognized.

char const* vl_string_protocol_name | ( | int | prot | ) |

Parameters:

  | prot | protocol id.

The function returns a pointer to the symbolic name of the protocol prot (see the vl-file-protocols "protocols" list).

Returns:
  pointer to the protocol name. The function returns a null pointer if the protocol code is unknown.

int vl_string_replace_wildcard | ( | char * | dst,
|  | int | n,
|  | char const * | src,
|  | char | wild,
|  | char | esc,
|  | char const * | repl |
| ) |  |  |

Parameters:

  | dst | output buffer.
  | n | size of output buffer.
  | src | input string.
  | wild | widcard character.
  | esc | escape character.
  | repl | replacement string.

The function replaces the occurrence of the specified wildcard character wild by the string repl. The result is written to the buffer dst of size n.

Wildcard characters may be escaped by preceeding them by the esc character. More in general, anything following an occurence of esc character is copied verbatim. To disable the escape characters simply set esc to 0.

Returns:
  length of the result.

See also:
  Detecting overflow.