---
name: "soldout_array"
section: "3"
platform: "linux"
package: "libsoldout-dev"
version: "1.4-7+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/soldout_array"
---

# soldout\_array(3)

array handling functions for soldout

## NAME

**soldout\_array**, **arr\_adjust**, **arr\_free**, **arr\_grow**, **arr\_init**, **arr\_insert**, **arr\_item**, **arr\_newitem**, **arr\_remove**, **arr\_sorted\_find**, **arr\_sorted\_find\_i**, **parr\_adjust**, **parr\_free**, **parr\_grow**, **parr\_init**, **parr\_insert**, **parr\_pop**, **parr\_push**, **parr\_remove**, **parr\_sorted\_find**, **parr\_sorted\_find\_i**, **parr\_top** – array handling functions for soldout

## SYNOPSIS

**#include \<array.h\>**

*int*\

**(\*array\_cmp\_fn)**(*void \*key*, *void \*array\_entry*);

*int*\

**arr\_adjust**(*struct array \*arr*);

*void*\

**arr\_free**(*struct array \*arr*);

*int*\

**arr\_grow**(*struct array \*arr*, *int need*);

*void*\

**arr\_init**(*struct array \*arr*, *size\_t unit*);

*int*\

**arr\_insert**(*struct array \*arr*, *int nb*, *int n*);

*void \**\

**arr\_item**(*struct array \*arr*, *int no*);

*int*\

**arr\_newitem**(*struct array \*arr*);

*void*\

**arr\_remove**(*struct array \*arr*, *int idx*);

*void \**\

**arr\_sorted\_find**(*struct array \*arr*, *void \*key*, *array\_cmp\_fn cmp*);

*int*\

**arr\_sorted\_find\_i**(*struct array \*arr*, *void \*key*, *array\_cmp\_fn cmp*);

*int*\

**parr\_adjust**(*struct parray \*arr*);

*void*\

**parr\_free**(*struct parray \*arr*);

*int*\

**parr\_grow**(*struct parray \*arr*, *int need*);

*void*\

**parr\_init**(*struct parray \*arr*);

*int*\

**parr\_insert**(*struct parray \*parr*, *int nb*, *int n*);

*void \**\

**parr\_pop**(*struct parray \*arr*);

*int*\

**parr\_push**(*struct parray \*arr*, *void \*i*);

*void \**\

**parr\_remove**(*struct parray \*arr*, *int idx*);

*void \**\

**parr\_sorted\_find**(*struct parray \*arr*, *void \*key*, *array\_cmp\_fn cmp*);

*int*\

**parr\_sorted\_find\_i**(*struct parray \*arr*, *void \*key*, *array\_cmp\_fn cmp*);

*void \**\

**parr\_top**(*struct parray \*arr*);

## DESCRIPTION

### Types

- *struct array*

  generic linear array. Consists of the following fields:

  - *void \** *base*

    actual array data.

  - *int* *size*

    size of the array.

  - *int* *asize*

    allocated size.

  - *size\_t* *unit*

    reallocation unit size.

- *struct parray*

  array of pointers. Consists of the following fields:

  - *void \*\** *item*

    actual parray data.

  - *int* *size*

    size of the parray.

  - *int* *asize*

    allocated size.

- *array\_cmp\_fn*

  comparison function for sorted arrays.

### Functions

- **arr\_adjust**()

  shrink the allocated memory to fit exactly the needs.

- **arr\_free**()

  free the structure contents (but NOT the struct itself).

- **arr\_grow**()

  increase the array size to fit the given number of elements.

- **arr\_init**()

  initialize the contents of the struct.

- **arr\_insert**()

  insert *nb* elements before the *n* one.

- **arr\_item**()

  return a pointer to the *n* element.

- **arr\_newitem**()

  return the index of a new element appended to the array *arr*.

- **arr\_remove**()

  remove the n-th elements of the array.

- **arr\_sorted\_find**()

  O(log n) search in a sorted array, returning entry.

- **arr\_sorted\_find\_i**()

  O(log n) search in a sorted array, returning index of the smallest element larger than the key.

- **parr\_adjust**()

  shrink the allocated memory to fit exactly the needs.

- **parr\_free**()

  free the structure contents (but NOT the struct itself).

- **parr\_grow**()

  increase the array size to fit the given number of elements.

- **parr\_init**()

  initialize the contents of the struct.

- **parr\_insert**()

  insert *nb* elements before the *n* one.

- **parr\_pop**()

  pop the last item of the array and return it.

- **parr\_push**()

  push a pointer at the end of the array (= append).

- **parr\_remove**()

  remove the *idx* element of the array and return it.

- **parr\_sorted\_find**()

  O(log n) search in a sorted array, returning entry.

- **parr\_sorted\_find\_i**()

  O(log n) search in a sorted array, returning index of the smallest element larger than the key.

- **parr\_top**()

  return the top the stack (i.e. the last element of the array).

## RETURN VALUES

The **arr\_adjust**(), **arr\_grow**(), **arr\_insert**(), **parr\_adjust**(), **parr\_grow**(), **parr\_insert**() and **parr\_push**() functions return on success 1; on error - 0.

The **arr\_free**(), **arr\_init**(), **arr\_remove**(), **parr\_free**() and **parr\_init**() functions do not return a value.

The **arr\_item**(), **arr\_sorted\_find**(), **parr\_pop**(), **parr\_remove**(), **parr\_sorted\_find**() and **parr\_top**() functions return a pointer to the element on success; on error - NULL.

The **arr\_newitem**() function returns the index on success; on error -1.

The **arr\_sorted\_find\_i**() and **parr\_sorted\_find\_i**() functions return an index.

## SEE ALSO

[soldout(3)](/soldout/3.md)

## AUTHORS

The **soldout** library was written by Natasha "Kerensikova" Porte ⟨*natacha@instinctive.eu*⟩. Manual page was originally written by Massimo Manghi ⟨*mxmanghi@apache.org*⟩, and rewritten to mdoc format by Svyatoslav Mishyn ⟨*juef@openmailbox.org*⟩.