C++——智能指针

“智能”指针？

指针本似乎只应是一个特殊的整型变量，其何以有“智能”一说？其源于C/C++中堆内存(Heap memory)管理的有关问题。

C语言在<stdlib.h>中提供了类似于malloc、free等函数来进行堆内存的简单分配及回收；C++中则引入了operator new、operator delete[]等来配合面向对象的语义；但仅依赖它们进行内存管理的缺点亦非常明显，包括但不限于：

  • 容易“忘记”或“绕过”内存回收的部分，进而导致内存泄漏问题想必各位刚接触C语言时就被填鸭式地记忆过malloc完一定要free；
  • 内存“所有权”(ownership)不清晰。比如往某个函数中传入指针时无法明确其内存的“所有权”（指是否能重新分配、释放等）是否转移，函数嵌套调用时容易导致内存管理混乱（如 double-free ，即双重释放问题，亦是UB）；
  • 作为整型变量的指针非常“脆弱”，极易在函数调用链中被不经意地修改。

比如下述C代码片段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
void foo(int*);
void bar(const int* p)
{
    p += 2; //?
    free(p); //?
}
void fun()
{
    int* ptr = (int*)calloc(10,sizeof(int));
    bool status;

    //...

    for(int i = 0;i<5;++i)
    {
        ptr++; //?
    }

    foo(ptr); //?
    bar(ptr); //?

    if(!status)
    {
        return; //?
    }

    free(ptr);
}

稍多加学习与内存管理等有关的知识就会发现，上述代码的槽点不断。
如void bar()的形参声明为const int*，只使用顶层const约束了不能通过p来修改指向的值，但架不住p本身容易被乱改，对于稍长一些的函数来说非常致命（极易忘记前述代码中p已经被改动过）。同时即使加上底层const，此般“固若金汤”也无法防止本函数间有人试图提前将其指向的内存free掉——内存管理权（所有权）混乱，可谓“引 SegmentFault 入室”。
void fun()中难得地记得了在函数结束时free申请的内存，但往上看数行就可发觉隐患之一：若status为false，则会触发 early return，进而ptr指向的内存将（在程序允许结束或者大概率崩溃之前）无法被释放。C++中此类问题更甚——除了显式的returnexit或abort一类的[[norerturn]]不算，exceptions 乱飞也极易在不经意间直接“跳出”函数，且异常相比此类显式的return更难以被发现和追踪。

但不可否认的是，C/C++的“手动”内存管理也是其极大的特色和优势之一——对底层内存拥有极高自由度的读写权，同时没有后台 garbage collection 的束缚，使之能广泛地应用于底层软硬件的程序开发，同时拥有相比其它解释型/混合型语言“一骑绝尘”的效率。

如何在保留“手动内存管理”特色的同时，应用语言自身机制帮助程序设计者管理内存，自然成为了C++发展的一大课题。

C++98：前世的auto_ptr

C++98提出了一个因为太憨在C++11被废弃(deprecated)并在C++17被移除(removed)的智能指针的雏形：auto_ptr。

基本设计与成效

回顾到我们的基本需求，即希望在申请的堆内存离开其作用域时自动释放，显然将之封装在构造/析构函数中是其不二之选。
同时还应当提供一些易于访问原始指针的接口，其可通过类成员函数和操作符重载实现。
由此，可以写出一个简单的类模板如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
template<class Ty>
class auto_ptr
{
public:
    auto_ptr();
    ~auto_ptr();

    Ty* operator->();
    const Ty* operator->() const;

    Ty& operator*();
    const Ty& operator*() const;

    Ty* get();
    const Ty* get() const;

    Ty* release();
    void reset(Ty*);

    //...
private:
    Ty* ptr;
};

其中只需要

1
2
3
4
5
template<class Ty>
auto_ptr<Ty>::~auto_ptr()
{
    delete ptr;
}

就可以实现自动“释放内存”的功能了。operator->等重载亦能实现“无感”的底层指针访问，如：

1
2
auto_ptr<std::string> sp;
std::cout << sp->length() << std::endl;

利用operator->重载的“二次解析”特性，访问类成员的方式无异于sp是原始指针的情况。

get()和release()成员函数都会返回原始指针，区别在于get()用于向后兼容一些C样式的API以及少数需要利用原始指针的情况（并未“交出”指针的所有权，只是临时供使用），release()则会“交出”指针的所有权（调用后该对象管理的指针置空，进而该指针指向的堆内存不会被自动释放，需要手动清理）。

reset()函数则用于重置其管理的指针（新指针亦必须指向有效的、已申请的堆内存），看实现即知其用途：

1
2
3
4
5
6
template<class Ty>
void auto_ptr<Ty>::reset(Ty* p)
{
    delete ptr;
    ptr = p;
}

此处应用了C++的operator delete“逃课”机制：free/delete一个空指针不会发生任何事情（即该操作是“安全”的）。

Hint：为什么花如此多的篇幅讲述一个已经 deprecated 类的成员函数？因为现代的智能指针“三剑客”成员函数的语义与之相同，只是更改了部分其它函数的实现（或增减了一些其它函数）来完善其功能。

缺点

看似上述auto_ptr在功能全面的同时实现看似“天衣无缝”，但其依然未能规避开原始指针的诸多缺点。

首先，指针的“所有权”在函数传参等场景时依然不够明确或许是C++98/03没有移动语义的锅：

1
2
3
4
5
6
7
8
void fun(auto_ptr<int>);

void foo()
{
    auto_ptr<int> p;
    //...
    fun(p); //?
}

在对fun(p)调用后，fun函数中auto_ptr这一形参会将p管理的指针释放掉，导致现在foo中的p管理了一个无效的内存，进而SegmentFault只是时间问题。

C++11：智能指针“三剑客”

auto_ptr迎合时代发展的浪潮，在C++11中蜕变为了unique_ptr、shared_ptr和weak_ptr三剑客，通过和C++11引入的大量其它语法特性的巧妙配合，使其在内存管理辅助中如鱼得水。

同时auto_ptr其也是现代C++中最先被 deprecated 和 removed 的一批库特性之一。

unique_ptr

字如其名，unique_ptr表示一个“独占”的指针。
其通过和C++11中的= delete;声明结合，禁止了其复制构造和复制赋值（形如 unique_ptr<Ty>::unique_ptr(const unique_ptr&) = delete;），保留了移动构造和移动赋值的接口，由此解决了“所有权”问题之争——当传递unique_ptr时，必须选择是否显式地放弃所有权：

1
2
3
4
5
void f1(unique_ptr<int>);

unique_ptr<int> ip;
f1(ip); //Error: invokes function `unique_ptr<int>::unique_ptr(const unique_ptr&)` that is declared as deleted
f1(std::move(ip)); //OK, transferrs ownership to f1

移动构造的语义实现参考：

1
2
3
4
5
template<class Ty>
unique_ptr<Ty>::unique_ptr(unique_ptr&& rhs) noexcept : ptr(nullptr)
{
    this->reset(rhs.release());
}

unique_ptr的其它成员函数实现和auto_ptr大同小异，不再赘述。

shared_ptr

但unique_ptr只涵盖了“只需要”独占指针的情况；在并发编程等任务中，很多时候需要不同函数“共享”一块内存空间，同时又希望实现“自动”的内存管理。
由此引出了“共享指针”shared_ptr和“弱指针”weak_ptr。

shared_ptr的部分接口实现仍与auto_ptr类似。主要区别之一在其还会内置一个“计数器”且允许复制构造，每次复制构造会令该指针的计数器+1，析构（或因被其它指针赋值而放弃对当前指针管理）则令其计数器-1；
当一个指针对应的的计数器归零时，shared_ptr将该指针指向的堆内存释放。

在较复杂的并发编程中，因同一shared_ptr的各成员函数没有被synchroized修饰可以被不同线程同时调用，为了避免数据竞争(data race)，应使用std::atomic<std::shared_ptr>。

1
2
3
4
5
6
7
8
9
10
11
12
void fun(std::shared_ptr<int>);

int main()
{
    std::thread[10] ta;
    std::shared_ptr<int> sp;
    //...
    for(auto& th : ta)
    {
        th = std::thread(fun,sp);
    }
}

shared_ptr的部分重要成员函数如下：

成员函数 作用
size_t use_count() const 返回管理指针的计数，未绑定则为0
operator bool() const 等价于return static_cast<bool>(use_count());
(C++20)bool unique() const 等价于 return use_count() == 1;

weak_ptr

“弱指针”weak_ptr在并发/异步编程中亦能大显身手，其本质上一种不具备底层内存所有权(ownership)的shared_ptr。
weak_ptr可以被默认构造（空构造），亦可初始化时即设定“观测”一个shared_ptr（后续亦可以reset()方法重置观测对象）：

1
2
3
shared_ptr<int> sp;
weak_ptr<int> wp{};
weak_ptr<int> wp2{sp};

这个weak_ptr将成为一个 Observer （观测者），其“观测”着这个shared_ptr的底层指针，但不增加其Counter的计数。
同时由于weak_ptr不具备内存所有权，因而其不能直接访问shared_ptr管理的底层指针；访问内存的方法参考以下“独有”的成员函数：

成员函数 作用
size_t use_count() const 返回观测的shared_ptr对应指针的计数，未绑定则为0
bool expired() const 若该weak_ptr“观测”的shared_ptr依然有效（即其管理的指针计数不为0），返回true，否则为false；weak_ptr未初始化，即未绑定至shared_ptr时同样返回false。等价于return static_cast<bool>(use_count());
shared_ptr<Ty> lock() 等价于return expired() ? shared_ptr<Ty>(ptr) : shared_ptr<Ty>()，ptr为观测的shared_ptr

其应用场景在某个函数/线程不知道某堆内存是否仍可用，但又要观察并“按需取之”时，能安全地实现相应的语义。
简单示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#include <memory>

void fun(std::weak_ptr<int> wp)
{
    if(auto ptr = wp.lock())
    {
        std::cout << "Get number:" << *ptr << std::endl;
    }   
    else
    {
        std::cout << "Pointer expired";
    }
}

int main()
{
    std::shared_ptr<int> sp;
    fun(sp);

    sp.reset(new int(5));
    fun(sp);

    delete sp.release();
    fun(sp);
}

神秘的第二模板参数

若仔细观察，可以发现这些智能指针作为类模板，实际上有两个模板参数，声明形如：

1
2
3
4
5
template<class Ty,class Dx = std::default_delete<Ty>>
class unique_ptr
{
    /*...*/
};

多数情况下只会用到第一个模板参数（指定指针的类型）。
第二个参数意为指定删除器(Deleter)，若不指定则默认为::operator delete（或operator delete[]，下同）来释放内存，指定之能适配部分手动管理“内存块”的场景。
类似的还有std::vector等容器的模板声明：

1
2
3
4
5
template<class Ty,class Ax = std::allocator<Ty>>
class vector
{
    /*...*/
};

此处的std::allocator若不指定，则默认为::operator new的方式分配内存；指定之可改用自定义的内存分配器。

外传：RAII

RAII，全称 Resource Acquisition Is Initialization，是一种的程序设计“哲学”，适用于多种编程语言（越“低级”适用性越强）。
智能指针就是RAII的生动实践实例之一，同样地还有fstream、lock_guard、vector等。

有关RAII（还有SFINAE、Rule-of-3/5/0等C++ Idioms）的更详解可移步可能还在咕的C++——Idioms

展开全文 >>

C++——explicit

闲登小阁看新晴。

explicit修饰符是C++11引入的两个短小精悍，而又对编程风格产生较大影响的特性，可谓之“新晴”。

C之阙漏：隐式转换

C语言中类型的转换只分显式和隐式两种。其中隐式转换则在参数传递、赋值（含初始化）等操作时自动完成毕竟作为POP语言并没有对象、及其关联的构造/析构等概念。

1
int x = 3.14; //Implicit conversion from `double` to `int`

隐式转换虽在程序设计中带来了不少便利，但其亦引来了最为诟病的一点——难以达成精确的类型转换控制/约束。
C中如strcpy的库函数函数大量应用了无符号整型作为形参类型/返回值，但编程中经常需要将有符号整型传进传出点名int抛给size_t或者反之，许多时候因图方便就没有进行严格的转换检查，同fopen不看errno等“陋习”共为许多C语言代码埋下了祸根：

1
2
int x = strlen(str);
strcpy(str,str + 5,x - 3);

先不论第一行size_t向int的截断毕竟相比之下已经算小问题了；
第二行中若x < 3，则传入strcpy的长度转为size_t后产生无符号下溢出(unsigned underflow)，进而导致内存“无限”访问而导致段错误/UB。

显然，在类型转换的便捷性和类型安全性之间，现代C++亟需找到一个新的平衡。

C++11的答案——explicit

语法

explicit关键字可用于修饰构造函数和转换构造函数(conversion constructor，即形如operator X()的成员函数)。
回顾二者的联系和区别：

属性 构造函数 转换构造函数
函数签名 X(...) operator Y()
属性 特殊成员函数 普通成员函数
可为虚函数？ 否（因为调用时对象的建立尚未完成） 是
形参列表 可有任意数量形参 必定为空
可否重载？ 可以参数列表差分重载 只能以const属性重载
返回类型？ 没有返回类型，在构造新对象时自动调用 不显式声明返回类型，返回的是类Y的一个新对象
本质 将其它对象（形参列表）转换为类X的对象 将类X的对象转换为类Y的对象
其它 可以= default;声明；编译器会为一个类自动生成默认构造函数（若没有声明构造函数）

explicit作为修饰符应出现在函数名之前，形如explicit MyClass()、explicit operator bool()。

同为前缀修饰符，constexpr和explicit的顺序没有限制，但出于语义和可读性的考虑，笔者较倾向explicit在前的写法。

作用

被explicit修饰的构造函数和转换构造函数不能被隐式调用。
“隐式调用”的概念：C++中每次进行“类型转换”时（参考上述列表的“本质”一栏），编译器都会将之转化为对构造/转换构造函数的重载决议（若无法选择合适的函数，则将产生编译错误）。

即使是内置类型（或“平凡类型”，trivial-types），其截断、拓展等本质上也可以看作一种对相应函数调用的重载决议。

不能“隐式调用”的内涵可参见下述示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class X
{
public:
    explicit X(int){}

    operator int() const {return 1;}
};

X a = 1; //Error: no suitable constructor from `int` to `X`(marked as explicit, cannot be invoked implicitly)
X b{1}; //OK
X c = X{1}; //OK

int y = b; //Invokes `X::operator int() const` implicitly

class Y
{
public:
    explicit operator int() const {return 2;}
};

int z1 = Y{}; //Error: no suitable constructor from `Y` to `int`
int z2 = int(Y{}); //OK

在函数返回值的应用中也非常广泛，用于明确“是否真的需要转换”或“是否知晓正在转换”的语义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

X func1()
{
    return 1; //Error (`explicit` specifier for `X::X(int)`)
    return X{1}; //OK
}

int func2()
{
    Y y;
    //...

    return y; //Error (`explicit` specifier for `Y::operator int() const`)
    return int(y); //OK
}

不知各位有没有发现上述代码中，堪称“蝶影纷堕”的初始化方式：等号、大括号、小括号齐“上阵”，它们的作用时而无异，时而又大相径庭。显然又可以挖一个大坑——C++花样初始化的盘点，欢迎催更

特例

C++中有大量场景“需要”使用bool类型的变量。
为保证在这类场景（所谓 "type bool is expected"）中，相应向bool类型的转换能更加“流利”地进行，引出了C++中explicit的一个“特例”：
对于表达式e，只要bool t(e);语句是 良构(well-formed)（简单理解为可通过编译），则说明e可以在上下文中("contextually")隐式地被转化为bool，此时explicit operator bool亦会被考虑在内。

适用于这个“特例”的场景包括条件表达式（if/while/for）、逻辑运算符（||/&&/!/?:）、static_assert/noexcept/explicit的操作数。

总结来说，若一个类的对象可以被“有条件”地作为bool使用，则其可以选择声明一个explicit operator bool，或以operator int一类的其它非explicit转换函数占位。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class MyInt
{
public:
    constexpr operator int() const;
    //...
};

class expected
{
public:
    explicit constexpr operator bool() const;
    //...
};

int main()
{
    if(expected{}) //OK: contextually converted to bool
    if(MyInt{}) //OK: convertion sequence is MyInt -> int -> bool

    bool x = expected{}; //Error: operator bool is marked explicit
    bool x = !!expected{}; //OK: expected{} is contextually converted to bool through unary operator `!`
}

C++中，从一个类型向另一个类型的转换的“决策”为以下三步某种意义上是一个NFA（非确定有限自动机）：
先执行0/1次 标准转换顺序 (standard conversion sequence)，再进行一次 用户自定义的转换 (user-defined conversion)，最后再进行0/1次 标准转换顺序 （当且仅当用户自定义转换被调用时才可触发）。

其中“标准转换顺序”指“内置”的类型转换，如熟知的普通整型/浮点型互转（含截断）、整型/浮点型转bool（或反之）、指针转bool。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

struct X
{
    explicit operator bool() const
    {
        return true;
    }
};

struct Y
{
    operator int() const {return 1;}
};

struct Z
{
    explicit operator int() const {return 1;}
};

int main()
{
    if(X{}) //OK: explicit `operator bool` still works
    if(Y{}) //OK: conversion from Y to int, then to bool
    if(Z{}) //Error: conversion from Y to int is marked explicit
    if(int(Z{})) //OK
}

这对于许多希望只“有条件”地用于测试true/false的类型来说极为有用比如std::cin就有过这么一段黑历史：

1
2
3
4
5
6
int main()
{
    if(std::cin) //Normal usage on testing std::istream object's EOF, yet the type cast path is std::istream& -> void* -> bool
    
    delete std::cin; //This line compiles prior to C++11
}

是不是觉得后面一行莫名其妙？实际上是因为C++11前，没有explicit关键字导致std::istream使用了一个非常奇怪的workaround：

1
std::istream::operator void*() const;

其选择提供一个operator void*来规避bool赋值的问题，副作用就是让它变得“可删除了”乱删“野”指针，UB警告。C++11后（及其后新的相关类）均改用explicit operator bool。
同样“别扭”的还有使用private+不给定义来“封印”函数（C++11后用= delete一键解决）。

有关上述内容的“天书”般全解，可移步cppreference。

应用指北

显然任何需要“阻挡”无意间隐式转换场景中，explicit均可大展身手——其多用于需要保证类型安全时。

“联动”一个比较简单的例子：众所周知以下代码在java中不能通过编译

1
2
float x = 3.14; //Error: ...?
float y = (float)3.14; //OK

类似的“截断”在C/C++中常只以很容易被忽略/关闭的Warning的形式出现突击检查之谁在编译选项里加了-Wno-narrowing；尽管主流编译器都提供了将之视为Error的选项，但其只能覆盖基本类型转换的截断。

简单来说，explicit应用在构造函数中可以“防外”，转换构造函数则是“防内”。

explicit可以同时应用之于二者，亦可只应用于一端，创造更灵巧于enum class的类（enum class可视为向底层类型的构造函数和转换构造函数均为explicit的类）；甚至可以只阻隔一部分的构造函数，而允许另一部分通过，以更适配实际应用场景。

如，对于自定义的大整数类MyInt，即可存在以下几方面的考量：

  • MyInt可表示整数的取值范围是极广的，但int只限于 \(-2^{31} ~ 2^{31}-1\)，故从允许拓展而不允许截断的角度出发，构造函数不应声明为explicit；同时我们又希望保留这个转换构造的窗口（但需要调用者明示之，以确定其知会截断风险），则可以声明explicit的operator int() const；
  • 设计算术运算符重载时，我们希望只在MyInt的逻辑下进行（以保证设计语义一致并避免逻辑混乱、难以维护），故只会声明形如MyInt operator+(MyInt x,MyInt y);的重载，显然此时不应将构造函数声明为explicit否则将无法如此“丝滑”地调用。

二元算术运算符建议都声明为“传值进，传值出”：参见C++——右值引用与移动语义。
简而言之，其动机在于可以充分利用移动语义的优势，能在无需编写模板/大量重载的情况下最好地优化各种情况（临时对象，常对象，普通对象等）的空间应用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

class MyInt
{
public: 
    //...
    MyInt(int);

    //...
    explicit operator int() const;

    //...
};


int main()
{
    MyInt a{3},b{5};
    //...
    auto c = a*3;  //c is MyInt automatically,calls `MyInt::MyInt(int)` to construct a MyInt object in the process

    int x = c; //Error: `MyInt::operator int() const` is specified explicit
    
    std::cout << int(c) << std::endl; //OK
}

实例

以笔者的AES-Integrals为例。
为在密码学应用的代码维护中充分发挥Modern C++的优势，笔者选择了推翻既有的直接视unsigned char/uint8_t为 "Byte" 的做法，亦未使用C++17提供的enum class byte，而选择另起炉灶，自立一派——自定义struct byte（可见于aes.h中），封装unsigned char并定义相应的重载等，其中转换构造函数就利用了单向/部分explicit：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
using uc = unsigned char;

struct byte 
{
    explicit constexpr byte(unsigned char _val) : value{_val} {}
    constexpr byte() : byte(0) {}

    // Default special member functions
    constexpr byte(const byte&) = default;
    constexpr byte(byte&&) noexcept = default;
    constexpr byte& operator=(const byte&) = default;
    constexpr byte& operator=(byte&&) noexcept = default;
    constexpr ~byte() = default;

    // Conversion
    constexpr operator unsigned char() const noexcept { return value; }

    // Bitwise operators
    //...
};

此处笔者倾向于强调byte作为一个自定义类的特殊性，设置了较高的“准入门槛”，即用explicit修饰byte::byte(unsigned char)，以达成避免普通的字面量和struct byte混合位运算的语义混乱。结合自定义的字面量操作符operator""_t，效果形如：

1
2
3
4
5
6
//byte x = 3; //Not compile

byte x;
//byte z = x ^ 3; //Not Compile
byte z = x ^ 3_t; //OK

C++20：带条件的explicit

C++20中，explicit关键字变得更加灵活：声明时可以写出explicit(expr)，其中expr为bool类型的编译期常量（compile-time constant）。
当expr解析为true时，该函数视为被explicit修饰，否则视为未被explicit修饰。

相当于单纯的explicit等价于explicit(true)，参考noexcept和noexcept(expr)的用法间联系。

其作用亦和noexcept一类有相通之处，即用于模板编程中和requires和noexcept等一众神魔乱舞：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
template<class Ty>
class T
{
public:
    explicit(!requires{int x = std::declval<Ty>();}) operator int() const
    {
        return 1;
    }
};

int main()
{
    int a = T<int>{}; //OK, conversion ctor resolves to explicit(false)
    int b = T<std::string>{}; //Error: conversion ctor resolves to explicit(true)
}

什么？你还不知道requires？嘿嘿，又可以打广告啦：欢迎移步C++——concepts

结语

C++进化中许多语义检查的设计哲学之一，即为保证语义安全的“目标”同时，提供尽可能便捷的灵活性选项。explicit、= delete;、[[fallthrough]]、[[nodiscard]]等一众attributes即为其实例——所谓“有求者自取之”。

灵活应用explicit的目的同const、&&等所趋目标是一致的：作为镇寰宇玉门之守，不在最终生成的可执行代码中，而在保护这片代码不受有意无意的破坏侵蚀。

由于C/C++的类型转换同return、引用等一样是个极大的课题，加之笔者认识有限，上述内容或存诸多疏漏之处。如有出错，请见谅并欢迎指正之；亦可关注还在咕咕咕的C++——万类霜天竞自由

展开全文 >>

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true