Welcome to little lamb

Code » limb » master » tree

[master] / src / doc / bytestr.h / byte_get_match_full.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
% limb manual
% byte_get_match_full(3)
% limb 0.1.0
% 2023-07-24

# NAME

byte_get_match_full, byte_get_match - find the (partial) match of a given
string in an array

# SYNOPSIS

    #include <limb/bytestr.h>

```pre hl
int byte_get_match_full(int *<em>first</em>, const char *<em>str</em>, size_t <em>slen</em>,
                        const void *<em>list</em>, size_t <em>offset</em>, size_t <em>llen</em>)
int byte_get_match(int *<em>first</em>, const char *<em>str</em>, size_t <em>slen</em>, const char **<em>list</em>)
```

# DESCRIPTION

The `byte_get_match_full`() function looks inside the array `list` for a string
matching `str` of length `slen`.

Each element of the array `list` must by `llen` bytes long, and must contain,
at byte `offset` (starting from 0), a pointer to a NUL-terminated string to
check against.

An element is said to match if its `slen` first bytes are the same as those from
`str`. In case of an /exact match/, that is the element's NUL-terminated string
is of length `slen`, the search ends and the function returns.

If the element's string is longer however, the search continues through the
remaining elements in `list`. No other elements shall match for a success.
Otherwise -1 is returned, and if `first` is not NULL the value it points to is
set to the index of the first-matching element.

The search goes on until an exact match is found, or an element is found with a
string pointer that is NULL.

! INFO:
! - Elements in `list` need not to be ordered.
! - `first` is not changed if there are no matches. To distinguish between no
!   matches and more than one, it should be initialized to e.g. -1 prior to
!   calling `byte_get_match_full`().
! - `first` is set in case of an exact match, regardless of whether there were
!    partial matches before or not.

The `byte_get_match`() function is similar, but simply takes `list` as a NULL
terminated array of NUL-terminated string pointers.

# RETURN VALUE

These functions return the index of the matching element in `list`, or -1 if
either no element matched `str`, or more than one did. In the later case, if
`first` was not NULL the value it points to is set to the index of the
first-matching element.

# EXAMPLE

Usually you'll probably want to use `byte_get_match`() with a NULL terminated
array of strings.

An example of use for `byte_get_match_full`() would be when the strings are
members of a structure, e.g:

```c
struct user {
  int id;
  const char *name;
} users[];

int r = byte_get_match_full(&first, name, strlen(name), users,
                            offsetof(struct user, name), sizeof(*users));
```

# SEE ALSO

[list_matches_full](3)