Attribute Macro utf_table 

#[utf_table]

Macro for arranging a table and implementing useful Table behavior

General Output Structure

This attribute macro accepts a struct definition, and outputs one or more new struct definitions, along with an implementation of the Table trait.

For example, if the struct is named ImportantTable. The final struct definition may look something like this:

struct ImportantTable {
    constants: ImportantTableConstants,
    rows: Vec<ImportantTableRow>,
    write_context: criware_utf::WriteContext
}

The macro would also define ImportantTableConstants and ImportantTableRow as part of its output, containing the constant or row fields respectively. They are only defined when they are needed.

• If there are no constant columns, ImportantTableConstants and the constants field are not included
• If there are no rowed columns, ImportantTableRow and the rows field are not included
• If there are no optional rowed columns, the write_context field is not included

Input/Output Examples

// Input
#[utf_table]
struct NuTable {
    id: i64,
    blob: Vec<u8>,
    #[constant]
    comment: String
}

// Output
struct NuTableConstants {
    comment: String
}
struct NuTableRow {
    id: i64,
    blob: Vec<u8>
}
struct NuTable {
    constants: NuTableConstants,
    rows: Vec<NuTableRow>
}
impl Table for NuTable {/** ... */}

// Input
#[utf_table(constants = FileTableInfo, row = File)]
struct FileTable {
    id: u64,
    name: String,
    #[column_name = "Crc"]
    #[optional]
    crc32: u32
    #[constant]
    version: String
    #[constant]
    #[optional]
    table_metadata: Vec<u8>
}

// Output
struct FileTableInfo {
    version: String,
    table_metadata: Option<Vec<u8>>
}
struct File {
    id: u64,
    name: String,
    crc32: Option<u32>
}
struct FileTable {
    constants: FileTableInfo,
    rows: Vec<File>,
    write_context: WriteContext
}
impl Table for FileTable {/** ... */}

Attribute Options

This section outlines the optional configuration options that can be included with the #[utf_table] attribute.

These options can be chained together by separating them with a comma. Specifying any of these options multiple times will cause a compile error.

#[utf_table(table_name = "TABLE", constants = TableStuff)]

table_name

By default, the macro assumes the name of the table is the name of the struct. This can be overwritten by specifying a string literal. The generated read procedure will check that the name of the table matches, so specifying this is important.

#[utf_table(table_name = "ActualTableName")]

constants

If a constant struct is generated, by default its name will be the name of the input struct + “Constants”. This name can be overwritten by specifying a type name. If there is no constant struct generated, this option does nothing.

#[utf_table(constants = TConsts)]

row

If a row struct is generated, by default its name will be the name of the input struct + “Row”. This name can be overwritten by specifying a type name. If there is no row struct generated, this option does nothing.

#[utf_table(row = TRow)]

Field Options

This section outlines the optional configuration options for each field within the input struct.

Multiple may be used on the same field, but duplicate or conflicting options will result in a compile error.

#[optional]
#[constant]
some_value: i64

#[column_name = "{name}"]

By default, the in-table column name associated with a field is an upper camel case conversion of the field name (e.g. “some_column” => “SomeColumn”). This can be overwritten by passing a string literal.

#[column_name = "TheActualColumnName"]
some_value: i64

#[constant]

By default, columns are rowed. This marks the column as constant instead.

If this is used in the presence of #[rowed], there will be a compile error.

#[constant]
some_value: i64

#[rowed]

Since columns are rowed by default, using this attribute is superfluous. Nevertheless, this can be manually specified if it helps make the form of each column clear.

If this is used in the presence of #[constant], there will be a compile error.

#[rowed]
some_value: i64

#[optional]

This marks a column as optional.

In the constant or row struct output, the field will have type Option<T> instead of T (where T is the original type specified in the struct definition). In the table read procedure, the column storage method may be zero or constant/rowed (depending on whether the column is marked as constant or rowed).

In the table write procedure, the storage method that is used for the column is dependent on the column’s associated value(s). If the values are all None, the storage method will be zero. If the values are all Some, the storage method will be constant/rowed. There cannot be a mix of Some and None. If there is, the write procedure will error out.

Furthermore, if the column is rowed and there are no rows, the storage method will depend on other factors.

If the table was read, it will simply copy the storage method it was originally read as.

If the table is created from scratch, the storage method will default to zero. This behavior can be overwritten with configuration options on the #[optional] attribute.

#[optional(include)]

This will make the column constant/rowed instead of zero

#[optional(exclude)]

This does nothing, but can make the write procedure’s behavior more clear to readers.