gi-glib-2.0.17: GLib bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.GLib.Structs.Tree

Contents

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

Exported types

newtype Tree Source #

Memory-managed wrapper type.

Constructors

Tree (ManagedPtr Tree) 
Instances
WrappedPtr Tree Source # 
Instance details

Defined in GI.GLib.Structs.Tree

noTree :: Maybe Tree Source #

A convenience alias for Nothing :: Maybe Tree.

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.

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

-> Ptr ()

origKey: returns the original key

-> Ptr ()

value: returns the value associated with the key

-> m Bool

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.

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