gi-glib-2.0.24: GLib bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.Tree

Contents

- Exported types
- Methods
  - Overloaded methods
  - destroy
  - height
  - insert
  - lookup
  - lookupExtended
  - nnodes
  - remove
  - replace
  - steal
  - unref

Description

The GTree struct is an opaque data structure representing a [balanced binary tree][glib-Balanced-Binary-Trees]. It should be accessed only by using the following functions.

Synopsis

- newtype Tree = Tree (ManagedPtr Tree)
- treeDestroy :: (HasCallStack, MonadIO m) => Tree -> m ()
- treeHeight :: (HasCallStack, MonadIO m) => Tree -> m Int32
- treeInsert :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> Ptr () -> m ()
- treeLookup :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> m (Ptr ())
- treeLookupExtended :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> m (Bool, Ptr (), Ptr ())
- treeNnodes :: (HasCallStack, MonadIO m) => Tree -> m Int32
- treeRemove :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> m Bool
- treeReplace :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> Ptr () -> m ()
- treeSteal :: (HasCallStack, MonadIO m) => Tree -> Ptr () -> m Bool
- treeUnref :: (HasCallStack, MonadIO m) => Tree -> m ()

# Exported types

newtype Tree Source #

Memory-managed wrapper type.

Constructors

Tree (ManagedPtr Tree) |

#### Instances

Instances details

Eq Tree Source # |
Instance details Defined in GI.GLib.Structs.Tree Methods (==) :: Tree -> Tree -> Bool # (/=) :: Tree -> Tree -> Bool #
ManagedPtrNewtype Tree Source # |
Instance details Defined in GI.GLib.Structs.Tree Methods toManagedPtr :: Tree -> ManagedPtr Tree Source #
BoxedPtr Tree Source # |
Instance details Defined in GI.GLib.Structs.Tree Methods boxedPtrCopy :: Tree -> IO Tree Source # boxedPtrFree :: Tree -> IO () Source #

# Methods

## Overloaded methods

## destroy

treeDestroy Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> m () |

Removes all keys and values from the `Tree` and decreases its reference count by one. If keys and/or values are dynamically allocated, you should either free them first or create the `Tree` using `g_tree_new_full()`. In the latter case the destroy functions you supplied will be called on all keys and values before destroying the `Tree`.

## height

treeHeight Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> m Int32 | Returns: the height of `tree`

Gets the height of a `Tree`.

If the `Tree` contains no nodes, the height is 0. If the `Tree` contains only one root node the height is 1. If the root node has children the height is 2, etc.

## insert

treeInsert Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `key`: the key to insert
-> Ptr () | `value`: the value corresponding to the key
-> m () |

Inserts a key/value pair into a `Tree`.

If the given key already exists in the `Tree` its corresponding value is set to the new value. If you supplied a `valueDestroyFunc` when creating the `Tree`, the old value is freed using that function. If you supplied a `keyDestroyFunc` when creating the `Tree`, the passed key is freed using that function.

The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible. The cost of maintaining a balanced tree while inserting new key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)).

## lookup

treeLookup Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `key`: the key to look up
-> m (Ptr ()) | Returns: the value corresponding to the key, or `Nothing` if the key was not found

Gets the value corresponding to the given key. Since a `Tree` is automatically balanced as key/value pairs are added, key lookup is O(log n) (where n is the number of key/value pairs in the tree).

## lookupExtended

treeLookupExtended Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `lookupKey`: the key to look up
-> m (Bool, Ptr (), Ptr ()) | Returns: `True` if the key was found in the `Tree`

Looks up a key in the `Tree`, returning the original key and the associated value. This is useful if you need to free the memory allocated for the original key, for example before calling `treeRemove`.

## nnodes

treeNnodes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> m Int32 | Returns: the number of nodes in `tree`

Gets the number of nodes in a `Tree`.

## remove

treeRemove Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `key`: the key to remove
-> m Bool | Returns: `True` if the key was found (prior to 2.8, this function returned nothing)

Removes a key/value pair from a `Tree`.

If the `Tree` was created using `g_tree_new_full()`, the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. If the key does not exist in the `Tree`, the function does nothing.

The cost of maintaining a balanced tree while removing a key/value result in a O(n log(n)) operation where most of the other operations are O(log(n)).

## replace

treeReplace Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `key`: the key to insert
-> Ptr () | `value`: the value corresponding to the key
-> m () |

Inserts a new key and value into a `Tree` similar to `treeInsert`. The difference is that if the key already exists in the `Tree`, it gets replaced by the new key. If you supplied a `valueDestroyFunc` when creating the `Tree`, the old value is freed using that function. If you supplied a `keyDestroyFunc` when creating the `Tree`, the old key is freed using that function.

The tree is automatically 'balanced' as new key/value pairs are added, so that the distance from the root to every leaf is as small as possible.

## steal

treeSteal Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> Ptr () | `key`: the key to remove
-> m Bool | Returns: `True` if the key was found (prior to 2.8, this function returned nothing)

Removes a key and its associated value from a `Tree` without calling the key and value destroy functions.

If the key does not exist in the `Tree`, the function does nothing.

## unref

treeUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Tree | `tree`: a `Tree`
-> m () |

Decrements the reference count of `tree` by one. If the reference count drops to 0, all keys and values will be destroyed (if destroy functions were specified) and all memory allocated by `tree` will be released.

It is safe to call this function from any thread.

Since: 2.22