# **IACore - C++ Style Guide**

This document defines the coding standards for IACore and all IA Projects.  
Philosophy: Enforce Rust-like memory safety and discipline within modern C++20.

---
### **1. Oxide Usage**

Usage of [`Oxide`](https://github.com/I-A-S/Oxide) library and its philosophy is mandatory. 

`Oxide` is a single header library and a truncated version of it is listed below.

```cpp
#define OX_UNUSED(v) (void)(v)

namespace Oxide {

// =============================================================================
// Primitive Types
// =============================================================================

using u8 = std::uint8_t;
using u16 = std::uint16_t;
using u32 = std::uint32_t;
using u64 = std::uint64_t;

using i8 = std::int8_t;
using i16 = std::int16_t;
using i32 = std::int32_t;
using i64 = std::int64_t;

using f32 = float;
using f64 = double;

using usize = std::size_t;
using isize = std::ptrdiff_t;

// =============================================================================
// Template Types
// =============================================================================

template <typename T> using Const = const T;
template <typename T> using Mut = T;

template <typename T> using Ref = const T &;
template <typename T> using MutRef = T &;
template <typename T> using ForwardRef = T &&;

// =============================================================================
// Memory & Ownership
// =============================================================================

template <typename T> using Box = std::unique_ptr<T>;
template <typename T> using Arc = std::shared_ptr<T>;
template <typename T> using Weak = std::weak_ptr<T>;

template <typename T, typename... Args>
[[nodiscard]] inline auto make_box(ForwardRef<Args>... args) -> Box<T> {
  return std::make_unique<T>(std::forward<Args>(args)...);
}

template <typename T, typename... Args>
[[nodiscard]] inline auto make_arc(ForwardRef<Args>... args) -> Arc<T> {
  return std::make_shared<T>(std::forward<Args>(args)...);
}

// =============================================================================
// Error Handling
// =============================================================================

template <typename T, typename E = std::string>
using Result = Oxide::Internal::Expected<T, E>;

template <typename E> [[nodiscard]] inline auto fail(ForwardRef<E> error) {
  return Oxide::Internal::make_unexpected(std::forward<E>(error));
}

template <typename... Args>
[[nodiscard]] inline auto fail(Ref<std::format_string<Args...>> fmt,
                               ForwardRef<Args>... args) {
  return Oxide::Internal::make_unexpected(
      std::format(fmt, std::forward<Args>(args)...));
}

// =============================================================================
// Utilities
// =============================================================================

namespace Env {
#if defined(NDEBUG)
constexpr Const<bool> IS_DEBUG = false;
constexpr Const<bool> IS_RELEASE = true;
#else
constexpr Const<bool> IS_DEBUG = true;
constexpr Const<bool> IS_RELEASE = false;
#endif
} // namespace Env

[[noreturn]] inline void
panic(Ref<std::string> msg,
      Ref<std::source_location> loc = std::source_location::current()) {
  std::cerr << "\n[panic] " << msg << "\n           At: " << loc.file_name()
            << ":" << loc.line() << "\n";
  std::abort();
}

inline void
ensure(Const<bool> condition, Ref<std::string> msg,
       Ref<std::source_location> loc = std::source_location::current()) {
  if (Env::IS_DEBUG && !condition) {
    std::cerr << "\n[assert] " << msg << "\n            At: " << loc.file_name()
              << ":" << loc.line() << "\n";
    std::abort();
  }
}

using String = std::string;
using StringView = std::string_view;

template <typename T> using Option = std::optional<T>;
template <typename T> using Vec = std::vector<T>;
template <typename T> using Span = std::span<T>;
template <typename T1, typename T2> using Pair = std::pair<T1, T2>;
template <typename T, usize Count> using Array = std::array<T, Count>;

} // namespace Oxide

#define OX_TRY_PURE(expr)                                                     \
  {                                                                            \
    auto _ox_res = (expr);                                                    \
    if (!_ox_res) {                                                           \
      return Oxide::Internal::make_unexpected(std::move(_ox_res.error()));  \
    }                                                                          \
  }

#define OX_TRY(expr)                                                          \
  __extension__({                                                              \
    auto _ox_res = (expr);                                                    \
    if (!_ox_res) {                                                           \
      return Oxide::Internal::make_unexpected(std::move(_ox_res.error()));  \
    }                                                                          \
    std::move(*_ox_res);                                                      \
  })

#define OX_TRY_DISCARD(expr)                                                  \
  {                                                                            \
    auto _ox_res = (expr);                                                    \
    if (!_ox_res) {                                                           \
      return Oxide::Internal::make_unexpected(std::move(_ox_res.error()));  \
    }                                                                          \
    OX_UNUSED(*_ox_res);                                                     \
  }

```

Note: no need to explicity use `Oxide::` prefix as Oxide namespace is almost always globally used in IA projects.

All variables (local, member and parameter/argument) MUST always be wrapped in one of `Const<T>, Mut<T>, Ref<T>, MutRef<T>` or `ForwardRef<T>`.

> For outer most template of parameters/arguments, use the following Rule to decide between `Ref<T>` or `Const<T>`:
> 1) Is the parameter size <= 64, then use `Const`
> 2) Otherwise use `Ref`

| Use This | Instead of This |
| :---- | :---- |
| ```Box``` | ```std::unique_ptr``` |
| ```Arc``` | ```std::shared_ptr``` |
| ```Weak``` | ```std::weak_ptr``` |
| ```make_box``` | ```std::make_unique``` |
| ```make_arc``` | ```std::make_shared``` |

---

### **2. Naming Conventions**

We use **Rust Naming Conventions** to strictly distinguish Types from Values.

| Element | Style | Example |
| :---- | :---- | :---- |
| **Types / Classes** | PascalCase | ```StreamReader, TcpSocket``` |
| **Functions** | snake_case | ```read_bytes(), create_instance()``` |
| **Variables** | snake_case | ```buffer_size, socket_id``` |
| **Private Members** | m_snake_case | ```m_parser, m_data_size``` |
| **Constants** | SCREAMING_SNAKE | ```MAX_PATH_LENGTH``` |
| **Namespaces** | PascalCase | ```IACore, Oxide, IACore::Env``` |
| **Files** | PascalCase | ```StreamReader.hpp``` |

**Rule:** Never use Hungarian notation (e.g., iCount, strName) except for the m_ prefix on private members.

---

### **3. Primitives Types**

Do not use standard C++ primitives (int, long, unsigned int, double, char).  
Use the IACore Rust Aliases defined in IACore.hpp.

| Use This | Instead of This |
| :---- | :---- |
| ```i8, i16, i32, i64``` | ```int8_t, short, int, long long``` |
| ```u8, u16, u32, u64``` | ```uint8_t, unsigned short, unsigned int``` |
| ```f32, f64``` | ```float, double``` |
| ```usize``` | ```size_t, std::size_t``` |
| ```isize``` | ```std::ptrdiff_t``` |

**Exception:** Use char only for C-string literals or std::format compatibility.

---

### **4. Ownership & Pointers**

Adhere to strict ownership semantics. **Raw pointers (T\*) are non-owning.**

* **Box (ia::Box<T>):** Exclusive ownership. Use ia::make_box<T>().  
* **Arc (ia::Arc<T>):** Shared ownership (atomic ref-counting). Use sparingly.  
* **Raw Pointers (T\*):** Borrowed, non-owning, mutable view. **Must not be deleted.**  
* **Const Pointers (const T\*):** Borrowed, non-owning, read-only view.

**Forbidden:**

* new / delete / malloc / free.  
* Passing std::shared_ptr by value (unless sharing ownership is the intent).

---

### **5. Error Handling**

Exceptions are BANNED.  
All fallible functions must return ia::Result<T>.  
**Correct:**

```cpp
// Returns value OR error string  
auto read_file(const Path& path) -> ia::Result<String>;
```
Checking Errors (The IA_TRY Macro):  
Use IA_TRY to propagate errors (equivalent to Rust's ? operator).

```cpp
auto process_data() -> Result<String> {  
    IA_TRY(auto data, read_file("test.txt")); // Returns error if read_file fails  
    return process(data);  
}
```

---

### **6. Function Signatures**

Use **Trailing Return Syntax** for all functions (even void returns). This aligns with Rust (fn name() -> type) and handles complex template returns better.

**Correct:**

```cpp
auto calculate_sum(u32 a, u32 b) -> u32;
auto do_something() -> void;
```
**Incorrect:**

```cpp
u32 calculate_sum(u32 a, u32 b);
void do_something();
```
---

### **7. Const Correctness and Auto Usage**

Immutable by Default.  

`auto` keyword is BANNED.

Variables should be const unless mutation is explicitly required.  

**Correct:**

```cpp
Const<String> path = "data.bin";
Const<i32> result = process(path);
```
**Incorrect:**


```cpp
String path = "data.bin";
const auto result = process(path);
```
---

### **8. Macros**

Avoid Macros.  
Use constexpr for constants and inline templates for logic.

* **Allowed:** IA_TRY, IA_NODISCARD, Platform detection (internal).  
* **Banned:** TRUE, FALSE, CONST, IN, OUT.

### **9. Class Design (The "Safe Wrapper" Pattern)**

If a class wraps a C-library or raw resource (like simdjson), it must:

1. Be **Move-Only** (Delete Copy Constructor).  
2. Use a **Factory Method** (create()) that returns Result<Box<T>> or Result<T>.  
3. Never expose raw handles that outlive the wrapper.

```cpp
class SafeWrapper {  
public:  
    static auto create() -> Result<SafeWrapper>;  
      
    SafeWrapper(SafeWrapper&&) = default;  
    SafeWrapper(const SafeWrapper&) = delete;   
};
```
---