Metadata-Version: 2.4
Name: pointer-x
Version: 0.1.0
Summary: Pure Python C-style pointers with pluggable memory backend.
Author-email: vazx096 <3803274936@qq.com>
License: MIT License
        
        Copyright (c) 2026 vazx096
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Pointer

A Python package that simulates C-style pointers — because **Python said it can't have pointers. I took that personally.**

## Overview

`pointer` provides a memory simulation layer on top of Python, implementing raw pointer arithmetic, typed memory allocation, and manual memory management — all inside a single `bytearray` acting as virtual RAM.

## How It Works

- A global `_vram` (`bytearray`) serves as the "physical memory".
- `PtrType` objects hold an integer address into `_vram` and interpret the bytes according to a `Type` (short, int, long, char, bool, etc.).
- `Type` is defined via `MainTypes` (size in bytes) and `ModifiedTypes` (signed/unsigned).
- `nullptr` is a sentinel object representing a null pointer.
- Memory allocation is tracked via a global `used` set to prevent overlapping.

## Core Components

| Class / Enum | Purpose |
|---|---|
| `MainTypes` | Defines base C types with byte sizes (short=2, int=4, long=8, etc.) |
| `ModifiedTypes` | Modifiers like `unsigned` |
| `PtrType` | A typed pointer that reads/writes from `_vram` |
| `nullptr` | Null pointer sentinel |
| `_vram` | The actual `bytearray` acting as raw memory |

## Usage

### Basic Pointer

```python
import pointer as ptr

# Create an integer pointer (default nullptr)
p = ptr.PtrType(ptr.Type(ptr.mat.int))

# Allocate memory (assign a value -> triggers allocation)
p.value = 42
print(p.value)  # 42
print(p.ptr)    # address in _vram

# Free memory
p.free()
```

### Pointer Arithmetic

```python
p = ptr.PtrType(ptr.Type(ptr.mat.int))
p.value = 100

# Move pointer by N elements (in bytes = N * type.size)
p += 1  # move forward by 4 bytes
p -= 1  # move back by 4 bytes
```

### Array / Multiple Elements

```python
# Create a pointer pointing to 5 consecutive ints
p = ptr.PtrType(ptr.Type(ptr.mat.int), _length=5)
for i in range(5):
    p[i] = i * 10

print(p[2])  # 20
```

### Direct Memory Manipulation via `_vram`

Since `_vram` is a public `bytearray`, you can manipulate it directly using `ctypes` or raw byte operations:

```python
import ctypes
import pointer

# Create a writable buffer that shares memory with _vram
pointer._vram = ctypes.create_string_buffer(1 * 1024 ** 2)

# Now any PtrType reads/writes to this ctypes buffer
p = pointer.PtrType(pointer.Type(pointer.mat.int))
p.value = 999
print(pointer._vram[p.ptr:p.ptr+4])  # raw bytes
```

> **Warning:** Modifying `_vram` directly can corrupt existing pointers. Use with caution.

## API Reference

### `PtrType(type, default=nullptr, _length=1)`

- `type`: A `Type(mat, mot)` object.
- `default`: Initial value (or `nullptr`).
- `_length`: Number of elements (for array-style access).

**Properties:**
- `.value` → get/set the value at the current pointer address.
- `.ptr` → current integer address (or `nullptr`).
- `[index]` → array-style element access.

**Methods:**
- `.free()` → release allocated memory.
- `__iadd__` / `__isub__` → pointer arithmetic.

### `Type(mat, mot=ModifiedTypes.unsigned)`

- `mat`: A `MainTypes` enum member.
- `mot`: `ModifiedTypes.unsigned` or default.

## Limitations

- Single global `_vram` — no per-process isolation.
- No garbage collection; manual `free()` required.
- Not thread-safe.
- Pointer arithmetic is element-based, not byte-based (unlike real C).

## License

MIT — because even fake pointers deserve freedom.
