lib/list.c

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #include <config.h>
  17 #include "list.h"
  18 #include <assert.h>
  19
  20 /* Initializes 'list' as an empty list. */
  21 void
  22 list_init(struct list *list)
  23 {
  24     list->next = list->prev = list;
  25 }
  26
  27 /* Initializes 'list' with pointers that will (probably) cause segfaults if
  28  * dereferenced and, better yet, show up clearly in a debugger. */
  29 void
  30 list_poison(struct list *list)
  31 {
  32     memset(list, 0xcc, sizeof *list);
  33 }
  34
  35 /* Inserts 'elem' just before 'before'. */
  36 void
  37 list_insert(struct list *before, struct list *elem)
  38 {
  39     elem->prev = before->prev;
  40     elem->next = before;
  41     before->prev->next = elem;
  42     before->prev = elem;
  43 }
  44
  45 /* Removes elements 'first' though 'last' (exclusive) from their current list,
  46    then inserts them just before 'before'. */
  47 void
  48 list_splice(struct list *before, struct list *first, struct list *last)
  49 {
  50     if (first == last)
  51         return;
  52     last = last->prev;
  53
  54     /* Cleanly remove 'first'...'last' from its current list. */
  55     first->prev->next = last->next;
  56     last->next->prev = first->prev;
  57
  58     /* Splice 'first'...'last' into new list. */
  59     first->prev = before->prev;
  60     last->next = before;
  61     before->prev->next = first;
  62     before->prev = last;
  63 }
  64
  65 /* Inserts 'elem' at the beginning of 'list', so that it becomes the front in
  66    'list'. */
  67 void
  68 list_push_front(struct list *list, struct list *elem)
  69 {
  70     list_insert(list->next, elem);
  71 }
  72
  73 /* Inserts 'elem' at the end of 'list', so that it becomes the back in
  74  * 'list'. */
  75 void
  76 list_push_back(struct list *list, struct list *elem)
  77 {
  78     list_insert(list, elem);
  79 }
  80
  81 /* Puts 'elem' in the position currently occupied by 'position'.
  82  * Afterward, 'position' is not part of a list. */
  83 void
  84 list_replace(struct list *element, const struct list *position)
  85 {
  86     element->next = position->next;
  87     element->next->prev = element;
  88     element->prev = position->prev;
  89     element->prev->next = element;
  90 }
  91
  92 /* Adjusts pointers around 'list' to compensate for 'list' having been moved
  93  * around in memory (e.g. as a consequence of realloc()).
  94  *
  95  * This always works if 'list' is a member of a list, or if 'list' is the head
  96  * of a non-empty list.  It fails badly, however, if 'list' is the head of an
  97  * empty list; just use list_init() in that case. */
  98 void
  99 list_moved(struct list *list)
 100 {
 101     list->prev->next = list->next->prev = list;
 102 }
 103
 104 /* Removes 'elem' from its list and returns the element that followed it.
 105    Undefined behavior if 'elem' is not in a list. */
 106 struct list *
 107 list_remove(struct list *elem)
 108 {
 109     elem->prev->next = elem->next;
 110     elem->next->prev = elem->prev;
 111     return elem->next;
 112 }
 113
 114 /* Removes the front element from 'list' and returns it.  Undefined behavior if
 115    'list' is empty before removal. */
 116 struct list *
 117 list_pop_front(struct list *list)
 118 {
 119     struct list *front = list->next;
 120     list_remove(front);
 121     return front;
 122 }
 123
 124 /* Removes the back element from 'list' and returns it.
 125    Undefined behavior if 'list' is empty before removal. */
 126 struct list *
 127 list_pop_back(struct list *list)
 128 {
 129     struct list *back = list->prev;
 130     list_remove(back);
 131     return back;
 132 }
 133
 134 /* Returns the front element in 'list_'.
 135    Undefined behavior if 'list_' is empty. */
 136 struct list *
 137 list_front(const struct list *list_)
 138 {
 139     struct list *list = (struct list *) list_;
 140
 141     assert(!list_is_empty(list));
 142     return list->next;
 143 }
 144
 145 /* Returns the back element in 'list_'.
 146    Undefined behavior if 'list_' is empty. */
 147 struct list *
 148 list_back(const struct list *list_)
 149 {
 150     struct list *list = (struct list *) list_;
 151
 152     assert(!list_is_empty(list));
 153     return list->prev;
 154 }
 155
 156 /* Returns the number of elements in 'list'.
 157    Runs in O(n) in the number of elements. */
 158 size_t
 159 list_size(const struct list *list)
 160 {
 161     const struct list *e;
 162     size_t cnt = 0;
 163
 164     for (e = list->next; e != list; e = e->next)
 165         cnt++;
 166     return cnt;
 167 }
 168
 169 /* Returns true if 'list' is empty, false otherwise. */
 170 bool
 171 list_is_empty(const struct list *list)
 172 {
 173     return list->next == list;
 174 }
 175
 176 /* Returns true if 'list' has exactly 1 element, false otherwise. */
 177 bool
 178 list_is_singleton(const struct list *list)
 179 {
 180     return list_is_short(list) && !list_is_empty(list);
 181 }
 182
 183 /* Returns true if 'list' has 0 or 1 elements, false otherwise. */
 184 bool
 185 list_is_short(const struct list *list)
 186 {
 187     return list->next == list->prev;
 188 }