Documentation>C API
Data Structures | Enumerations | Functions
stringop.h File Reference

String operations. More...

`#include "generic.h"`

## Data Structures

struct | VlEnumerator
| Member of an enumeration. More...

## Enumerations

enum | { VL_PROT_UNKNOWN = -1 , VL_PROT_NONE = 0 , VL_PROT_ASCII , VL_PROT_BINARY }
| File protocols. More...

## Functions

vl_size | vl_string_copy (char *destination, vl_size destinationSize, char const *source)
| Copy string.
vl_size | vl_string_copy_sub (char *destination, vl_size destinationSize, char const *beginning, char const *end)
| Copy substring.
char * | vl_string_parse_protocol (char const *string, int *protocol)
| Extract the protocol prefix from a string.
char const * | vl_string_protocol_name (int prot)
| Get protocol name.
vl_size | vl_string_basename (char *destination, vl_size destinationSize, char const *source, vl_size maxNumStrippedExtension)
| Extract base of file name.
vl_size | vl_string_replace_wildcard (char *destination, vl_size destinationSize, char const *src, char wildcardChar, char escapeChar, char const *replacement)
| Replace wildcard characters by a string.
char * | vl_string_find_char_rev (char const *beginning, char const *end, char c)
| Search character in reversed order.
vl_size | vl_string_length (char const *string)
| Calculate string length.
int | vl_string_casei_cmp (const char *string1, const char *string2)
| Compare strings case-insensitive.
String enumerations
VlEnumerator * | vl_enumeration_get (VlEnumerator const *enumeration, char const *name)
| Get a member of an enumeration by name.
VlEnumerator * | vl_enumeration_get_casei (VlEnumerator const *enumeration, char const *name)
| Get a member of an enumeration by name (case insensitive).
VlEnumerator * | vl_enumeration_get_by_value (VlEnumerator const *enumeration, vl_index value)
| Get a member of an enumeration by value.

## Detailed Description

Author
  Andrea Vedaldi

stringop.h implements basic string operations. All functions that write to strings use range checking, which makes them safer than some standard POSIX equivalent (see Detecting overflow).

# Enumerations

stringop.h defines a simple enumeration data type. This is given by an array of enumeration members, represented by instances of the VlEnumerator strucutre, each storing a name-value pair. The enumeration must end by a member whose name is set to `NULL`.

Use vl_enumeration_get and vl_enumeration_get_casei to retrieve an enumeration member by name.

# File protocols

stringop.h defines a few file "protocols" and helps parsing them from URL-like formatted strings. The supported protocols are:

File protocols
Protocol | Code | URL prefix
ASCII | VL_PROT_ASCII | `ascii://`
BINARY | VL_PROT_BINARY | `binary://`

# Detecting overflow

stringop.h functions that write a string to a character buffer take both the buffer and its size `n` as input. If `n` is not large enough, the output may be truncated but it is always a null terminated string (provided that `n` >= 1). Such functions also return the length of the string that would have been written `r` (which does not include the terminating null character) had the buffer been large enough. Hence an overflow can be detected by testing if `r` >= `n`, `r` can be used to re-allocate a buffer large enough to contain the result, and the operation can be repeated.

Author
  Andrea Vedaldi

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

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

## Function Documentation

## ◆ vl_enumeration_get()

VlEnumerator * vl_enumeration_get | ( | VlEnumerator const * | enumeration,
|  | char const * | name )

Parameters

  enumeration | array of VlEnumerator objects.
  name | the name of the desired member.

Returns
  enumerator matching name.

If name is not found in the enumeration, then the value `NULL` is returned.

See also
  vl-stringop-enumeration

## ◆ vl_enumeration_get_by_value()

VlEnumerator * vl_enumeration_get_by_value | ( | VlEnumerator const * | enumeration,
|  | vl_index | value )

Parameters

  enumeration | array of VlEnumerator objects.
  value | value of the desired member.

Returns
  enumerator matching value.

If value is not found in the enumeration, then the value `NULL` is returned.

See also
  vl-stringop-enumeration

## ◆ vl_enumeration_get_casei()

VlEnumerator * vl_enumeration_get_casei | ( | VlEnumerator const * | enumeration,
|  | char const * | name )

Parameters

  enumeration | array of VlEnumerator objects.
  name | the name of the desired member.

Returns
  enumerator matching name.

If name is not found in the enumeration, then the value `NULL` is returned. string is matched case insensitive.

See also
  vl-stringop-enumeration

## ◆ vl_string_basename()

vl_size vl_string_basename | ( | char * | destination,
|  | vl_size | destinationSize,
|  | char const * | source,
|  | vl_size | maxNumStrippedExtensions )

Parameters

  destination | destination buffer.
  destinationSize | size of destination buffer.
  source | input string.
  maxNumStrippedExtensions | maximum number of extensions to strip.

Returns
  length of the destination string.

The function removes the leading path and up to `maxNumStrippedExtensions` trailing extensions from the string source and writes the result to the buffer destination.

The leading path is the longest suffix that ends with either the `\` or `/` characters. An extension is a string starting with the `.` character not containing it. For instance, the string `file.png` contains the extension `.png` and the string `file.tar.gz` contains two extensions (`.tar` and ```.gz`).

See also
  Detecting overflow.

## ◆ vl_string_casei_cmp()

int vl_string_casei_cmp | ( | const char * | string1,
|  | const char * | string2 )

Parameters

  string1 | fisrt string.
  string2 | second string.

Returns
  an integer =,<,> 0 if `string1` =,<,> `string2`

## ◆ vl_string_copy()

vl_size vl_string_copy | ( | char * | destination,
|  | vl_size | destinationSize,
|  | char const * | source )

Parameters

  destination | output buffer.
  destinationSize | size of the output buffer.
  source | string to copy.

Returns
  length of the source string.

The function copies the string source to the buffer destination of size destinationSize.

See also
  Detecting overflow.

## ◆ vl_string_copy_sub()

vl_size vl_string_copy_sub | ( | char * | destination,
|  | vl_size | destinationSize,
|  | char const * | beginning,
|  | char const * | end )

Parameters

  destination | output buffer.
  destinationSize | size of output buffer.
  beginning | start of the substring.
  end | end of the substring.

Returns
  length of the destination string.

The function copies the substring from at beginning to end (not included) to the buffer destination of size destinationSize. If, however, the null character is found before end, the substring terminates there.

See also
  Detecting overflow.

## ◆ vl_string_find_char_rev()

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

Parameters

  beginning | pointer to the substring beginning.
  end | pointer to the substring end.
  c | character to search for.

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

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

## ◆ vl_string_length()

vl_size vl_string_length | ( | char const * | string | ) |

Parameters

  string | string.

Returns
  string length.

## ◆ vl_string_parse_protocol()

char * vl_string_parse_protocol | ( | char const * | string,
|  | int * | protocol )

Parameters

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

Returns
  pointer to the first character after the protocol prefix.

The function extracts the prefix of the string string terminated by the first occurrence of the ``:// substring (if any). It then matches the suffix terminated by ``:// to the supported File protocols protocols. If `protocol` is not `NULL`, the corresponding protocol code is written to protocol

The function writes to protocol the value VL_PROT_NONE if no suffix is detected and VL_PROT_UNKNOWN if there is a suffix but it cannot be matched to any of the supported protocols.

## ◆ vl_string_protocol_name()

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

Parameters

  protocol | protocol code.

Returns
  pointer protocol name string.

The function returns a pointer to a string containing the name of the protocol protocol (see the vl-file-protocols protocols list). If the protocol is unknown the function returns the empty string.

## ◆ vl_string_replace_wildcard()

vl_size vl_string_replace_wildcard | ( | char * | destination,
|  | vl_size | destinationSize,
|  | char const * | source,
|  | char | wildcardChar,
|  | char | escapeChar,
|  | char const * | replacement )

Parameters

  destination | output buffer.
  destinationSize | size of the output buffer.
  source | input string.
  wildcardChar | wildcard character.
  escapeChar | escape character.
  replacement | replacement string.

The function replaces the occurrence of the specified wildcard character wildcardChar by the string replacement. The result is written to the buffer destination of size destinationSize.

Wildcard characters may be escaped by preceding them by the esc character. More in general, anything following an occurrence 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.