Dictionary.chs

{-# LANGUAGE ForeignFunctionInterface #-}

-- Copyright (C) 2009 John Millikin <jmillikin@gmail.com>
--
-- This program is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program.  If not, see <http://www.gnu.org/licenses/>.

module CPython.Types.Dictionary
	( Dictionary
	, dictionaryType
	, new
	, clear
	, contains
	, copy
	, getItem
	, setItem
	, deleteItem
	, items
	, keys
	, values
	, size
	, merge
	, update
	, mergeFromSeq2
	) where

#include <hscpython-shim.h>

import           CPython.Internal hiding (new)

instance Concrete Dictionary where
	concreteType _ = dictionaryType

{# fun pure unsafe hscpython_PyDict_Type as dictionaryType
	{} -> `Type' peekStaticObject* #}

{# fun PyDict_New as new
	{} -> `Dictionary' stealObject* #}

-- newProxy

-- | Empty an existing dictionary of all key-value pairs.
{# fun PyDict_Clear as clear
	{ withObject* `Dictionary'
	} -> `()' id #}

-- | Determine if a dictionary contains /key/. If an item in the dictionary
-- matches /key/, return 'True', otherwise return 'False'. On error, throws
-- an exception. This is equivalent to the Python expression @key in d@.
{# fun PyDict_Contains as contains
	`Object key' =>
	{ withObject* `Dictionary'
	, withObject* `key'
	} -> `Bool' checkBoolReturn* #}

-- | Return a new dictionary that contains the same key-value pairs as the
-- old dictionary.
{# fun PyDict_Copy as copy
	{ withObject* `Dictionary'
	} -> `Dictionary' stealObject* #}

-- | Return the object from a dictionary which has a key /key/. Return
-- 'Nothing' if the key is not present.
getItem :: Object key => Dictionary -> key -> IO (Maybe SomeObject)
getItem dict key =
	withObject dict $ \dict' ->
	withObject key $ \key' -> do
	{# call PyErr_Clear as ^ #}
	raw <- {# call PyDict_GetItemWithError as ^ #} dict' key'
	if raw /= nullPtr
		then Just `fmap` peekObject raw
		else do
			exc <- {# call PyErr_Occurred as ^ #}
			exceptionIf $ exc /= nullPtr
			return Nothing

-- getItemString

-- | Inserts /value/ into a dictionary with a key of /key/. /key/ must be
-- hashable; if it isn&#x2019;t, throws @TypeError@.
{# fun PyDict_SetItem as setItem
	`(Object key, Object value)' =>
	{ withObject* `Dictionary'
	, withObject* `key'
	, withObject* `value'
	} -> `()' checkStatusCode* #}

-- setItemString

-- | Remove the entry in a dictionary with key /key/. /key/ must be hashable;
-- if it isn&#x2019;t, throws @TypeError@.
{# fun PyDict_DelItem as deleteItem
	`Object key' =>
	{ withObject* `Dictionary'
	, withObject* `key'
	} -> `()' checkStatusCode* #}

-- deleteItemString

-- | Return a 'List' containing all the items in the dictionary, as in
-- the Python method @dict.items()@.
{# fun PyDict_Items as items
	{ withObject* `Dictionary'
	} -> `List' stealObject* #}

-- | Return a 'List' containing all the keys in the dictionary, as in
-- the Python method @dict.keys()@.
{# fun PyDict_Keys as keys
	{ withObject* `Dictionary'
	} -> `List' stealObject* #}

-- | Return a 'List' containing all the values in the dictionary, as in
-- the Python method @dict.values()@.
{# fun PyDict_Values as values
	{ withObject* `Dictionary'
	} -> `List' stealObject* #}

-- | Return the number of items in the dictionary. This is equivalent to
-- @len(d)@.
{# fun PyDict_Size as size
	{ withObject* `Dictionary'
	} -> `Integer' checkIntReturn* #}

-- next

-- | Iterate over mapping object /b/ adding key-value pairs to a dictionary.
-- /b/ may be a dictionary, or any object supporting 'keys' and 'getItem'.
-- If the third parameter is 'True', existing pairs in will be replaced if a
-- matching key is found in /b/, otherwise pairs will only be added if there
-- is not already a matching key.
{# fun PyDict_Merge as merge
	`Mapping b' =>
	{ withObject* `Dictionary'
	, withObject* `b'
	, `Bool'
	} -> `()' checkStatusCode* #}

-- | This is the same as @(\\a b -> 'merge' a b True)@ in Haskell, or
-- @a.update(b)@ in Python.
{# fun PyDict_Update as update
	`Mapping b' =>
	{ withObject* `Dictionary'
	, withObject* `b'
	} -> `()' checkStatusCode* #}

-- | Update or merge into a dictionary, from the key-value pairs in /seq2/.
-- /seq2/ must be an iterable object producing iterable objects of length 2,
-- viewed as key-value pairs. In case of duplicate keys, the last wins if
-- the third parameter is 'True', otherwise the first wins. Equivalent
-- Python:
--
-- @
-- def mergeFromSeq2(a, seq2, override):
-- 	for key, value in seq2:
-- 		if override or key not in a:
-- 			a[key] = value
-- @
{# fun PyDict_MergeFromSeq2 as mergeFromSeq2
	`Object seq2' =>
	{ withObject* `Dictionary'
	, withObject* `seq2'
	, `Bool'
	} -> `()' checkStatusCode* #}