指针还是引用？5 个原则教你如何在函数参数中做出正确选择

各位编程爱好者、C++开发者们，大家好！

欢迎来到今天的技术讲座。今天我们要深入探讨一个在C++编程中频繁出现，却又常常困扰初学者甚至经验丰富开发者的问题：在函数参数中，我们究竟该选择指针（pointer）还是引用（reference）？这看似一个简单的语法选择，实则牵涉到程序的设计哲学、安全性、性能以及代码的可读性和维护性。

在C++中，指针和引用都是间接访问对象的方式，它们都允许我们操作存储在内存中某个位置的数据，而无需复制整个对象。然而，它们的语义、行为和应用场景却有着显著的区别。理解这些区别，并根据具体需求做出明智的选择，是写出健壮、高效、可维护的C++代码的关键。

本次讲座，我将为大家揭示五项核心原则。掌握这些原则，你就能在面对各种函数参数设计场景时，胸有成竹地做出最正确的选择。我们将从基础概念回顾开始，然后逐一剖析这五项原则，并辅以丰富的代码示例，确保大家不仅理解“是什么”，更能明白“为什么”和“如何做”。

准备好了吗？让我们开始这段旅程吧！

---

一、 指针与引用的基础回顾：理解根本差异

在深入探讨选择原则之前，我们有必要快速回顾一下C++中指针和引用的基本概念及其核心区别。这为我们后续的讨论奠定基础。

1.1 指针（Pointer）

指针是一个变量，其值为另一个变量的内存地址。它直接指向内存中的某个位置。

特点：

• 可为空（Nullable）： 指针可以指向 nullptr (或 NULL)，表示它不指向任何有效的对象。
• 可重定向（Reseatable）： 指针在生命周期内可以改变其指向的对象，即可以被重新赋值以指向不同的内存地址。
• 需要解引用（Dereference）： 访问指针所指向的值需要使用解引用运算符 *。
• 有自己的内存地址： 指针本身是一个变量，存储着地址，因此它也有自己的内存地址。
• 支持指针算术： 可以对指针进行加减运算，使其指向内存中的相邻位置。
• 可用于动态内存管理： new 和 delete 操作符返回和接受的都是指针。

示例：

#include <iostream>

int main() {
    int value = 10;
    int* ptr = &value; // ptr指向value的地址

    std::cout << "Value: " << value << std::endl;         // 输出 10
    std::cout << "Address of value: " << &value << std::endl; // 输出 value 的内存地址
    std::cout << "Pointer value (address): " << ptr << std::endl; // 输出 value 的内存地址
    std::cout << "Value via pointer: " << *ptr << std::endl;     // 输出 10 (解引用)

    *ptr = 20; // 通过指针修改value的值
    std::cout << "New value: " << value << std::endl;     // 输出 20

    int another_value = 30;
    ptr = &another_value; // 指针可以重新指向另一个变量
    std::cout << "Pointer now points to another_value: " << *ptr << std::endl; // 输出 30

    int* null_ptr = nullptr; // 指针可以为空
    if (null_ptr == nullptr) {
        std::cout << "null_ptr is null." << std::endl;
    }

    // 指针算术 (对于数组或连续内存块很有用)
    int arr[] = {1, 2, 3};
    int* p_arr = arr; // p_arr 指向 arr[0]
    std::cout << "arr[0] via pointer: " << *p_arr << std::endl;
    p_arr++; // p_arr 指向 arr[1]
    std::cout << "arr[1] via pointer arithmetic: " << *p_arr << std::endl;

    return 0;
}

1.2 引用（Reference）

引用是一个已存在对象的别名（alias）。一旦引用被初始化，它就始终指向同一个对象，不能被重新绑定到其他对象。

特点：

• 不可为空（Non-nullable）： 引用在声明时必须初始化，并且必须指向一个有效的对象。它不能是 nullptr。
• 不可重定向（Non-reseatable）： 一旦引用被初始化，它就永远绑定到最初引用的对象，不能改变指向。
• 自动解引用（Automatic Dereference）： 访问引用所指向的值时，无需使用任何特殊运算符，就像直接使用对象本身一样。
• 没有自己的内存地址（通常）： 引用本身不被视为一个独立的对象，它只是一个别名。虽然编译器可能在内部实现时使用地址，但从语言语义上讲，你无法获取引用的地址（&ref 会得到它所引用对象的地址）。
• 不支持引用算术： 无法对引用进行算术运算。
• 不用于动态内存管理： 引用不直接参与 new 和 delete 操作。

示例：

#include <iostream>

int main() {
    int value = 10;
    int& ref = value; // ref是value的别名，必须初始化

    std::cout << "Value: " << value << std::endl;     // 输出 10
    std::cout << "Value via reference: " << ref << std::endl; // 输出 10 (自动解引用)

    ref = 20; // 通过引用修改value的值
    std::cout << "New value: " << value << std::endl; // 输出 20

    int another_value = 30;
    // ref = another_value; // 错误！这不是重新绑定，而是将another_value的值赋给ref引用的对象（即value）
    // 如果尝试让ref引用another_value，你需要一个新的引用
    // int& new_ref = another_value;

    std::cout << "Value after assigning another_value to ref: " << value << std::endl; // 输出 30

    // int& invalid_ref; // 错误：引用必须初始化
    // int& null_ref = nullptr; // 错误：引用不能绑定到nullptr

    return 0;
}

1.3 核心差异速览表

特性	指针（Pointer）	引用（Reference）
可为空	可以为空 (nullptr)	必须始终引用一个有效对象（不可为空）
可重定向	可以改变指向不同的对象	一旦初始化，终身绑定到同一对象
初始化	可以不初始化（但通常建议初始化为nullptr或有效地址）	必须在声明时初始化
解引用	需要显式使用 * 运算符	自动解引用，使用方式与对象本身相同
内存地址	有自己的内存地址	通常没有独立的内存地址（是别名）
算术运算	支持指针算术	不支持算术运算
底层实现	通常是内存地址变量	通常由编译器实现为常量指针
语义	“指向一个对象”	“是另一个对象的别名”

理解了这些基本差异，我们就可以开始探讨在函数参数中如何做出选择的五项原则。

---

二、 原则一：空值（Nullability）与可选性（Optionality）

核心思想：如果函数参数可能合法地不指向任何对象（即“空”），或者表示一个可选的输入，那么使用指针。如果函数参数必须始终引用一个有效的对象，那么使用引用。

这是最基本也是最重要的选择原则之一。指针可以被赋值为 nullptr，这意味着一个指针参数可以明确地表示“没有提供对象”或“该参数是可选的”。而引用必须在初始化时绑定到一个有效的对象，因此它不能表示空值。

2.1 场景分析

• 使用指针的场景：

  • 可选参数： 当一个函数的功能在某些情况下不需要某个对象，或者这个对象是可选的。例如，一个查找函数，如果找不到，可能会返回 nullptr；一个配置函数，某些配置项是可选的。
  • 链表、树等数据结构： 节点通常包含指向下一个（或子）节点的指针，这些指针在列表尾部或叶子节点处可能为 nullptr。
  • 错误处理： 函数通过指针参数返回结果，如果操作失败，可以返回 nullptr。

• 使用引用的场景：

  • 强制存在： 当函数逻辑依赖于参数所引用的对象必须存在且有效时。使用引用可以省去在函数内部进行 nullptr 检查的麻烦，因为语言保证了引用总是有效的。
  • 避免拷贝（对于输入参数）： 当传递大型对象作为输入参数，但函数不修改它时，使用 const 引用可以避免不必要的拷贝，同时保证对象存在。

2.2 代码示例

示例 1: 可选的配置对象 (指针)

假设我们有一个配置管理器，它可以接受一个可选的日志记录器。

#include <iostream>
#include <string>
#include <vector>

// 假设有一个简单的日志接口
class Logger {
public:
    virtual void log(const std::string& message) = 0;
    virtual ~Logger() = default;
};

// 具体实现
class ConsoleLogger : public Logger {
public:
    void log(const std::string& message) override {
        std::cout << "[Console Log]: " << message << std::endl;
    }
};

// 配置管理器，可以有一个可选的Logger
class ConfigurationManager {
private:
    std::string config_name;
    // 假设有一些配置项
    std::vector<std::string> settings;

public:
    ConfigurationManager(const std::string& name) : config_name(name) {
        settings.push_back("Default setting 1");
        settings.push_back("Default setting 2");
    }

    // configure函数接受一个可选的Logger指针
    // 如果logger_ptr为nullptr，则不进行日志记录
    void configure(Logger* logger_ptr) {
        if (logger_ptr != nullptr) {
            logger_ptr->log("Starting configuration for " + config_name);
        } else {
            std::cout << "No logger provided for " << config_name << ", proceeding without logging." << std::endl;
        }

        // 模拟一些配置操作
        std::cout << "Applying configurations..." << std::endl;
        for (const auto& setting : settings) {
            if (logger_ptr != nullptr) {
                logger_ptr->log("Applied setting: " + setting);
            }
        }
        std::cout << "Configuration complete." << std::endl;

        if (logger_ptr != nullptr) {
            logger_ptr->log("Finished configuration for " + config_name);
        }
    }
};

int main() {
    ConsoleLogger console_logger;
    ConfigurationManager manager1("System A");
    ConfigurationManager manager2("System B");

    std::cout << "--- Configuring System A with logger ---" << std::endl;
    manager1.configure(&console_logger); // 传入有效的logger

    std::cout << "n--- Configuring System B without logger ---" << std::endl;
    manager2.configure(nullptr); // 不传入logger

    return 0;
}

在这个例子中，configure 函数接受 Logger* logger_ptr。如果调用者不希望进行日志记录，可以直接传入 nullptr。函数内部通过 if (logger_ptr != nullptr) 进行检查，这使得日志功能成为可选的。如果使用引用，则必须始终提供一个 Logger 对象。

示例 2: 查找函数 (指针返回，引用参数)

一个查找用户的功能，可能找不到用户。同时，为了避免拷贝，用户信息可以作为 const 引用传入。

#include <iostream>
#include <string>
#include <vector>
#include <map>

struct User {
    int id;
    std::string name;
    std::string email;

    void print() const {
        std::cout << "User ID: " << id << ", Name: " << name << ", Email: " << email << std::endl;
    }
};

class UserRepository {
private:
    std::map<int, User> users; // 存储用户数据

public:
    UserRepository() {
        users[1] = {1, "Alice", "[email protected]"};
        users[2] = {2, "Bob", "[email protected]"};
        users[3] = {3, "Charlie", "[email protected]"};
    }

    // findUserById 接受一个const int引用作为id，返回一个User*
    // 如果找到用户，返回指向用户的指针；否则返回nullptr
    User* findUserById(const int& user_id) { // user_id 必须存在，所以用引用
        auto it = users.find(user_id);
        if (it != users.end()) {
            return &(it->second); // 返回User对象的地址
        }
        return nullptr; // 未找到用户，返回nullptr
    }

    // findUserByName 接受一个const string引用作为name，返回一个const User*
    // 如果找到用户，返回指向用户的const指针；否则返回nullptr
    const User* findUserByName(const std::string& user_name) const { // user_name 必须存在，所以用引用
        for (const auto& pair : users) {
            if (pair.second.name == user_name) {
                return &(pair.second); // 返回const User对象的地址
            }
        }
        return nullptr; // 未找到用户，返回nullptr
    }
};

int main() {
    UserRepository repo;

    std::cout << "--- Searching for existing user ---" << std::endl;
    User* user1 = repo.findUserById(2);
    if (user1 != nullptr) {
        std::cout << "Found user: ";
        user1->print();
        user1->email = "[email protected]"; // 可以通过指针修改对象
        std::cout << "Updated user: ";
        user1->print();
    } else {
        std::cout << "User with ID 2 not found." << std::endl;
    }

    std::cout << "n--- Searching for non-existing user ---" << std::endl;
    User* user4 = repo.findUserById(4);
    if (user4 != nullptr) {
        std::cout << "Found user: ";
        user4->print();
    } else {
        std::cout << "User with ID 4 not found." << std::endl; // 预期输出
    }

    std::cout << "n--- Searching for user by name (const) ---" << std::endl;
    const User* user_alice = repo.findUserByName("Alice");
    if (user_alice != nullptr) {
        std::cout << "Found user by name: ";
        user_alice->print();
        // user_alice->email = "[email protected]"; // 错误：不能通过const指针修改
    } else {
        std::cout << "User 'Alice' not found." << std::endl;
    }

    return 0;
}

在这个例子中，findUserById 和 findUserByName 返回 User* 或 const User*，因为它们可能找不到对应的用户并返回 nullptr。而 user_id 和 user_name 作为输入参数，它们必须是有效的搜索条件，所以使用 const 引用来传递，避免拷贝且确保有效性。

总结： 当参数的缺失或不存在是一个合法且需要处理的条件时，指针是表达这种可选性的自然选择。反之，如果参数的有效性是函数执行的前提，引用则能提供更简洁、更安全的接口。

---

三、 原则二：输出参数与修改调用者状态

核心思想：如果函数需要修改一个由调用者提供的对象，并且该对象必须存在，那么通常使用引用作为输出参数。如果函数需要修改调用者传入的“指针所指向的内容”，或者更罕见地，需要改变调用者传入的“指针本身”所指向的对象，那么需要使用指针或指针的引用。

这个原则主要关注函数如何影响调用者的状态。C++中，函数不能直接返回多个值（结构体或元组除外），因此通过参数来修改调用者提供的对象是一种常见模式，即“输出参数”或“输入/输出参数”。

3.1 场景分析

• 使用引用作为输出参数：

  • 最常见的输出参数模式： 当函数需要填充或修改一个由调用者提供的现有对象时，引用是最清晰、最安全的。例如，一个解析函数将结果填充到一个 std::vector 中，或者一个计算函数将结果写入一个 double 变量。
  • 避免拷贝： 对于大型对象，通过引用修改可以避免将对象作为返回值复制的开销。
  • 保证有效性： 引用保证了传入的对象是有效的，函数内部无需进行 nullptr 检查。

• 使用指针作为输出参数（较少见，但有特定用途）：

  • 可选的输出： 如果输出参数是可选的（即调用者可能不关心这个输出），可以传递 nullptr。
  • 修改指针本身： 如果函数需要改变调用者传入的 指针变量本身 的值（使其指向不同的对象），例如在链表操作中改变 head 指针，或者在资源管理中将一个指针设置为 nullptr 以表示资源已被消耗，此时需要传入一个 指针的引用 (Type*&) 或 指向指针的指针 (Type**)。

3.2 代码示例

示例 1: 使用引用作为输出参数 (修改现有对象)

#include <iostream>
#include <string>
#include <vector>
#include <numeric> // For std::accumulate

struct Measurement {
    double value;
    std::string unit;

    void print() const {
        std::cout << "Value: " << value << " " << unit << std::endl;
    }
};

// 函数计算平均值，并将结果填充到由引用传入的Measurement对象中
// average_output 必须存在且有效
bool calculateAverage(const std::vector<double>& data, Measurement& average_output) {
    if (data.empty()) {
        std::cerr << "Error: Cannot calculate average of empty data." << std::endl;
        return false;
    }

    double sum = std::accumulate(data.begin(), data.end(), 0.0);
    average_output.value = sum / data.size();
    average_output.unit = "avg_unit"; // 假设设置一个默认单位

    return true;
}

// 另一个函数，通过引用交换两个整数的值
void swap(int& a, int& b) {
    int temp = a;
    a = b;
    b = temp;
}

int main() {
    std::vector<double> sensor_readings = {10.5, 12.3, 11.8, 13.0, 10.9};
    Measurement result_measurement; // 声明一个对象来接收结果

    std::cout << "--- Calculating average ---" << std::endl;
    if (calculateAverage(sensor_readings, result_measurement)) {
        std::cout << "Calculated average: ";
        result_measurement.print();
    }

    std::vector<double> empty_data;
    Measurement empty_result;
    std::cout << "n--- Calculating average for empty data ---" << std::endl;
    calculateAverage(empty_data, empty_result); // 会打印错误信息

    std::cout << "n--- Swapping integers ---" << std::endl;
    int x = 5, y = 10;
    std::cout << "Before swap: x = " << x << ", y = " << y << std::endl;
    swap(x, y); // 传入x和y的引用
    std::cout << "After swap: x = " << x << ", y = " << y << std::endl;

    return 0;
}

calculateAverage 函数的 average_output 参数是一个引用。这意味着调用者必须提供一个 Measurement 对象，函数会直接修改这个对象。函数 swap 也是经典的使用引用作为输出参数的例子。

示例 2: 修改调用者传入的指针所指向的对象 (通过指针)

这是指函数通过一个 Type* 参数来修改 *Type 对象。这与引用类似，只是多了一层指针的语义，允许空值。

#include <iostream>
#include <string>

struct Settings {
    int volume;
    bool enable_notifications;
    std::string theme;

    void print() const {
        std::cout << "Volume: " << volume
                  << ", Notifications: " << (enable_notifications ? "On" : "Off")
                  << ", Theme: " << theme << std::endl;
    }
};

// 函数修改传入的Settings指针所指向的对象
// settings_ptr 可以是 nullptr，表示不修改任何设置
void applyDefaultSettings(Settings* settings_ptr) {
    if (settings_ptr != nullptr) {
        settings_ptr->volume = 50;
        settings_ptr->enable_notifications = true;
        settings_ptr->theme = "Light";
        std::cout << "Default settings applied." << std::endl;
    } else {
        std::cout << "No settings object provided to apply defaults." << std::endl;
    }
}

int main() {
    Settings my_settings = {10, false, "Dark"};
    std::cout << "--- Before applying defaults ---" << std::endl;
    my_settings.print();

    std::cout << "n--- Applying defaults to my_settings ---" << std::endl;
    applyDefaultSettings(&my_settings); // 传入 my_settings 的地址
    std::cout << "--- After applying defaults ---" << std::endl;
    my_settings.print();

    std::cout << "n--- Trying to apply defaults with nullptr ---" << std::endl;
    applyDefaultSettings(nullptr); // 传入 nullptr

    return 0;
}

在这里，applyDefaultSettings 接受 Settings* settings_ptr。如果 settings_ptr 不是 nullptr，它就会修改 settings_ptr 所指向的 Settings 对象。这与引用作为输出参数的区别在于，这里允许 nullptr，即允许调用者选择不提供对象。

示例 3: 修改调用者传入的指针本身 (指针的引用)

这是更高级的用法，当函数需要改变调用者持有的 指针变量的值 时使用。例如，一个函数可能需要“接管”一个动态分配的对象的指针，并将其设置为 nullptr，或者在一个链表操作中改变 head 指针。

#include <iostream>
#include <string>
#include <memory> // For std::unique_ptr (though not strictly necessary for this example)

struct Resource {
    std::string name;
    Resource(const std::string& n) : name(n) {
        std::cout << "Resource '" << name << "' created." << std::endl;
    }
    ~Resource() {
        std::cout << "Resource '" << name << "' destroyed." << std::endl;
    }
    void use() const {
        std::cout << "Using resource '" << name << "'." << std::endl;
    }
};

// 函数 "接管" 资源的所有权，将传入的指针设置为 nullptr
// 传入的是 Resource* 的引用，这意味着函数可以修改 main 函数中的 resource_ptr 变量本身
void takeOwnershipAndClear(Resource*& resource_ptr) {
    if (resource_ptr != nullptr) {
        std::cout << "Function taking ownership of resource: " << resource_ptr->name << std::endl;
        resource_ptr->use();
        delete resource_ptr; // 释放资源
        resource_ptr = nullptr; // 将 main 函数中的指针设置为 nullptr
        std::cout << "Resource released and pointer cleared." << std::endl;
    } else {
        std::cout << "No resource to take ownership of." << std::endl;
    }
}

// 另一个例子：在链表操作中更新头节点
struct Node {
    int data;
    Node* next;
    Node(int d) : data(d), next(nullptr) {}
};

// 在链表头部插入新节点，需要修改head指针
void insertAtHead(Node*& head, int data) {
    Node* new_node = new Node(data);
    new_node->next = head; // 新节点的下一个是当前的头
    head = new_node;       // 更新head指向新节点
    std::cout << "Inserted " << data << " at head. New head: " << head->data << std::endl;
}

// 打印链表
void printList(const Node* head) {
    std::cout << "List: ";
    while (head != nullptr) {
        std::cout << head->data << " -> ";
        head = head->next;
    }
    std::cout << "nullptr" << std::endl;
}

// 释放链表内存
void deleteList(Node*& head) {
    while (head != nullptr) {
        Node* temp = head;
        head = head->next;
        delete temp;
    }
    std::cout << "List deleted." << std::endl;
}

int main() {
    std::cout << "--- Demonstrating takeOwnershipAndClear ---" << std::endl;
    Resource* my_resource_ptr = new Resource("MainResource");
    my_resource_ptr->use();

    takeOwnershipAndClear(my_resource_ptr); // 传入指针的引用
    if (my_resource_ptr == nullptr) {
        std::cout << "my_resource_ptr is now nullptr in main." << std::endl;
    }

    std::cout << "n--- Demonstrating insertAtHead (linked list) ---" << std::endl;
    Node* head_node = nullptr; // 初始链表为空

    printList(head_node);
    insertAtHead(head_node, 10); // 传入 head_node 的引用
    printList(head_node);
    insertAtHead(head_node, 20);
    printList(head_node);
    insertAtHead(head_node, 30);
    printList(head_node);

    deleteList(head_node); // 清理链表内存
    if (head_node == nullptr) {
        std::cout << "head_node is now nullptr after deletion." << std::endl;
    }

    return 0;
}

takeOwnershipAndClear 函数接受 Resource*& resource_ptr。这意味着 resource_ptr 是 main 函数中 my_resource_ptr 变量的一个别名。函数内部对 resource_ptr 的修改（包括 delete 和将其设置为 nullptr）会直接反映到 main 函数的 my_resource_ptr 上。同理，insertAtHead 函数通过 Node*& head 改变了 main 函数中 head_node 的值，使其指向新的头节点。

总结： 对于简单的输出参数（修改现有对象），引用是首选，因为它更简洁、更安全。只有当输出参数可能为空，或者函数需要改变调用者所持有的 指针变量本身 时，才考虑使用指针，或者更精确地，指针的引用。

---

四、 原则三：所有权语义与资源管理

核心思想：如果函数需要“接管”一个动态分配的对象的生命周期（即获得其所有权），或者需要共享一个对象的所有权，那么应该使用智能指针作为参数。如果函数只是观察或修改一个由外部管理的对象，且不涉及所有权转移，那么使用引用或原始指针（如果允许为空）更合适。

在现代C++中，直接使用原始指针进行动态内存管理是被强烈不鼓励的，因为它极易导致内存泄漏和悬空指针。智能指针（std::unique_ptr 和 std::shared_ptr）是解决这些问题的最佳实践。

4.1 场景分析

• 使用 std::unique_ptr 作为参数：

  • 转移所有权： 当函数被调用后，参数所指向的对象的唯一所有权将从调用者转移到函数内部（或函数内部创建的对象）。这通常通过 std::move 来实现。
  • 单所有权： std::unique_ptr 保证了对象的独占所有权，确保了在任何时候只有一个智能指针指向该对象。

• 使用 std::shared_ptr 作为参数：

  • 共享所有权： 当多个部分需要共享同一个对象的生命周期时。std::shared_ptr 使用引用计数来管理对象的生命周期，当最后一个 std::shared_ptr 销毁时，对象才会被释放。

• *使用 const std::shared_ptr<T>& 或 `const T/T&` 作为参数：**

  • 观察者模式（不改变所有权）： 当函数只是需要访问或修改由 std::shared_ptr 管理的对象，但不需要改变引用计数或所有权时，通常传入 const std::shared_ptr<T>&。如果函数甚至不需要知道对象是否由 std::shared_ptr 管理，只是需要访问对象本身，那么 const T& 或 T* (如果允许空) 是更通用的选择。

• *使用原始指针 `T或引用T&`：**

  • 非拥有者（Non-owning）： 当函数只是暂时借用对象的访问权限，而不承担其生命周期管理责任时，使用原始指针（如果允许空）或引用（如果必须存在）。这称为“非拥有性引用/指针”。

4.2 代码示例

示例 1: 转移 std::unique_ptr 的所有权

#include <iostream>
#include <memory>
#include <string>
#include <vector>

class Document {
public:
    std::string title;
    std::string content;

    Document(const std::string& t, const std::string& c) : title(t), content(c) {
        std::cout << "Document '" << title << "' created." << std::endl;
    }
    ~Document() {
        std::cout << "Document '" << title << "' destroyed." << std::endl;
    }

    void print() const {
        std::cout << "--- " << title << " ---n" << content << "n-------------------n";
    }
};

class DocumentManager {
private:
    std::vector<std::unique_ptr<Document>> documents;

public:
    // addDocument 接收一个 unique_ptr，表示它将接管Document的所有权
    void addDocument(std::unique_ptr<Document> doc) {
        if (doc) { // 检查是否为nullptr
            std::cout << "DocumentManager: Adding document '" << doc->title << "'." << std::endl;
            documents.push_back(std::move(doc)); // 将所有权转移到vector中
        } else {
            std::cout << "DocumentManager: Attempted to add a null document." << std::endl;
        }
    }

    void listDocuments() const {
        std::cout << "n--- Current Documents in Manager ---" << std::endl;
        if (documents.empty()) {
            std::cout << "No documents." << std::endl;
            return;
        }
        for (const auto& doc_ptr : documents) {
            if (doc_ptr) {
                doc_ptr->print();
            }
        }
    }
};

int main() {
    DocumentManager manager;

    std::cout << "--- Creating and adding documents with unique_ptr ---" << std::endl;
    // 创建一个 unique_ptr
    std::unique_ptr<Document> doc1 = std::make_unique<Document>("Report 2023", "Annual report content...");
    manager.addDocument(std::move(doc1)); // 转移所有权，doc1现在为nullptr

    if (!doc1) {
        std::cout << "doc1 in main is now nullptr after move." << std::endl;
    }

    // 直接创建并转移
    manager.addDocument(std::make_unique<Document>("Memo", "Important memo content."));

    manager.listDocuments();

    std::cout << "n--- Testing with a null unique_ptr ---" << std::endl;
    std::unique_ptr<Document> null_doc_ptr;
    manager.addDocument(std::move(null_doc_ptr));

    std::cout << "n--- Main function ending ---" << std::endl;
    // 当manager销毁时，其内部的unique_ptr会销毁所管理Document对象
    return 0;
}

addDocument 函数接受 std::unique_ptr<Document> doc。调用时，通过 std::move(doc1) 将 doc1 的所有权转移给函数。函数内部再将所有权转移到 documents 向量中。一旦函数返回，doc1 在 main 函数中就不再拥有 Document 对象了。

示例 2: 共享 std::shared_ptr 的所有权

#include <iostream>
#include <memory>
#include <string>
#include <vector>

class Image {
public:
    std::string filename;
    int width, height;

    Image(const std::string& fn, int w, int h) : filename(fn), width(w), height(h) {
        std::cout << "Image '" << filename << "' loaded." << std::endl;
    }
    ~Image() {
        std::cout << "Image '" << filename << "' unloaded." << std::endl;
    }

    void display() const {
        std::cout << "Displaying image: " << filename << " (" << width << "x" << height << ")" << std::endl;
    }
};

class ImageProcessor {
public:
    // processImage 接收 shared_ptr，表示它也需要一份所有权，直到处理完成
    void processImage(std::shared_ptr<Image> img) {
        if (img) {
            std::cout << "ImageProcessor: Processing image '" << img->filename << "'." << std::endl;
            img->display();
            // 模拟一些处理...
            std::cout << "ImageProcessor: Finished processing image '" << img->filename << "'." << std::endl;
        } else {
            std::cout << "ImageProcessor: No image to process." << std::endl;
        }
        // 当img离开作用域时，引用计数会减少
    }

    // inspectImage 接收 const shared_ptr&，表示只查看，不改变所有权
    void inspectImage(const std::shared_ptr<Image>& img) const {
        if (img) {
            std::cout << "ImageProcessor: Inspecting image '" << img->filename << "' (ref_count=" << img.use_count() << ")." << std::endl;
            img->display();
        } else {
            std::cout << "ImageProcessor: No image to inspect." << std::endl;
        }
    }

    // renderImage 接收原始指针或引用，表示它只是一个临时观察者
    void renderImage(Image& img_ref) {
        std::cout << "ImageProcessor: Rendering image (via reference): '" << img_ref.filename << "'." << std::endl;
        img_ref.display();
    }
};

int main() {
    ImageProcessor processor;

    std::cout << "--- Creating and processing images with shared_ptr ---" << std::endl;
    std::shared_ptr<Image> img1 = std::make_shared<Image>("Sunset.jpg", 1920, 1080);
    std::cout << "img1 ref count: " << img1.use_count() << std::endl; // 1

    processor.processImage(img1); // 传入 shared_ptr，引用计数增加到2 (函数参数也持有一份)
    std::cout << "img1 ref count after processImage: " << img1.use_count() << std::endl; // 1 (函数参数离开作用域)

    // 创建第二个 shared_ptr，共享所有权
    std::shared_ptr<Image> img2 = img1;
    std::cout << "img1 ref count after img2 creation: " << img1.use_count() << std::endl; // 2

    processor.inspectImage(img1); // 传入 const shared_ptr&，不改变引用计数
    std::cout << "img1 ref count after inspectImage: " << img1.use_count() << std::endl; // 2

    // 传入原始引用
    if (img1) {
        processor.renderImage(*img1);
    }

    std::cout << "n--- Main function ending ---" << std::endl;
    // 当img1和img2都销毁时，Image对象才会被释放
    return 0;
}

processImage 接受 std::shared_ptr<Image> img。这意味着函数内部会获得 img 的一个副本，从而增加引用计数。当函数返回时，这个副本被销毁，引用计数减少。inspectImage 接受 const std::shared_ptr<Image>& img，这表示它只是观察智能指针，不影响引用计数。renderImage 接受 Image& img_ref，这表示它只是一个非拥有者的观察者。

总结： 当函数参数涉及到动态内存的所有权管理时，优先考虑使用智能指针。std::unique_ptr 用于独占所有权转移，std::shared_ptr 用于共享所有权。对于仅仅访问对象而不涉及所有权管理的场景，const T& 或 T* 仍然是更轻量、更通用的选择。

---

五、 原则四：C-风格互操作性与低层内存访问

*核心思想：当需要与C语言库或API进行交互，或者进行低层内存操作（如指针算术、直接访问内存块、处理 `void` 等）时，原始指针是不可或缺的。对于大多数纯C++应用，应优先使用引用或智能指针。**

C++设计之初就考虑了与C语言的兼容性。许多操作系统API、旧的库或某些高性能计算库仍然使用C风格的接口，这些接口大量使用原始指针。

5.1 场景分析

• 使用原始指针的场景：

  • C语言API： C库函数通常接受原始指针作为参数（例如 FILE*, char*, void*）。
  • 数组处理： 数组名在很多上下文中会退化为指向其第一个元素的指针。指针算术在处理数组或连续内存块时非常有用。
  • 泛型内存操作： void* 用于传递任意类型的内存块，尤其是在需要手动内存分配和类型转换的低层操作中。
  • 与硬件交互： 直接访问内存映射寄存器等。
  • 实现底层数据结构： 如链表、树等，其内部节点间的连接通常通过原始指针实现。

• 避免在纯C++应用中滥用原始指针：

  • 在现代C++中，除非有明确的理由（上述情况），否则应避免使用原始指针进行资源管理，以防止内存泄漏和悬空指针。
  • 对于集合遍历，C++11引入的基于范围的 for 循环和迭代器通常比指针算术更安全、更易读。

5.2 代码示例

*示例 1: 与C标准库函数 qsort 交互 (使用 `void`)**

qsort 是C标准库中的一个泛型排序函数，它接受 void* 指针和比较函数指针。

#include <iostream>
#include <vector>
#include <algorithm> // For std::sort, which is preferred in C++
#include <cstdlib>   // For qsort

// C风格的比较函数，用于qsort
// 接受两个 const void* 参数，需要进行类型转换
int compareInts(const void* a, const void* b) {
    int arg1 = *static_cast<const int*>(a);
    int arg2 = *static_cast<const int*>(b);
    if (arg1 < arg2) return -1;
    if (arg1 > arg2) return 1;
    return 0;
}

int main() {
    std::vector<int> numbers = {5, 2, 9, 1, 7, 3};

    std::cout << "Original numbers: ";
    for (int n : numbers) {
        std::cout << n << " ";
    }
    std::cout << std::endl;

    // 使用 C 风格的 qsort
    // numbers.data() 返回指向底层数组的原始指针
    std::qsort(numbers.data(), numbers.size(), sizeof(int), compareInts);

    std::cout << "Sorted numbers (qsort): ";
    for (int n : numbers) {
        std::cout << n << " ";
    }
    std::cout << std::endl;

    // C++ 风格的排序 (更推荐)
    std::vector<double> doubles = {3.14, 1.618, 2.718, 0.577};
    std::cout << "Original doubles: ";
    for (double d : doubles) {
        std::cout << d << " ";
    }
    std::cout << std::endl;
    std::sort(doubles.begin(), doubles.end());
    std::cout << "Sorted doubles (std::sort): ";
    for (double d : doubles) {
        std::cout << d << " ";
    }
    std::cout << std::endl;

    return 0;
}

std::qsort 函数的第一个参数是 void* base，它要求我们传入待排序数组的起始地址，这里我们通过 numbers.data() 获取 std::vector 内部数据的原始指针。比较函数 compareInts 也必须接受 const void* 类型，并在内部进行 static_cast 转换为实际类型。

示例 2: 处理C风格字符串 (使用 char* 和 const char*)

#include <iostream>
#include <cstring> // For C-style string functions

// 打印 C 风格字符串
void printCString(const char* str) {
    if (str != nullptr) {
        std::cout << "C-string: " << str << std::endl;
    } else {
        std::cout << "C-string: (null)" << std::endl;
    }
}

// 复制 C 风格字符串到目标缓冲区
// dest 必须指向一个足够大的缓冲区
// src 必须指向一个有效的 C 风格字符串
// count 是目标缓冲区的最大大小
void copyCString(char* dest, const char* src, size_t count) {
    if (dest != nullptr && src != nullptr && count > 0) {
        // 使用 strncpy_s (C11/C++11 safe version) 或 strncpy
        // 注意 strncpy 不保证 null 终止如果源字符串太长
        std::strncpy(dest, src, count - 1); // 留一个字节给 null 终止符
        dest[count - 1] = ''; // 确保 null 终止
        std::cout << "Copied C-string." << std::endl;
    } else {
        std::cerr << "Error: Invalid arguments for copyCString." << std::endl;
    }
}

int main() {
    char buffer[100]; // 缓冲区

    const char* message = "Hello, C-style strings!";
    printCString(message);

    copyCString(buffer, message, sizeof(buffer));
    printCString(buffer);

    // 尝试传入 nullptr
    printCString(nullptr);

    // 尝试复制一个太长的字符串
    const char* long_message = "This is a very long message that might exceed the buffer size.";
    char small_buffer[10];
    copyCString(small_buffer, long_message, sizeof(small_buffer));
    printCString(small_buffer); // 会被截断

    return 0;
}

printCString 接受 const char* str，这是C++中表示只读C风格字符串的标准方式。copyCString 接受 char* dest 和 const char* src，分别用于可写的目标缓冲区和只读的源字符串。这展示了原始指针在处理与C语言兼容的字符串时的必要性。

总结： 当你的C++代码需要与C语言接口交互，或者进行内存级别的精细控制时，原始指针是不可避免的。在这种情况下，要特别注意指针的有效性（nullptr 检查）和内存安全。但在纯C++上下文中，应尽量利用C++的更高层抽象（如 std::string, std::vector, 智能指针，迭代器）来替代原始指针。

---

六、 原则五：可读性、安全性与C++惯用法

核心思想：在没有特定需求（如空值、所有权转移或C互操作）的情况下，优先选择引用作为函数参数，因为它们提供了更好的可读性、安全性，并符合现代C++的惯用法。

这个原则可以看作是前四个原则的综合补充，强调了在日常编程中，如果前述的特定条件都不满足，那么引用通常是更优的选择。

6.1 场景分析

• 使用引用的优势：

  • 自动解引用，简化语法： 使用引用时，你无需像指针那样显式解引用（* 运算符），语法更简洁，代码更接近直接操作对象。
  • 保证非空，提高安全性： 引用必须绑定到有效对象，消除了 nullptr 检查的需要，降低了空指针解引用的风险。
  • 不可重定向，增强稳定性： 引用一旦绑定就不能改变，这为代码提供了更强的语义保证，减少了意外重新绑定的可能性。
  • 作为 const 参数避免拷贝： 对于输入参数，const Type& 是传递大型对象而不进行拷贝的标准和安全方式。
  • 符合C++惯用法： 引用被广泛用于输出参数、函数返回类型以及操作符重载等场景，是C++语言的核心特性。

• 使用指针的考虑：

  • 显式空值： 只有当参数可能为 nullptr 且需要处理这种情况时，才使用指针。
  • 显式地址操作： 只有当需要进行指针算术或直接操作内存地址时，才使用指针。
  • C互操作： 与C API交互时，指针是必需的。

6.2 代码示例

示例 1: 优先使用 const 引用作为输入参数 (避免拷贝)

#include <iostream>
#include <string>
#include <vector>

struct Person {
    std::string name;
    int age;
    std::string address;
    std::vector<std::string> hobbies;

    void print() const {
        std::cout << "Name: " << name << ", Age: " << age << ", Address: " << address;
        std::cout << ", Hobbies: [";
        for (size_t i = 0; i < hobbies.size(); ++i) {
            std::cout << hobbies[i] << (i == hobbies.size() - 1 ? "" : ", ");
        }
        std::cout << "]" << std::endl;
    }
};

// 使用 const Person& 作为输入参数：
// 1. 避免了 Person 对象的拷贝开销。
// 2. 保证了 person 引用的是一个有效的 Person 对象。
// 3. const 保证了函数不会修改传入的 Person 对象。
void displayPersonInfo(const Person& person) {
    std::cout << "Displaying info for: ";
    person.print();
    // person.age = 30; // 错误：不能修改 const 引用指向的对象
}

// 如果使用 Person* 作为输入参数，需要额外的 nullptr 检查和解引用
void displayPersonInfoPtr(const Person* person_ptr) {
    if (person_ptr != nullptr) {
        std::cout << "Displaying info for (via pointer): ";
        person_ptr->print(); // 需要使用 -> 运算符
        // person_ptr->age = 30; // 错误：不能修改 const 指针指向的对象
    } else {
        std::cout << "Cannot display info for a null person pointer." << std::endl;
    }
}

int main() {
    Person p = {"Alice", 25, "123 Main St", {"Reading", "Hiking"}};

    std::cout << "--- Using reference ---" << std::endl;
    displayPersonInfo(p); // 简洁、安全

    std::cout << "n--- Using pointer ---" << std::endl;
    displayPersonInfoPtr(&p); // 需要取地址符，函数内部需要 nullptr 检查和 -> 运算符
    displayPersonInfoPtr(nullptr); // 可以处理空值，但如果不需要空值语义，则增加了复杂性

    return 0;
}

displayPersonInfo 函数接受 const Person&。这表明函数期望一个有效的 Person 对象，并且不会修改它。这种方式既高效（避免拷贝）又安全（保证对象存在且不可修改），是C++中传递大型只读对象的标准做法。而 displayPersonInfoPtr 需要显式的 & 和 nullptr 检查，增加了冗余。

示例 2: 使用引用作为输出参数 (清晰的意图)

回顾原则二中的 calculateAverage 和 swap 函数，它们都使用了引用作为输出参数，这清晰地表达了函数会修改调用者提供的对象。

#include <iostream>

// 使用引用作为输出参数，清晰表明函数会修改 a 和 b
void swapValues(int& a, int& b) {
    int temp = a;
    a = b;
    b = temp;
}

int main() {
    int val1 = 10, val2 = 20;
    std::cout << "Before swap: val1=" << val1 << ", val2=" << val2 << std::endl;
    swapValues(val1, val2); // 函数可以直接修改 val1 和 val2
    std::cout << "After swap: val1=" << val1 << ", val2=" << val2 << std::endl;

    // 如果用指针：
    // void swapValuesPtr(int* a_ptr, int* b_ptr) { /* ... */ }
    // swapValuesPtr(&val1, &val2); // 调用时需要 &，函数内部需要 * 解引用
    // 并且如果允许 nullptr，还需要额外检查
    return 0;
}

swapValues 的接口 (int& a, int& b) 明确告诉调用者，这两个参数会被修改，且它们必须是有效的 int 变量。这种清晰性是引用优于指针的一个重要方面。

6.3 最佳实践总结表

场景	优先选择	理由	备选/次选	理由（何时选择次选）
输入参数（大对象，不修改）	const Type&	避免拷贝，保证对象有效且不被修改，简洁安全。	const Type*	如果参数是可选的（可能为 nullptr）。
输入参数（小对象，不修改）	Type (按值传递)	拷贝开销小，语义最清晰（函数拥有自己的副本），不会影响外部。	const Type&	对极小对象，编译器可能优化掉引用，但按值通常更简单。
输出参数（修改调用者提供的对象）	Type&	清晰表明修改意图，保证对象有效，无需 nullptr 检查，避免拷贝。	Type*	如果输出参数是可选的（调用者可能不关心，传入 nullptr）。
需要修改调用者持有的指针变量本身	Type*&	允许函数修改调用者传入的指针所指向的对象或将指针设为 nullptr。	Type**	C 风格的接口，或者不希望引入引用语义时。
所有权转移（独占）	std::unique_ptr<T>	明确所有权转移语义，自动管理资源，避免内存泄漏。	T* (作为返回值，但通常不作为参数接收)	极少数特殊场景，需要手动管理内存或与C API交互，风险高。
所有权共享	std::shared_ptr<T>	允许多个拥有者共享资源，自动管理生命周期。	const std::shared_ptr<T>&	如果函数只是观察共享对象而不增加引用计数。
C 语言互操作/低层内存操作	Type* / void*	与 C API 兼容，支持指针算术，直接内存访问。	Type&	C++ 封装层，将原始指针转换为引用，提供更安全的接口。
参数可能为“空”或“缺失”	Type*	明确表达参数的可选性或缺失，需要 nullptr 检查。	std::optional<Type> (C++17)	更现代、更安全的表达可选值的方式，但通常用于返回值，参数使用 const Type& 或 Type。

总结： 在C++中，引用是传递参数的首选方式，尤其是在需要避免拷贝且参数必须有效时。它提供了更好的类型安全性和可读性。指针则保留给那些引用无法满足的特定需求，例如处理空值、执行低层内存操作或与C语言接口互操作。

---

七、 结论

在C++函数参数中选择指针还是引用，并非简单的语法偏好，而是一项关乎程序设计、健壮性、可读性和性能的关键决策。通过深入理解指针和引用的底层机制，并遵循我们今天探讨的五项核心原则：空值与可选性、输出参数与修改调用者状态、所有权语义与资源管理、C-风格互操作性与低层内存访问，以及可读性、安全性与C++惯用法，你将能够为不同的场景做出最合适的选择。

总而言之，现代C++编程倾向于优先使用引用，因为它提供了更强的类型安全、更简洁的语法和对对象有效性的保证。只有当引用的特性不足以满足特定需求时（如允许空值、需要重新绑定或进行指针算术），才应考虑使用原始指针。而对于动态内存管理，智能指针无疑是最佳实践。始终牢记：选择最能清晰表达意图、最能提高代码安全性、同时兼顾性能的参数类型。

感谢大家的参与，希望今天的讲座能帮助大家在C++的道路上走得更远、更稳健！