rubicon.objc.types - Non-Objective-C types and utilities¶
This module contains definitions for common C constants and types, and utilities for working with C types.
Common C type definitions¶
These are commonly used C types from various frameworks.
The
NSUInteger
type from <objc/NSObjCRuntime.h>. Equivalent to
c_ulong on 64-bit systems and
c_uint on 32-bit systems.
Bases: Structure
The
UIEdgeInsets
structure from <UIKit/UIGeometry.h>.
Bases: Structure
The
NSEdgeInsets
structure from <Foundation/NSGeometry.h>.
The
NSTimeInterval
type from <Foundation/NSDate.h>. Equivalent to c_double.
The
CFIndex
type from <CoreFoundation/CFBase.h>. Equivalent to
c_longlong on 64-bit systems
and c_long on 32-bit systems.
Common C constants¶
module level - document in source These are commonly used C constants from various frameworks.
module-attribute
¶
UIEdgeInsetsZero = UIEdgeInsets(0, 0, 0, 0)
The constant
UIEdgeInsetsZero:
a UIEdgeInsets instance with all
insets set to zero.
module-attribute
¶
NSZeroPoint = NSPoint(0, 0)
The constant
NSZeroPoint:
a NSPoint instance with the X and Y
coordinates set to zero.
module-attribute
¶
NSIntegerMax
The macro constant
NSIntegerMax
from <objc/NSObjCRuntime.h>: the maximum value that a
NSInteger can hold.
module-attribute
¶
NSNotFound
The constant
NSNotFound
from <Foundation/NSObjCRuntime.h>: a
NSInteger sentinel value indicating that
an item was not found (usually when searching in a collection).
Architecture detection constants¶
The following constants provide information about the architecture of the current environment. All of them are equivalent to the C compiler macros of the same names.
module-attribute
¶
__LP64__
Indicates whether the current environment is 64-bit.
If true, C longs and pointers are 64 bits in size, otherwise 32 bits.
Each of the following constants is true if the current environment uses the named architecture. At most one of these constants is true at once in a single Python runtime. (If the current architecture cannot be determined, all of these constants are false.)
Objective-C type encoding conversion¶
These functions are used to convert Objective-C type encoding strings to and from ctypes types, and to manage custom conversions in both directions.
All Objective-C encoding strings are represented as bytes rather than str.
ctype_for_encoding(encoding)
Return the C type corresponding to an Objective-C type encoding.
If a C type has been registered for the encoding, that type is returned. Otherwise, if the type encoding represents a compound type (pointer, array, structure, or union), the contained types are converted recursively. A new C type is then created from the converted ctypes, and is registered for the encoding (so that future conversions of the same encoding return the same C type).
For example, the type encoding {spam=ic} is not registered by default. However,
the contained types i and c are registered, so they are converted individually
and used to create a new ctypes.Structure with two fields of the correct
types. The new structure type is then registered for the original encoding
{spam=ic} and returned.
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
if the conversion fails at any point |
encoding_for_ctype(ctype)
Return the Objective-C type encoding for the given ctypes type.
If a type encoding has been registered for the C type, that encoding is returned. Otherwise, if the C type is a pointer type, its pointed-to type is encoded and used to construct the pointer type encoding.
Automatic encoding of other compound types (arrays, structures, and unions)
is currently not supported. To encode such types, a type encoding must be
manually provided for them using
register_preferred_encoding or
register_encoding.
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
if the conversion fails at any point |
register_preferred_encoding(encoding, ctype)
Register a preferred conversion between an Objective-C type encoding and a C type.
"Preferred" means that any existing conversions in each direction are
overwritten with the new conversion. To register an encoding without
overwriting existing conversions, use
register_encoding.
with_preferred_encoding(encoding)
Register a preferred conversion between an Objective-C type encoding and the decorated C type.
This is equivalent to calling
register_preferred_encoding on
the decorated C type.
register_encoding(encoding, ctype)
Register an additional conversion between an Objective-C type encoding and a C type.
"Additional" means that any existing conversions in either direction are
not overwritten with the new conversion. To register an encoding and
overwrite existing conversions, use
register_preferred_encoding.
with_encoding(encoding)
Register an additional conversion between an Objective-C type encoding and the decorated C type.
This is equivalent to calling
register_encoding on the
decorated C type.
unregister_encoding(encoding)
Unregister the conversion from an Objective-C type encoding to its corresponding C type.
Note that this does not remove any conversions in the other direction (from
a C type to this encoding). These conversions may be replaced with
register_encoding, or unregistered with
unregister_ctype. To remove all ctypes for
an encoding, use
unregister_encoding_all.
If the encoding was not registered previously, nothing happens.
unregister_encoding_all(encoding)
Unregister all conversions between an Objective-C type encoding and all corresponding ctypes.
All conversions from any C type to this encoding are removed recursively
using unregister_ctype_all.
If the encoding was not registered previously, nothing happens.
unregister_ctype(ctype)
Unregister the conversion from a C type to its corresponding Objective-C type encoding.
Note that this does not remove any conversions in the other direction (from
an encoding to this C type). These conversions may be replaced with
register_encoding, or unregistered
with unregister_encoding. To
remove all encodings for a C type, use
unregister_ctype_all.
If the C type was not registered previously, nothing happens.
unregister_ctype_all(ctype)
Unregister all conversions between a C type and all corresponding Objective-C type encodings.
All conversions from any type encoding to this C type are removed
recursively using
unregister_encoding_all.
If the C type was not registered previously, nothing happens.
get_ctype_for_encoding_map()
Get a copy of all currently registered encoding-to-C type conversions as a map.
get_encoding_for_ctype_map()
Get a copy of all currently registered C type-to-encoding conversions as a map.
split_method_encoding(encoding)
Split a method signature encoding into a sequence of type encodings.
The first type encoding represents the return type, all remaining type encodings represent the argument types.
If there are any numbers after a type encoding, they are ignored. On PowerPC, these numbers indicated each argument/return value's offset on the stack. These numbers are meaningless on modern architectures.
ctypes_for_method_encoding(encoding)
Convert a method signature encoding into a sequence of ctypes.
This is equivalent to first splitting the method signature encoding using
split_method_encoding, and
then converting each individual type encoding using
ctype_for_encoding.
Bases: c_void_p
Placeholder for the "unknown pointer" types ^?, ^{?} and ^(?).
Not to be confused with a ^v void pointer.
Usually a ^? is a function pointer, but because the encoding doesn't contain the
function signature, you need to manually create a CFUNCTYPE with the proper types,
and cast this pointer to it.
^{?} and ^(?) are pointers to a structure or union (respectively) with unknown
name and fields. Such a type also cannot be used meaningfully without casting it to
the correct pointer type first.
Default registered type encodings¶
The following table lists Objective-C's standard type encodings for primitive types, and the corresponding registered ctypes. These mappings can be considered stable, but nonetheless users should not hard code these encodings unless necessary. Instead, the encoding_for_ctype function should be used to encode types, because it is less error-prone and more readable than typing encodings out by hand.
Ctype |
Type encoding | Notes |
|---|---|---|
None (void) |
v |
|
c_bool |
B |
This refers to the bool type from C99 and C++. It is not necessarily the same as the BOOL type, which may be either c_byteor c_bool depending on the system and architecture. |
c_byte |
c |
|
c_ubyte |
C |
|
c_short |
s |
|
c_ushort |
S |
|
c_long |
l |
|
c_ulong |
L |
|
c_int |
i |
On 32-bit systems, c_int is an alias for c_long, and will be encoded as such. |
c_uint |
I |
On 32-bit systems, c_uint is an alias for c_ulong, and will be encoded as such. |
c_longlong |
q |
On 64-bit systems, c_longlong is an alias for c_long, and will be encoded as such. |
c_ulonglong |
Q |
On 64-bit systems, c_ulonglongis an alias for c_ulong, and will be encoded as such. |
c_float |
f |
|
c_double |
d |
|
c_longdouble |
D |
On ARM, c_longdoubleis an alias for c_double, and will be encoded as such. |
c_char |
c |
Only when encoding. Decoding c produces ctypes.c_byte, to allow using signed char as a Boolean value. |
c_char_p |
* |
|
POINTER(c_char) |
* |
Only when encoding. Decoding * produces c_char_p for easier use of C strings. |
POINTER(c_byte) |
* |
Only when encoding. Decoding * produces c_char_p for easier use of C strings. |
POINTER(c_ubyte) |
* |
Only when encoding. Decoding * produces c_char_p for easier use of C strings. |
c_wchar |
i |
Only when encoding. Decoding i produces c_int. |
c_wchar_p |
^i |
Only when encoding. Decoding ^i produces POINTER(c_int). |
c_void_p |
^v |
|
UnknownPointer |
^? |
This encoding stands for a pointer to a type that cannot be encoded, which in practice means a function pointer. |
UnknownPointer |
^{?}, ^(?) |
Only when decoding. These encodings stand for pointers to a structure or union with unknown name and fields. |
objc_id |
@ |
Class name suffixes in the encoding (e. g. @"NSString") are ignored. |
objc_block |
@? |
Block signature suffixes in the encoding (e. g. @?<v@?>) are ignored. |
SEL |
: |
|
Class |
# |
In addition, the following types defined by Rubicon are registered, but their encodings may vary depending on the system and architecture:
ctypes.py_objectNSIntegerNSUIntegerCGFloatNSPointCGPointNSSizeCGSizeNSRectCGRectUIEdgeInsetsNSEdgeInsetsNSTimeIntervalCFIndexUniCharunicharCGGlyphNSRange
Conversion of Python sequences to C structures and arrays¶
This function is used to convert a Python sequence (such as a tuple or list) to a specific C structure or array type. This function is mainly used internally by Rubicon, to allow passing Python sequences as method parameters where a C structure or array would normally be required. Most users will not need to use this function directly.
compound_value_for_sequence(seq, tp)
Create a C structure or array of type tp, initialized with values from seq.
If tp is a ctypes.Structure type, the newly created structure's fields are
initialized in declaration order with the values from seq. seq must have as many
elements as the structure has fields.
If tp is a Array type, the newly created array is initialized
with the values from seq. seq must have as many elements as the array type.
In both cases, if a structure field type or the array element type is itself a
structure or array type, the corresponding value from seq is recursively converted
as well.
Python to ctypes type mapping¶
These functions are used to map Python types to equivalent ctypes types, and to add or remove such mappings. This mechanism is mainly used internally by Rubicon, to for example allow ObjCInstance to be used instead of objc_id in method type annotations. Most users will not need to use these functions directly.
ctype_for_type(tp)
Look up the C type corresponding to the given Python type.
This conversion is applied to types used in
objc_method signatures,
objc_ivar types, etc. This function translates
Python built-in types and rubicon.objc classes to their
ctypes equivalents. Unregistered types (including types that are already
ctypes) are returned unchanged.
register_ctype_for_type(tp, ctype)
Register a conversion from a Python type to a C type.
unregister_ctype_for_type(tp)
Unregister a conversion from a Python type to a C type.
get_ctype_for_type_map()
Get a copy of all currently registered type-to-C type conversions as a mapping.
Default registered mappings¶
The following mappings are registered by default by Rubicon.
| Python type | Ctype |
|---|---|
int |
c_int |
float |
c_float |
bool |
c_bool |
bytes |
c_char_p |
ObjCInstance |
objc_id |
ObjCClass |
Class |
Constructor methods¶
NSEdgeInsetsMake(top, left, bottom, right)
Create and return an NSEdgeInsets with the
supplied edge values.
UIEdgeInsetsMake(top, left, bottom, right)
Constructs a new UIEdgeInsets object.