Dictionary Struct Reference

#include <Dictionary.h>

Overview

Key-value stores.

Definition at line 60 of file Dictionary.h.

Inheritance diagram for Dictionary:

Properties
size_t	count
	The count of elements.
Object	object
	The superclass.
Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class.
unsigned int	magic
	A header to allow introspection of Object types.

Methods
Class *	_Dictionary (void)
	The Dictionary archetype.
void	addEntriesFromDictionary (Dictionary *self, const Dictionary *dictionary)
	Adds the key-value entries from dictionary to this Dictionary.
Array *	allKeys (const Dictionary *self)
Array *	allObjects (const Dictionary *self)
bool	containsKey (const Dictionary *self, const ident key)
bool	containsKeyPath (const Dictionary *self, const char *path)
Dictionary *	dictionary (void)
	Returns a new Dictionary.
Dictionary *	dictionaryWithCapacity (size_t capacity)
	Returns a new Dictionary with the given capacity.
Dictionary *	dictionaryWithDictionary (const Dictionary *dictionary)
	Returns a new Dictionary containing all pairs from dictionary.
Dictionary *	dictionaryWithObjectsAndKeys (ident obj,...)
	Returns a new Dictionary containing pairs from the given arguments.
void	enumerateObjectsAndKeys (const Dictionary *self, DictionaryEnumerator enumerator, ident data)
	Enumerate the pairs of this Dictionary with the given function.
Dicionary *	filterObjectsAndKeys (const Dictionary *self, DictionaryPredicate predicate, ident data)
	Creates a new Dictionary with pairs that pass the filter function.
Dictionary *	init (Dictionary *self)
	Initializes this Dictionary.
Dictionary *	initWithCapacity (Dictionary *self, size_t capacity)
	Initializes this Dictionary with the specified capacity.
Dictionary *	initWithDictionary (Dictionary *self, const Dictionary *dictionary)
	Initializes this Dictionary to contain elements of dictionary.
Dictionary *	initWithObjectsAndKeys (Dictionary *self,...)
	Initializes this Dictionary with the NULL-terminated list of Objects and keys.
ident	objectForKey (const Dictionary *self, const ident key)
ident	objectForKeyPath (const Dictionary *self, const char *path)
ident	objectForKeyPathWithClass (const Dictionary *self, const char *path, const Class *clazz)
void	removeAllObjects (Dictionary *self)
	Removes all Objects from this Dictionary.
void	removeAllObjectsWithEnumerator (Dictionary *self, DictionaryEnumerator enumerator, ident data)
	Removes all Objects from this Dictionary, invoking enumerator for each Object and key pair.
void	removeObjectForKey (Dictionary *self, const ident key)
	Removes the Object with the specified key from this Dictionary.
void	removeObjectForKeyPath (Dictionary *self, const char *path)
	Removes the Object with the specified key path from this Dictionary.
void	setObjectForKey (Dictionary *self, const ident obj, const ident key)
	Sets a pair in this Dictionary.
void	setObjectForKeyPath (Dictionary *self, const ident obj, const char *path)
	Sets a pair in this Dictionary.
void	setObjectsForKeyPaths (Dictionary *self,...)
	Sets pairs in this Dictionary from the NULL-terminated list.
void	setObjectsForKeys (Dictionary *self,...)
	Sets pairs in this Dictionary from the NULL-terminated list.
Methods inherited from Object
Class *	_Object (void)
	The Object archetype.
Object *	copy (const Object *self)
	Creates a shallow copy of this Object.
void	dealloc (Object *self)
	Frees all resources held by this Object.
String *	description (const Object *self)
int	hash (const Object *self)
Object *	init (Object *self)
	Initializes this Object.
bool	isEqual (const Object *self, const Object *other)
	Tests equality of the other Object.
bool	isKindOfClass (const Object *self, const Class *clazz)
	Tests for Class hierarchy membership.

Protected Attributes
DictionaryInterface *	interface
	The interface.
Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface.

Property Details

count

size_t Dictionary::count

The count of elements.

Definition at line 82 of file Dictionary.h.

interface

DictionaryInterface* Dictionary::interface

protected

The interface.

Definition at line 71 of file Dictionary.h.

object

Object Dictionary::object

The superclass.

Definition at line 65 of file Dictionary.h.

Method Details

_Dictionary()

Class * _Dictionary

(

void

)

The Dictionary archetype.

Returns

The Dictionary Class.

Definition at line 762 of file Dictionary.c.

                         {
  static Class *clazz;
  static Once once;
 
  do_once(&once, {
    clazz = _initialize(&(const ClassDef) {
      .name = "Dictionary",
      .superclass = _Object(),
      .instanceSize = sizeof(Dictionary),
      .interfaceOffset = offsetof(Dictionary, interface),
      .interfaceSize = sizeof(DictionaryInterface),
      .initialize = initialize,
    });
  });
 
  return clazz;
}

addEntriesFromDictionary()

void addEntriesFromDictionary	(	Dictionary *	self,
		const Dictionary *	dictionary
	)

Adds the key-value entries from dictionary to this Dictionary.

Parameters

self	The Dictionary.
dictionary	A Dictionary.

Definition at line 175 of file Dictionary.c.

                                                                                     {
 
  assert(dictionary);
 
  $(dictionary, enumerateObjectsAndKeys, addEntriesFromDictionary_enumerator, self);
}

allKeys()

Array * allKeys

(

const Dictionary *

self

)

Parameters

self	The Dictionary.

Returns

An Array containing all keys in this Dictionary.

Definition at line 193 of file Dictionary.c.

                                              {
 
  Array *keys = $(alloc(Array), initWithCapacity, self->count);
 
  $(self, enumerateObjectsAndKeys, allKeys_enumerator, keys);
 
  return (Array *) keys;
}

allObjects()

Array * allObjects

(

const Dictionary *

self

)

Parameters

self	The Dictionary.

Returns

An Array containing all Objects in this Dictionary.

Definition at line 213 of file Dictionary.c.

                                                 {
 
  Array *objects = $(alloc(Array), initWithCapacity, self->count);
 
  $(self, enumerateObjectsAndKeys, allObjects_enumerator, objects);
 
  return (Array *) objects;
}

containsKey()

bool containsKey	(	const Dictionary *	self,
		const ident	key
	)

Parameters

self	The Dictionary.
key	The key to test.

Returns

True if this Dictionary contains the specified key, false otherwise.

Definition at line 226 of file Dictionary.c.

                                                                 {
  return $(self, objectForKey, key) != NULL;
}

containsKeyPath()

bool containsKeyPath	(	const Dictionary *	self,
		const char *	path
	)

Parameters

self	The Dictionary.
path	The key path to test.

Returns

True if this Dictionary contains the specified key path, false otherwise.

Definition at line 234 of file Dictionary.c.

                                                                      {
  return $(self, objectForKeyPath, path) != NULL;
}

dictionary()

Dictionary * dictionary

(

void

)

Returns a new Dictionary.

Returns

The new Dictionary, or NULL on error.

Definition at line 242 of file Dictionary.c.

                                    {
 
  return $(alloc(Dictionary), init);
}

dictionaryWithCapacity()

Dictionary * dictionaryWithCapacity

(

size_t

capacity

)

Returns a new Dictionary with the given capacity.

Parameters

capacity

The desired initial capacity.

Returns

The new Dictionary, or NULL on error.

Definition at line 251 of file Dictionary.c.

                                                           {
 
  return $(alloc(Dictionary), initWithCapacity, capacity);
}

dictionaryWithDictionary()

Dictionary * dictionaryWithDictionary

(

const Dictionary *

dictionary

)

Returns a new Dictionary containing all pairs from dictionary.

Parameters

dictionary

A Dictionary.

Returns

The new Dictionary, or NULL on error.

Definition at line 260 of file Dictionary.c.

                                                                          {
 
  return $(alloc(Dictionary), initWithDictionary, dictionary);
}

dictionaryWithObjectsAndKeys()

Dictionary * dictionaryWithObjectsAndKeys	(	ident	obj,
			...
	)

Returns a new Dictionary containing pairs from the given arguments.

Parameters

obj	The first in a NULL-terminated list of Objects and keys.

Returns

The new Dictionary, or NULL on error.

Definition at line 269 of file Dictionary.c.

                                                                {
 
  Dictionary *dict = (Dictionary *) $((Object *) alloc(Dictionary), init);
  if (dict) {
 
    va_list args;
    va_start(args, obj);
 
    while (obj) {
      ident key = va_arg(args, ident);
 
      $(dict, setObjectForKey, obj, key);
 
      obj = va_arg(args, ident);
    }
 
    va_end(args);
  }
 
  return dict;
}

enumerateObjectsAndKeys()

void enumerateObjectsAndKeys	(	const Dictionary *	self,
		DictionaryEnumerator	enumerator,
		ident	data
	)

Enumerate the pairs of this Dictionary with the given function.

Parameters

self	The Dictionary.
enumerator	The enumerator function.
data	User data.

Remarks

The enumerator should return true to break the iteration.

Definition at line 295 of file Dictionary.c.

                {
 
  assert(enumerator);
 
  for (size_t i = 0; i < self->capacity; i++) {
 
    Array *array = self->elements[i];
    if (array) {
 
      for (size_t j = 0; j < array->count; j += 2) {
 
        ident key = $(array, objectAtIndex, j);
        ident obj = $(array, objectAtIndex, j + 1);
 
        enumerator(self, obj, key, data);
      }
    }
  }
}

filterObjectsAndKeys()

Dictionary * filterObjectsAndKeys	(	const Dictionary *	self,
		DictionaryPredicate	predicate,
		ident	data
	)

Creates a new Dictionary with pairs that pass the filter function.

Parameters

self	The Dictionary.
predicate	The predicate function.
data	User data.

Returns

The new, filtered Dictionary.

Definition at line 320 of file Dictionary.c.

                                                                                                           {
 
  assert(predicate);
 
  Dictionary *dictionary = $(alloc(Dictionary), init);
 
  for (size_t i = 0; i < self->capacity; i++) {
 
    Array *array = self->elements[i];
    if (array) {
 
      for (size_t j = 0; j < array->count; j += 2) {
 
        ident key = $(array, objectAtIndex, j);
        ident obj = $(array, objectAtIndex, j + 1);
 
        if (predicate(obj, key, data)) {
          $(dictionary, setObjectForKey, obj, key);
        }
      }
    }
  }
 
  return dictionary;
}

init()

Dictionary * init

(

Dictionary *

self

)

Initializes this Dictionary.

Parameters

self	The Dictionary.

Returns

The initialized Dictionary, or NULL on error.

Definition at line 350 of file Dictionary.c.

                                          {
 
  return $(self, initWithCapacity, DICTIONARY_DEFAULT_CAPACITY);
}

initWithCapacity()

Dictionary * initWithCapacity	(	Dictionary *	self,
		size_t	capacity
	)

Initializes this Dictionary with the specified capacity.

Parameters

self	The Dictionary.
capacity	The initial capacity.

Returns

The initialized Dictionary, or NULL on error.

Definition at line 359 of file Dictionary.c.

                                                                       {
 
  self = (Dictionary *) super(Object, self, init);
  if (self) {
 
    self->capacity = capacity;
    if (self->capacity) {
 
      self->elements = calloc(self->capacity, sizeof(ident));
      assert(self->elements);
    }
  }
 
  return self;
}

initWithDictionary()

Dictionary * initWithDictionary	(	Dictionary *	self,
		const Dictionary *	dictionary
	)

Initializes this Dictionary to contain elements of dictionary.

Parameters

self	The Dictionary.
dictionary	A Dictionary.

Returns

The initialized Dictionary, or NULL on error.

Definition at line 379 of file Dictionary.c.

                                                                                      {
 
  self = (Dictionary *) super(Object, self, init);
  if (self) {
    if (dictionary) {
 
      self->capacity = dictionary->capacity;
 
      self->elements = calloc(self->capacity, sizeof(ident));
      assert(self->elements);
 
      for (size_t i = 0; i < dictionary->capacity; i++) {
 
        Array *array = dictionary->elements[i];
        if (array) {
          self->elements[i] = $((Object *) array, copy);
        }
      }
 
      self->count = dictionary->count;
    }
  }
 
  return self;
}

initWithObjectsAndKeys()

Dictionary * initWithObjectsAndKeys	(	Dictionary *	self,
			...
	)

Initializes this Dictionary with the NULL-terminated list of Objects and keys.

Parameters

self	The Dictionary.

Returns

The initialized Dictionary, or NULL on error.

Definition at line 409 of file Dictionary.c.

                                                                 {
 
  self = (Dictionary *) super(Object, self, init);
  if (self) {
 
    va_list args;
    va_start(args, self);
 
    while (true) {
 
      ident obj = va_arg(args, ident);
      if (obj) {
 
        ident key = va_arg(args, ident);
        $(self, setObjectForKey, obj, key);
      } else {
        break;
      }
    }
 
    va_end(args);
  }
 
  return self;
}

objectForKey()

ident objectForKey	(	const Dictionary *	self,
		const ident	key
	)

Parameters

self	The Dictionary.
key	The key.

Returns

The Object stored at the specified key in this Dictionary.

Definition at line 439 of file Dictionary.c.

                                                                   {
 
  if (self->capacity == 0) {
    return NULL;
  }
  
  const size_t bin = HashForObject(HASH_SEED, key) % self->capacity;
 
  Array *array = self->elements[bin];
  if (array) {
 
    const ssize_t index = $(array, indexOfObject, key);
    if (index > -1 && (index & 1) == 0) {
      return $(array, objectAtIndex, index + 1);
    }
  }
 
  return NULL;
}

objectForKeyPath()

ident objectForKeyPath	(	const Dictionary *	self,
		const char *	path
	)

Parameters

self	The Dictionary.
path	The key path.

Returns

The Object stored at the specified key path in this Dictionary.

Definition at line 463 of file Dictionary.c.

                                                                        {
 
  assert(path);
 
  String *key = str(path);
 
  ident obj = $(self, objectForKey, key);
 
  release(key);
 
  return obj;
}

objectForKeyPathWithClass()

ident objectForKeyPathWithClass	(	const Dictionary *	self,
		const char *	path,
		const Class *	clazz
	)

Parameters

self	The Dictionary.
path	The key path.
clazz	The Class.

Returns

The Object stored at the specified key path in this Dictionary, or NULL.

Remarks

This method performs unboxing of Null Objects, returning NULL in such cases.

The returned Object reference will either be of the specified type, or NULL.

Definition at line 480 of file Dictionary.c.

                                                                                                     {
 
  assert(path);
 
  const ident value = $(self, objectForKeyPath, path);
  if (value) {
    if (instanceof(Null, value)) {
      return NULL;
    } else {
      return _cast(clazz, value);
    }
  }
 
  return NULL;
}

removeAllObjects()

void removeAllObjects

(

Dictionary *

self

)

Removes all Objects from this Dictionary.

Parameters

self	The Dictionary.

Definition at line 500 of file Dictionary.c.

                                               {
 
  for (size_t i = 0; i < self->capacity; i++) {
 
    Array *array = self->elements[i];
    if (array) {
      self->elements[i] = release(array);
    }
  }
 
  self->count = 0;
}

removeAllObjectsWithEnumerator()

void removeAllObjectsWithEnumerator	(	Dictionary *	self,
		DictionaryEnumerator	enumerator,
		ident	data
	)

Removes all Objects from this Dictionary, invoking enumerator for each Object and key pair.

Parameters

self	The Dictionary.
enumerator	The enumerator.
data	The data.

Definition at line 517 of file Dictionary.c.

                                                                                                          {
 
  assert(enumerator);
 
  for (size_t i = 0; i < self->capacity; i++) {
 
    Array *array = self->elements[i];
    if (array) {
      for (size_t j = array->count; j > 0; j -= 2) {
 
        ident obj = array->elements[j - 1];
        ident key = array->elements[j - 2];
 
        enumerator(self, obj, key, data);
 
        $((Array *) array, removeObjectAtIndex, j - 1);
        $((Array *) array, removeObjectAtIndex, j - 2);
      }
 
      self->elements[i] = release(array);
    }
  }
 
  self->count = 0;
}

removeObjectForKey()

void removeObjectForKey	(	Dictionary *	self,
		const ident	key
	)

Removes the Object with the specified key from this Dictionary.

Parameters

self	The Dictionary.
key	The key of the Object to remove.

Definition at line 547 of file Dictionary.c.

                                                                  {
 
  if (self->capacity == 0) {
    return;
  }
  
  const size_t bin = HashForObject(HASH_SEED, key) % self->capacity;
 
  Array *array = self->elements[bin];
  if (array) {
 
    const ssize_t index = $((Array *) array, indexOfObject, key);
    if (index > -1) {
 
      $(array, removeObjectAtIndex, index);
      $(array, removeObjectAtIndex, index);
 
      if (((Array *) array)->count == 0) {
        self->elements[bin] = release(array);
      }
 
      self->count--;
    }
  }
}

removeObjectForKeyPath()

void removeObjectForKeyPath	(	Dictionary *	self,
		const char *	path
	)

Removes the Object with the specified key path from this Dictionary.

Parameters

self	The Dictionary.
path	The key path of the Object to remove.

Definition at line 577 of file Dictionary.c.

                                                                       {
 
  String *key = $$(String, stringWithCharacters, path);
 
  $(self, removeObjectForKey, key);
 
  release(key);
}

setObjectForKey()

void setObjectForKey	(	Dictionary *	self,
		const ident	obj,
		const ident	key
	)

Sets a pair in this Dictionary.

Parameters

self	The Dictionary.
obj	The Object to set.
key	The key of the Object to set.

Definition at line 634 of file Dictionary.c.

                                                                                {
 
  Dictionary *dict = self;
 
  setObjectForKey_resize(dict);
 
  const size_t bin = HashForObject(HASH_SEED, key) % dict->capacity;
 
  Array *array = dict->elements[bin];
  if (array == NULL) {
    array = dict->elements[bin] = $$(Array, arrayWithCapacity, (dict->capacity >> 2) + 1);
  }
 
  const ssize_t index = $((Array *) array, indexOfObject, key);
  if (index > -1 && (index & 1) == 0) {
    $(array, setObjectAtIndex, obj, index + 1);
  } else {
    $(array, addObject, key);
    $(array, addObject, obj);
 
    dict->count++;
  }
}

setObjectForKeyPath()

void setObjectForKeyPath	(	Dictionary *	self,
		const ident	obj,
		const char *	path
	)

Sets a pair in this Dictionary.

Parameters

self	The Dictionary.
obj	The Object to set.
path	The key path of the Object to set.

Definition at line 662 of file Dictionary.c.

                                                                                     {
 
  String *key = $$(String, stringWithCharacters, path);
 
  $(self, setObjectForKey, obj, key);
 
  release(key);
}

setObjectsForKeyPaths()

void setObjectsForKeyPaths	(	Dictionary *	self,
			...
	)

Sets pairs in this Dictionary from the NULL-terminated list.

Parameters

self	The Dictionary.

Definition at line 675 of file Dictionary.c.

                                                         {
 
  va_list args;
  va_start(args, self);
 
  while (true) {
 
    ident obj = va_arg(args, ident);
    if (obj) {
      const char *path = va_arg(args, const char *);
      $(self, setObjectForKeyPath, obj, path);
    } else {
      break;
    }
  }
 
  va_end(args);
}

setObjectsForKeys()

void setObjectsForKeys	(	Dictionary *	self,
			...
	)

Sets pairs in this Dictionary from the NULL-terminated list.

Parameters

self	The Dictionary.

Definition at line 698 of file Dictionary.c.

                                                     {
 
  va_list args;
  va_start(args, self);
 
  while (true) {
 
    ident obj = va_arg(args, ident);
    if (obj) {
      ident key = va_arg(args, ident);
      $(self, setObjectForKey, obj, key);
    } else {
      break;
    }
  }
 
  va_end(args);
}

---

The documentation for this struct was generated from the following files:

• Sources/Objectively/Dictionary.h
• Sources/Objectively/Dictionary.c