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.
- class rubicon.objc.types.c_ptrdiff_t([value])¶
The ptrdiff_t type from
<stddef.h>
. Equivalent toc_long
on 64-bit systems andc_int
on 32-bit systems.
- class rubicon.objc.types.NSInteger([value])¶
The NSInteger type from
<objc/NSObjCRuntime.h>
. Equivalent toc_long
on 64-bit systems andc_int
on 32-bit systems.
- class rubicon.objc.types.NSUInteger([value])¶
The NSUInteger type from
<objc/NSObjCRuntime.h>
. Equivalent toc_ulong
on 64-bit systems andc_uint
on 32-bit systems.
- class rubicon.objc.types.CGFloat([value])¶
The CGFloat type from
<CoreGraphics/CGBase.h>
. Equivalent toc_double
on 64-bit systems andc_float
on 32-bit systems.
- class rubicon.objc.types.NSPoint([x, y])¶
The NSPoint structure from
<Foundation/NSGeometry.h>
.Note
On 64-bit systems this is an alias for
CGPoint
.
- class rubicon.objc.types.NSSize([width, height])¶
The NSSize structure from
<Foundation/NSGeometry.h>
.Note
On 64-bit systems this is an alias for
CGSize
.
- class rubicon.objc.types.CGSize([width, height])¶
The CGSize structure from
<CoreGraphics/CGGeometry.h>
.
- class rubicon.objc.types.NSRect([origin, size])¶
The NSRect structure from
<Foundation/NSGeometry.h>
.Note
On 64-bit systems this is an alias for
CGRect
.
- class rubicon.objc.types.CGRect([origin, size])¶
The CGRect structure from
<CoreGraphics/CGGeometry.h>
.
- class rubicon.objc.types.UIEdgeInsets([top, left, bottom, right])¶
The UIEdgeInsets structure from
<UIKit/UIGeometry.h>
.
- class rubicon.objc.types.NSEdgeInsets([top, left, bottom, right])¶
The NSEdgeInsets structure from
<Foundation/NSGeometry.h>
.
- class rubicon.objc.types.NSTimeInterval([value])¶
The NSTimeInterval type from
<Foundation/NSDate.h>
. Equivalent toc_double
.
- class rubicon.objc.types.CFIndex([value])¶
The CFIndex type from
<CoreFoundation/CFBase.h>
. Equivalent toc_longlong
on 64-bit systems andc_long
on 32-bit systems.
- class rubicon.objc.types.UniChar([value])¶
- class rubicon.objc.types.unichar([value])¶
The unichar type from
<Foundation/NSString.h>
. Equivalent toc_ushort
.
- class rubicon.objc.types.CGGlyph([value])¶
The CGGlyph type from
<CoreGraphics/CGFont.h>
. Equivalent toc_ushort
.
- class rubicon.objc.types.CFRange([location, length])¶
The CFRange type from
<CoreFoundation/CFBase.h>
.
- class rubicon.objc.types.NSRange([location, length])¶
The NSRange type from
<Foundation/NSRange.h>
.- location¶
- length¶
The location and length as
NSUInteger
s.
Common C constants¶
These are commonly used C constants from various frameworks.
- rubicon.objc.types.UIEdgeInsetsZero¶
The constant UIEdgeInsetsZero: a
UIEdgeInsets
instance with all insets set to zero.
- rubicon.objc.types.NSZeroPoint¶
The constant NSZeroPoint: a
NSPoint
instance with the X and Y coordinates set to zero.
- rubicon.objc.types.NSIntegerMax¶
The macro constant NSIntegerMax from
<objc/NSObjCRuntime.h>
: the maximum value that aNSInteger
can hold.
- rubicon.objc.types.NSNotFound¶
The constant NSNotFound from
<Foundation/NSObjCRuntime.h>
: aNSInteger
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.
- rubicon.objc.types.__LP64__¶
Indicates whether the current environment is 64-bit. If true, C
long
s and pointers are 64 bits in size, otherwise 32 bits.
- rubicon.objc.types.__i386__¶
- rubicon.objc.types.__x86_64__¶
- rubicon.objc.types.__arm__¶
- rubicon.objc.types.__arm64__¶
Each of these 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
.
- rubicon.objc.types.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 typesi
andc
are registered, so they are converted individually and used to create a newStructure
with two fields of the correct types. The new structure type is then registered for the original encoding{spam=ic}
and returned.- Raises:
ValueError – if the conversion fails at any point
- rubicon.objc.types.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()
orregister_encoding()
.- Raises:
ValueError – if the conversion fails at any point
- rubicon.objc.types.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()
.
- rubicon.objc.types.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.
- rubicon.objc.types.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()
.
- rubicon.objc.types.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.
- rubicon.objc.types.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 withunregister_ctype()
. To remove all ctypes for an encoding, useunregister_encoding_all()
.If the encoding was not registered previously, nothing happens.
- rubicon.objc.types.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.
- rubicon.objc.types.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 withunregister_encoding()
. To remove all encodings for a C type, useunregister_ctype_all()
.If the C type was not registered previously, nothing happens.
- rubicon.objc.types.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.
- rubicon.objc.types.get_ctype_for_encoding_map()¶
Get a copy of all currently registered encoding-to-C type conversions as a map.
- rubicon.objc.types.get_encoding_for_ctype_map()¶
Get a copy of all currently registered C type-to-encoding conversions as a map.
- rubicon.objc.types.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.
- rubicon.objc.types.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 usingctype_for_encoding()
.
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.
|
Type encoding |
Notes |
---|---|---|
|
|
|
|
This refers to the |
|
|
||
|
||
|
||
|
||
|
||
|
||
|
On 32-bit systems, |
|
|
On 32-bit systems, |
|
|
On 64-bit systems, |
|
|
On 64-bit systems, |
|
|
||
|
||
|
On ARM, |
|
|
Only when encoding. Decoding |
|
|
||
|
|
Only when encoding. Decoding |
|
|
Only when encoding. Decoding |
|
|
Only when encoding. Decoding |
|
Only when encoding. Decoding |
|
|
Only when encoding. Decoding |
|
|
||
|
This encoding stands for a pointer to a type that cannot be encoded, which in practice means a function pointer. |
|
|
Only when decoding. These encodings stand for pointers to a structure or union with unknown name and fields. |
|
|
Class name suffixes in the encoding (e. g. |
|
|
Block signature suffixes in the encoding (e. g. |
|
|
||
|
- class rubicon.objc.types.UnknownPointer(value=None)¶
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.
In addition, the following types defined by Rubicon are registered, but their encodings may vary depending on the system and architecture:
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.
- rubicon.objc.types.compound_value_for_sequence(seq, tp)¶
Create a C structure or array of type
tp
, initialized with values fromseq
.If
tp
is aStructure
type, the newly created structure’s fields are initialized in declaration order with the values fromseq
.seq
must have as many elements as the structure has fields.If
tp
is aArray
type, the newly created array is initialized with the values fromseq
.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.
- rubicon.objc.types.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 andrubicon.objc
classes to theirctypes
equivalents. Unregistered types (including types that are already ctypes) are returned unchanged.
- rubicon.objc.types.register_ctype_for_type(tp, ctype)¶
Register a conversion from a Python type to a C type.
- rubicon.objc.types.unregister_ctype_for_type(tp)¶
Unregister a conversion from a Python type to a C type.
- rubicon.objc.types.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.