= loc_country_list_new(3)

== Name

loc_country_list_new, loc_country_list_ref, loc_country_list_unref,
loc_country_list_size, loc_country_list_empty, loc_country_list_clear,
loc_country_list_get, loc_country_list_sort - A list of countries

== Synopsis
----
#include <libloc/country-list.h>

struct loc_country_list;

int loc_country_list_new(struct loc_ctx* ctx,
	struct loc_country_list** list);

struct loc_country_list* loc_country_list_ref(struct loc_country_list* list);

struct loc_country_list* loc_country_list_unref(struct loc_country_list* list);

size_t loc_country_list_size(struct loc_country_list* list);

int loc_country_list_empty(struct loc_country_list* list);

void loc_country_list_clear(struct loc_country_list* list);

struct loc_country* loc_country_list_get(struct loc_country_list* list,
	size_t index);

void loc_country_list_sort(struct loc_country_list* list);
----

== Description

A country list holds countries in the order in which they have been added, and every
country only once. It is mainly used to tell an enumerator which networks to return
(see link:loc_database_enumerator_new[3]).

loc_country_list_new() creates a new, empty list.

loc_country_list_size() returns how many countries are on the list, and
loc_country_list_empty() returns whether there are none. loc_country_list_clear()
removes all of them.

loc_country_list_get() returns the country at _index_, starting from zero.

Countries are being added with link:loc_country_list_append[3].

loc_country_list_sort() sorts the list by code.

== Return Value

loc_country_list_new() returns zero on success, and a negative error number (see
errno(3)) on error.

loc_country_list_get() returns a reference to the country, which the caller has to
release, or NULL if _index_ is not on the list.

loc_country_list_empty() returns 1 if the list is empty, and zero otherwise.

loc_country_list_ref() returns the list. loc_country_list_unref() returns NULL once the
last reference has been released and the list has been freed, or the list otherwise.

== See Also

link:libloc[3],
link:loc_country_list_append[3],
link:loc_country_new[3],
link:loc_database_enumerator_new[3]

== Authors

Michael Tremer
