Trees       Indices       Help   
Module gwy :: Class Container
[hide private]
[frames] | no frames]

Class Container

source code

A container with items identified by a GQuark

Container is a general-purpose container, it can hold atomic types, strings and objects. However, objects must implement the Serializable interface, because the container itself is serializable.

A new container can be created with Container.new(), items can be stored with function like Container.set_double(), read with Container.get_double(), and removed with Container.remove() or Container.remove_by_prefix(). A presence of a value can be tested with Container.contains(), convenience functions for reading (updating) a value only if it is present like Container.gis_double(), are available too.

Container takes ownership of stored non-atomic items. For strings, this means you cannot store static strings (use g_strdup() to duplicate them), and must not free stored dynamic strings, as the container will free them itself when they are removed or when the container is finalized. For objects, this means it takes a reference on the object (released when the object is removed or the container is finalized), so you usually want to g_object_unref() objects after storing them to a container.

Items in a Container can be identified by a GQuark or the corresponding string. While GQuark's are atomic values and allow faster acces, they are less convenient for casual usage -- each GQuark key function like Container.set_double() thus has a string-key counterpart Container.set_double_by_name().

Instance Methods [hide private]
 
__init__()
Creates a new Container.		 source code
 
get_n_items()
Gets the number of items in a container.		 source code
 
value_type(key)
Returns the type of value in container identified by key.		 source code
 
contains(key)
Returns True if container contains a value identified by key.		 source code
 
remove(key)
Removes a value identified by key from a container.		 source code
 
remove_by_prefix(prefix)
Removes a values whose key start with prefix from container container.		 source code
 
transfer(dest, source_prefix, dest_prefix, force)
Copies a items from one place in container to another place.		 source code
 
rename(key, newkey, force)
Makes a value in container identified by key to be identified by newkey.		 source code
 
foreach(prefix, function, user_data)
Calls function on each container item whose identifier starts with prefix.		 source code
 
set_boolean(key, value)
Stores a boolean into container, identified by key.		 source code
 
get_boolean(key)
Returns the boolean in container identified by key.		 source code
 
set_uchar(key, value)
Stores an unsigned character into container, identified by key.		 source code
 
get_uchar(key)
Returns the unsigned character in container identified by key.		 source code
 
set_int32(key, value)
Stores a 32bit integer into container, identified by key.		 source code
 
get_int32(key)
Returns the 32bit integer in container identified by key.		 source code
 
set_enum(key, value)
Stores an enum into container, identified by key.		 source code
 
get_enum(key)
Returns the enum in container identified by key.		 source code
 
set_int64(key, value)
Stores a 64bit integer into container, identified by key.		 source code
 
get_int64(key)
Returns the 64bit integer in container identified by key.		 source code
 
set_double(key, value)
Stores a double into container, identified by key.		 source code
 
get_double(key)
Returns the double in container identified by key.		 source code
 
get_string(key)
Returns the string in container identified by key.		 source code
 
set_object(key, value)
Stores an object into container, identified by key.		 source code
 
get_object(key)
Returns the object in container identified by key.		 source code
 
keys()
Gets all quark keys of a container.		 source code
 
duplicate_by_prefix(keys)
Duplicates a container keeping only values under given prefixes.		 source code
 
serialize_to_text()
Creates a text representation of container contents.		 source code
 
contains_by_name(n)
Expands to True if container c contains a value identified by name n.		 source code
 
remove_by_name(n)
Removes a value identified by name n from container c.		 source code
 
rename_by_name(n, new_name, force)
Makes a value in container c identified by name n to be identified by new name nn.		 source code
 
set_boolean_by_name(n, v)
Stores a boolean into container c, identified by name n.		 source code
 
set_double_by_name(n, v)
Stores a double into container c, identified by name n.		 source code
 
set_enum_by_name(n, v)
Stores an enum into container c, identified by name n.		 source code
 
set_int32_by_name(n, v)
Stores a 32bit integer into container c, identified by name n.		 source code
 
set_int64_by_name(n, v)
Stores a 64bit integer into container c, identified by name n.		 source code
 
set_object_by_name(n, v)
Stores an object into container c, identified by name n.		 source code
 
set_uchar_by_name(n, v)
Stores an unsigned character into container c, identified by name n.		 source code
 
get_boolean_by_name(n)
Gets the boolean in container c identified by name n.		 source code
 
get_double_by_name(n)
Gets the double in container c identified by name n.		 source code
 
get_enum_by_name(n)
Gets the enum in container c identified by name n.		 source code
 
get_int32_by_name(n)
Gets the 32bit integer in container c identified by name n.		 source code
 
get_int64_by_name(n)
Gets the 64bit integer in container c identified by name n.		 source code
 
get_uchar_by_name(n)
Gets the unsigned character in container c identified by name n.		 source code
 
get_object_by_name(n)
Gets the object in container c identified by name n.		 source code
 
get_string_by_name(n)
Gets the string in container c identified by name n.		 source code
 
duplicate()
Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.		 source code
 
set_string_by_name(name, value)
Stores a string into container c, identified by name n.		 source code
 
set_string(key, value)
Stores a string into container, identified by key.		 source code
 
keys_by_name()
Gets all string keys of a container.		 source code
 
get_value_by_name(name)
Gets the value in container c identified by name n.		 source code
 
get_value(key)
Returns the value in container identified by key.		 source code
 
set_value_by_name(name, value)
Inserts or updates several values in container.		 source code
 
set_value(key, value)
Inserts or updates several values in container.		 source code
Method Details [hide private]

__init__()
(Constructor)

source code 

Creates a new Container.

Returns:
The container, as a GObject. (Container)

get_n_items()

source code 

Gets the number of items in a container.

Returns:
The number of items. (int)

value_type(key)

source code 

Returns the type of value in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The value type as GType; 0 if there is no such value. (GType)

contains(key)

source code 

Returns True if container contains a value identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
Whether container contains something identified by key. (bool)

remove(key)

source code 

Removes a value identified by key from a container.

Parameters:
  • key - A GQuark key. (int)
Returns:
True if there was such a value and was removed. (bool)

remove_by_prefix(prefix)

source code 

Removes a values whose key start with prefix from container container.

prefix can be None, all values are then removed.

Parameters:
  • prefix - A nul-terminated id prefix. (string)
Returns:
The number of values removed. (int)

transfer(dest, source_prefix, dest_prefix, force)

source code 

Copies a items from one place in container to another place.

The copies are shallow, objects are not physically duplicated, only referenced in dest.

Parameters:
  • dest - Destination container. It may be the same container as source, but source_prefix and dest_prefix may not overlap then. (Container)
  • source_prefix - Prefix in source to take values from. (string)
  • dest_prefix - Prefix in dest to put values to. (string)
  • force - True to replace existing values in dest. (bool)
Returns:
The number of actually transferred items. (int)

rename(key, newkey, force)

source code 

Makes a value in container identified by key to be identified by newkey.

When force is True existing value at newkey is removed from container. When it's False, an existing value newkey inhibits the rename and False is returned.

Parameters:
  • key - The current key. (int)
  • newkey - A new key for the value. (int)
  • force - Whether to replace existing value at newkey. (bool)
Returns:
Whether the rename succeeded. (bool)

foreach(prefix, function, user_data)

source code 

Calls function on each container item whose identifier starts with prefix.

The function is called function(GQuark key, GValue *value, user_data).

Parameters:
  • prefix - A nul-terminated id prefix. (string)
  • function - The function called on the items. (GHFunc)
  • user_data - The user data passed to function. (gpointer)
Returns:
The number of items function was called on. (int)

set_boolean(key, value)

source code 

Stores a boolean into container, identified by key.

Parameters:
  • key - A GQuark key. (int)
  • value - A boolean. (bool)

get_boolean(key)

source code 

Returns the boolean in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The boolean as gboolean. (bool)

set_uchar(key, value)

source code 

Stores an unsigned character into container, identified by key.

Parameters:
  • key - A GQuark key. (int)
  • value - An unsigned character. (guchar)

get_uchar(key)

source code 

Returns the unsigned character in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The character as guchar. (guchar)

set_int32(key, value)

source code 

Stores a 32bit integer into container, identified by key.

Parameters:
  • key - A GQuark key. (int)
  • value - A 32bit integer. (int)

get_int32(key)

source code 

Returns the 32bit integer in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The integer as guint32. (int)

set_enum(key, value)

source code 

Stores an enum into container, identified by key.

Note enums are treated as 32bit integers.

Parameters:
  • key - A GQuark key. (int)
  • value - An enum integer. (int)

get_enum(key)

source code 

Returns the enum in container identified by key.

Note enums are treated as 32bit integers.

Parameters:
  • key - A GQuark key. (int)
Returns:
The enum as gint. (int)

set_int64(key, value)

source code 

Stores a 64bit integer into container, identified by key.

Parameters:
  • key - A GQuark key. (int)
  • value - A 64bit integer. (gint64)

get_int64(key)

source code 

Returns the 64bit integer in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The 64bit integer as guint64. (gint64)

set_double(key, value)

source code 

Stores a double into container, identified by key.

Parameters:
  • key - A GQuark key. (int)
  • value - A double. (float)

get_double(key)

source code 

Returns the double in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The double as gdouble. (float)

get_string(key)

source code 

Returns the string in container identified by key.

The returned string must be treated as constant and never freed or modified.

Parameters:
  • key - A GQuark key. (int)
Returns:
The string. (string)

set_object(key, value)

source code 

Stores an object into container, identified by key.

The container claims ownership on the object, i.e. its reference count is incremented.

The object must implement Serializable interface to allow serialization of the container.

Parameters:
  • key - A GQuark key. (int)
  • value - An object to store into container. (gobject.GObject)

get_object(key)

source code 

Returns the object in container identified by key.

The returned object doesn't have its reference count increased, use g_object_ref() if you want to access it even when container may cease to exist.

Parameters:
  • key - A GQuark key. (int)
Returns:
The object as gpointer. (gobject.GObject)

keys()

source code 

Gets all quark keys of a container.

Returns:
A newly allocated array with quark keys of all container items, in no particular order. The number of items can be obtained with Container.get_n_items(). If there are no items, None is returned. (list)

Since: 2.7

duplicate_by_prefix(keys)

source code 

Duplicates a container keeping only values under given prefixes.

Like Container.duplicate(), this method creates a deep copy, that is contained object are physically duplicated too, not just referenced again.

Parameters:
  • keys - (StringArray*)
Returns:
A newly created container. (Container)

serialize_to_text()

source code 

Creates a text representation of container contents.

Note only simple data types are supported as serialization of compound objects is not controllable.

Returns:
A pointer array, each item containing string with one container item representation (name, type, value). The array is sorted by name. (StringArray*)

contains_by_name(n)

source code 

Expands to True if container c contains a value identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(bool)

remove_by_name(n)

source code 

Removes a value identified by name n from container c.

Expands to True if there was such a value and was removed.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(bool)

rename_by_name(n, new_name, force)

source code 

Makes a value in container c identified by name n to be identified by new name nn.

See Container.rename() for details.

Parameters:
  • n - A nul-terminated name (id). (string)
  • new_name - (string)
  • force - (bool)
Returns:
(bool)

set_boolean_by_name(n, v)

source code 

Stores a boolean into container c, identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - A boolean. (bool)

set_double_by_name(n, v)

source code 

Stores a double into container c, identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - A double integer. (float)

set_enum_by_name(n, v)

source code 

Stores an enum into container c, identified by name n.

Note enums are treated as 32bit integers.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - An enum. (int)

set_int32_by_name(n, v)

source code 

Stores a 32bit integer into container c, identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - A 32bit integer. (int)

set_int64_by_name(n, v)

source code 

Stores a 64bit integer into container c, identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - A 64bit integer. (gint64)

set_object_by_name(n, v)

source code 

Stores an object into container c, identified by name n.

See Container.set_object() for details.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - An object to store into container. (gobject.GObject)

set_uchar_by_name(n, v)

source code 

Stores an unsigned character into container c, identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
  • v - An unsigned character. (guchar)

get_boolean_by_name(n)

source code 

Gets the boolean in container c identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(bool)

get_double_by_name(n)

source code 

Gets the double in container c identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(float)

get_enum_by_name(n)

source code 

Gets the enum in container c identified by name n.

Note enums are treated as 32bit integers.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(int)

get_int32_by_name(n)

source code 

Gets the 32bit integer in container c identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(int)

get_int64_by_name(n)

source code 

Gets the 64bit integer in container c identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(gint64)

get_uchar_by_name(n)

source code 

Gets the unsigned character in container c identified by name n.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(guchar)

get_object_by_name(n)

source code 

Gets the object in container c identified by name n.

The returned object doesn't have its reference count increased, use g_object_ref() if you want to access it even when container may cease to exist.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(gobject.GObject)

get_string_by_name(n)

source code 

Gets the string in container c identified by name n.

The returned string must be treated as constant and never freed or modified.

Parameters:
  • n - A nul-terminated name (id). (string)
Returns:
(string)

duplicate()

source code 

Convenience macro doing gwy_serializable_duplicate() with all the necessary typecasting.

Returns:
(Container)

set_string_by_name(name, value)

source code 

Stores a string into container c, identified by name n.

The container makes a copy of the string, so it can be used on static strings.

Parameters:
  • name - (string)
  • value - (string)

Since: 2.38

set_string(key, value)

source code 

Stores a string into container, identified by key.

The container makes a copy of the string, so it can be used on static strings.

Parameters:
  • key - A GQuark key. (int)
  • value - A nul-terminated string. (string)

Since: 2.38

keys_by_name()

source code 

Gets all string keys of a container.

Returns:
A newly allocated array with string keys of all container items, in no particular order. The number of items can be obtained with Container.get_n_items(). If there are no items, None is returned. Unlike the array the strings are owned by GLib and must not be freed. (list)

Since: 2.7

get_value_by_name(name)

source code 

Gets the value in container c identified by name n.

Parameters:
  • name - (string)
Returns:
(any)

get_value(key)

source code 

Returns the value in container identified by key.

Parameters:
  • key - A GQuark key. (int)
Returns:
The value as a GValue. (any)

set_value_by_name(name, value)

source code 

Inserts or updates several values in container.

Parameters:
  • name - (string)
  • value - (any)

set_value(key, value)

source code 

Inserts or updates several values in container.

Parameters:
  • key - (int)
  • value - (any)

   Trees       Indices       Help   
Generated by Epydoc 3.0.1 http://epydoc.sourceforge.net