CONVERSION REFERENCE

Variables, types, and strings

Give function parameters and results explicit types. Local variables may use annotations or let PyCForge infer their type from an assignment.

Variables outside functions · Branches and loops · Variable and string errors

Choose a supported type

Python type	Generated C type	What to check
`bool`	`bool`	Use `True` and `False`, rather than integer values.
`int`	`int64_t`	Values and arithmetic results must stay between −9,223,372,036,854,775,808 and 9,223,372,036,854,775,807.
`float`	`double`	Use floating values such as `1.0`. Infinite and NaN literals are unsupported.
`str`	`const char *`	Text is UTF-8, without embedded NUL characters. See the C caller requirements below; file reads have separate memory rules.

An annotation does not convert a value. For example, rate: float = 1 is rejected; write rate: float = 1.0. A variable must keep the same type after reassignment. Union annotations such as int | str are unsupported.

Declarations and assignments inside functions

def adjust(amount: int) -> int:
    total: int
    total = amount
    left = right = 4
    left, right = right + 1, left - 1
    total += left + right
    return total

total: int declares a type without assigning a value. Assign it before every possible read.
total: int = amount declares and assigns in one statement.
left = right = expression evaluates the expression once and assigns that value to both names.
left, right = right, left swaps two scalars. Flat tuple or list targets need a matching tuple or list of expressions. Starred targets, nested targets, and unpacking arbitrary iterables are unsupported.
+=, -=, *=, /=, //=, and %= follow the same type and arithmetic limits as their ordinary operators.

A local declaration shadows a same-named module variable. It still needs its own assignment; it does not inherit the module value.

Function annotations and returns

def scale(value: float, factor: float) -> float:
    return value * factor

Use top-level def functions, with annotated parameters and return values. Every path through a value-returning function must return the declared type. Nested functions, decorators, generators, asynchronous functions, recursive calls, and exceptions are unsupported.

Assignments in branches

Assign a local on every branch before using it afterward. An annotation alone does not supply zero, an empty string, or any other initial value.

def label(ready: bool) -> str:
    text: str
    if ready:
        text = "ready"
    else:
        text = "waiting"
    return text

String operations on function inputs

Expression	Result	Limits
`len(text)`	Number of Unicode code points	Counts characters as Python does, not UTF-8 bytes or visible grapheme clusters.
`text == other`, `!=`, `<`, `<=`, `>`, `>=`	Comparison of string contents	Use one comparison at a time. Ordering follows Unicode code points.
`text.startswith(prefix)`, `text.endswith(suffix)`	Boolean	One string argument; no tuple of alternatives or start/end arguments.
`text.find(needle)`	Character index, or `-1` if absent	One string argument. An empty needle returns `0`.
`needle in text`, `needle not in text`	Boolean	Both operands must be strings.

def greeting_length(text: str) -> int:
    if text.startswith("hé"):
        return len(text)
    return -1

def separator_position(text: str) -> int:
    return text.find(":")

For "hé😀", len returns 3 and find("😀") returns 2. No Unicode normalization is applied: visually similar composed and decomposed text can compare differently.

Extra operations when text is known during conversion

When the text and arguments are constants, PyCForge can also resolve concatenation, repetition, indexing, slicing, and the methods below. Constants can come from earlier module assignments or straightforward local assignments.

TITLE = "  café  ".strip().upper()
BANNER = "[" + TITLE + "]"

def banner() -> str:
    return BANNER

def reverse_sample() -> str:
    text = "hé😀"
    return text[::-1]

Supported constant methods are upper, lower, casefold, strip, lstrip, rstrip, replace, removeprefix, removesuffix, count, find, startswith, and endswith. Expansion is size-limited, so huge repetitions are rejected.

Runtime text construction is still limited. Concatenating function inputs, slicing unknown text, changing its case, replacing parts of it, formatting, split, and join are unsupported. For example, return text.upper() cannot convert when text is a parameter. If appropriate for your program, prepare that text before calling the converted function.

Passing strings from C

Pass a non-null pointer to valid UTF-8 terminated by a NUL byte. Keep that storage alive while the function uses it, and while using a returned pointer that refers to it. The byte length must be less than INT64_MAX. These string operations do not allocate a new string. Do not free a string literal or a borrowed result; see file-read results for the separate case that does require free.

Numeric expressions

Supported numeric expressions include compatible +, -, *, unary signs, and comparisons. Use / only with floating operands. Numeric and/or, truth tests, and chained comparisons are supported in the documented conditional forms; arbitrary Python object truthiness is not.

Integer floor division and remainder

def bucket(value: int) -> int:
    return value // 10

def signed_remainder(value: int) -> int:
    return value % -3

// and % follow Python's floor and remainder rules. Use a direct nonzero integer literal divisor, rather than a parameter or calculated expression. Dividing a possible minimum 64-bit integer by -1 is rejected. The minimum 64-bit integer itself is also unsupported as a divisor.

Keep evaluation order predictable

Accepted assignments and calls preserve Python's operand evaluation order. Re-convert after changing source or settings, and test the generated C with the input ranges your program actually uses.