list.h File Reference

Singly-linked list type. More...

#include <stdbool.h>
#include <stddef.h>
#include "queue.h"

Include dependency graph for list.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ListNode
	A List node for strings. More...

Typedefs
typedef void(*	list_free_t) (void **ptr)

Functions
	STAILQ_HEAD (ListHead, ListNode)
void	mutt_list_clear (struct ListHead *h)
	Free a list, but NOT its strings.
void	mutt_list_copy_tail (struct ListHead *dst, const struct ListHead *src)
	Copy a list into another list.
bool	mutt_list_equal (const struct ListHead *ah, const struct ListHead *bh)
	Compare two string lists.
struct ListNode *	mutt_list_find (const struct ListHead *h, const char *data)
	Find a string in a List.
void	mutt_list_free (struct ListHead *h)
	Free a List AND its strings.
void	mutt_list_free_type (struct ListHead *h, list_free_t fn)
	Free a List of type.
struct ListNode *	mutt_list_insert_after (struct ListHead *h, struct ListNode *n, char *s)
	Insert a string after a given ListNode.
struct ListNode *	mutt_list_insert_head (struct ListHead *h, char *s)
	Insert a string at the beginning of a List.
struct ListNode *	mutt_list_insert_tail (struct ListHead *h, char *s)
	Append a string to the end of a List.
bool	mutt_list_match (const char *s, struct ListHead *h)
	Is the string in the list (see notes).
size_t	mutt_list_str_split (struct ListHead *head, const char *src, char sep)
	Split a string into a list using a separator char.
size_t	mutt_list_write (const struct ListHead *h, struct Buffer *buf)
	Write a list to a buffer.
void	add_to_stailq (struct ListHead *head, const char *str)
	Add a string to a list.
void	remove_from_stailq (struct ListHead *head, const char *str)
	Remove an item, matching a string, from a List.

Detailed Description

Singly-linked list type.

Authors

• Pietro Cerutti
• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file list.h.

Typedef Documentation

list_free_t

typedef void(* list_free_t) (void **ptr)

Definition at line 50 of file list.h.

Function Documentation

STAILQ_HEAD()

STAILQ_HEAD	(	ListHead	,
		ListNode	)

mutt_list_clear()

void mutt_list_clear

(

struct ListHead *

h

)

Free a list, but NOT its strings.

Parameters

h	Head of the List

This can be used when the strings have a different lifetime to the List.

Definition at line 168 of file list.c.

{
  if (!h)
    return;
 
  struct ListNode *np = NULL;
  struct ListNode *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, h, entries, tmp)
  {
    STAILQ_REMOVE(h, np, ListNode, entries);
    FREE(&np);
  }
 
  STAILQ_INIT(h);
}

Here is the caller graph for this function:

mutt_list_copy_tail()

void mutt_list_copy_tail	(	struct ListHead *	dst,
		const struct ListHead *	src )

Copy a list into another list.

Parameters

dst	Destination list
src	Source list

Definition at line 278 of file list.c.

{
  const struct ListNode *np = NULL;
 
  STAILQ_FOREACH(np, src, entries)
  {
    mutt_list_insert_tail(dst, mutt_str_dup(np->data));
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_list_equal()

bool mutt_list_equal	(	const struct ListHead *	ah,
		const struct ListHead *	bh )

Compare two string lists.

Parameters

ah	First string list
bh	Second string list

Return values

true	Lists are identical

To be identical, the lists must both be the same length and contain the same strings. Two empty lists are identical.

Definition at line 220 of file list.c.

{
  if (!ah || !bh)
    return false;
 
  struct ListNode *a = STAILQ_FIRST(ah);
  struct ListNode *b = STAILQ_FIRST(bh);
 
  while (a && b)
  {
    if (!mutt_str_equal(a->data, b->data))
      return false;
 
    a = STAILQ_NEXT(a, entries);
    b = STAILQ_NEXT(b, entries);
  }
  if (a || b)
    return false;
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_list_find()

struct ListNode * mutt_list_find	(	const struct ListHead *	h,
		const char *	data )

Find a string in a List.

Parameters

h	Head of the List
data	String to find

Return values

ptr	ListNode containing the string
NULL	The string isn't found

Definition at line 103 of file list.c.

{
  if (!h)
    return NULL;
 
  struct ListNode *np = NULL;
  STAILQ_FOREACH(np, h, entries)
  {
    if (mutt_str_equal(np->data, data))
    {
      return np;
    }
  }
  return NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_list_free()

void mutt_list_free

(

struct ListHead *

h

)

Free a List AND its strings.

Parameters

h	Head of the List

Definition at line 123 of file list.c.

{
  if (!h)
    return;
 
  struct ListNode *np = NULL;
  struct ListNode *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, h, entries, tmp)
  {
    STAILQ_REMOVE(h, np, ListNode, entries);
    FREE(&np->data);
    FREE(&np);
  }
 
  STAILQ_INIT(h);
}

Here is the caller graph for this function:

mutt_list_free_type()

void mutt_list_free_type	(	struct ListHead *	h,
		list_free_t	fn )

Free a List of type.

Parameters

h	Head of the List
fn	Function to free contents of ListNode

Definition at line 145 of file list.c.

{
  if (!h || !fn)
    return;
 
  struct ListNode *np = NULL;
  struct ListNode *tmp = NULL;
  STAILQ_FOREACH_SAFE(np, h, entries, tmp)
  {
    STAILQ_REMOVE(h, np, ListNode, entries);
    fn((void **) &np->data);
    FREE(&np);
  }
 
  STAILQ_INIT(h);
}

Here is the caller graph for this function:

mutt_list_insert_after()

struct ListNode * mutt_list_insert_after	(	struct ListHead *	h,
		struct ListNode *	n,
		char *	s )

Insert a string after a given ListNode.

Parameters

h	Head of the List
n	ListNode after which the string will be inserted
s	String to insert

Return values

ptr	Newly created ListNode containing the string

Note

The inserted string isn't strdup()d

Definition at line 85 of file list.c.

{
  if (!h || !n)
    return NULL;
 
  struct ListNode *np = MUTT_MEM_CALLOC(1, struct ListNode);
  np->data = s;
  STAILQ_INSERT_AFTER(h, n, np, entries);
  return np;
}

Here is the caller graph for this function:

mutt_list_insert_head()

struct ListNode * mutt_list_insert_head	(	struct ListHead *	h,
		char *	s )

Insert a string at the beginning of a List.

Parameters

h	Head of the List
s	String to insert

Return values

ptr	Newly inserted ListNode containing the string

Note

The inserted string isn't strdup()d

Definition at line 46 of file list.c.

{
  if (!h)
    return NULL;
 
  struct ListNode *np = MUTT_MEM_CALLOC(1, struct ListNode);
  np->data = s;
  STAILQ_INSERT_HEAD(h, np, entries);
  return np;
}

Here is the caller graph for this function:

mutt_list_insert_tail()

struct ListNode * mutt_list_insert_tail	(	struct ListHead *	h,
		char *	s )

Append a string to the end of a List.

Parameters

h	Head of the List
s	String to insert

Return values

ptr	Newly appended ListNode containing the string

Note

The inserted string isn't strdup()d

Definition at line 65 of file list.c.

{
  if (!h)
    return NULL;
 
  struct ListNode *np = MUTT_MEM_CALLOC(1, struct ListNode);
  np->data = s;
  STAILQ_INSERT_TAIL(h, np, entries);
  return np;
}

Here is the caller graph for this function:

mutt_list_match()

bool mutt_list_match	(	const char *	s,
		struct ListHead *	h )

Is the string in the list (see notes).

Parameters

s	String to match
h	Head of the List

Return values

true	String matches a List item (or List contains "*")

This is a very specific function. It searches a List of strings looking for a match. If the list contains a string "*", then it match any input string.

Note

The strings are compared to the length of the List item, e.g. List: "Red" matches Param: "Redwood", but not the other way around.

The case of the strings is ignored.

Definition at line 197 of file list.c.

{
  if (!h)
    return false;
 
  struct ListNode *np = NULL;
  STAILQ_FOREACH(np, h, entries)
  {
    if ((*np->data == '*') || mutt_istr_startswith(s, np->data))
      return true;
  }
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_list_str_split()

size_t mutt_list_str_split	(	struct ListHead *	head,
		const char *	src,
		char	sep )

Split a string into a list using a separator char.

Parameters

head	List to add to
src	String to split
sep	Word separator

Return values

num	Number of items in list

Definition at line 249 of file list.c.

{
  if (!src || (*src == '\0'))
    return 0;
 
  size_t count = 0;
  while (true)
  {
    const char *start = src;
    while ((*src != '\0') && (*src != sep))
      src++;
 
    mutt_list_insert_tail(head, mutt_strn_dup(start, src - start));
    count++;
 
    if ((*src == '\0'))
      break;
 
    src++;
  }
 
  return count;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_list_write()

size_t mutt_list_write	(	const struct ListHead *	h,
		struct Buffer *	buf )

Write a list to a buffer.

Parameters

h	List to write
buf	Buffer for the list

Elements separated by a space. References, and In-Reply-To, use this format.

Definition at line 296 of file list.c.

{
  if (!buf || !h)
    return 0;
 
  struct ListNode *np = NULL;
  STAILQ_FOREACH(np, h, entries)
  {
    buf_addstr(buf, np->data);
    if (STAILQ_NEXT(np, entries))
      buf_addstr(buf, " ");
  }
 
  return buf_len(buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

add_to_stailq()

void add_to_stailq	(	struct ListHead *	head,
		const char *	str )

Add a string to a list.

Parameters

head	String list
str	String to add

Note

Duplicate or empty strings will not be added

Definition at line 319 of file list.c.

{
  /* don't add a NULL or empty string to the list */
  if (!str || (*str == '\0'))
    return;
 
  /* check to make sure the item is not already on this list */
  struct ListNode *np = NULL;
  STAILQ_FOREACH(np, head, entries)
  {
    if (mutt_istr_equal(str, np->data))
    {
      return;
    }
  }
  mutt_list_insert_tail(head, mutt_str_dup(str));
}

Here is the call graph for this function:

Here is the caller graph for this function:

remove_from_stailq()

void remove_from_stailq	(	struct ListHead *	head,
		const char *	str )

Remove an item, matching a string, from a List.

Parameters

head	Head of the List
str	String to match

Note

The string comparison is case-insensitive

Definition at line 344 of file list.c.

{
  if (mutt_str_equal("*", str))
  {
    mutt_list_free(head); /* "unCMD *" means delete all current entries */
  }
  else
  {
    struct ListNode *np = NULL;
    struct ListNode *tmp = NULL;
    STAILQ_FOREACH_SAFE(np, head, entries, tmp)
    {
      if (mutt_istr_equal(str, np->data))
      {
        STAILQ_REMOVE(head, np, ListNode, entries);
        FREE(&np->data);
        FREE(&np);
        break;
      }
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function: