Skip to content

Commit

Permalink
minor refactors + documentation improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@marzer
marzer committed Jul 31, 2023
1 parent bc8ab14 commit b6ae3f3
Show file tree
Hide file tree
Showing 20 changed files with 252 additions and 248 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Changelog

## v0.1.2

- Minor refactors.

## v0.1.1

- Minor refactors.
Expand Down
28 changes: 12 additions & 16 deletions docs/pages/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ you move on to read about **soagen**, here's some resources:

I'd to present my solution to the problems of working with Structure-of-Arrays in C++: **soagen**. Soagen is fundamentally two things:

1. [`soagen`], a command-line code utility for generating `std::vector`-like SoA containers, and
1. [`soagen`], a command-line code utility for generating bespoke `std::vector`-like SoA containers, and
2. [`soagen.hpp`], a single-header backing library upon which the generated code depends.

Typically you only need to use the command-line tool [`soagen`], and don't need to know anything about [`soagen.hpp`]
Expand Down Expand Up @@ -778,7 +778,7 @@ auto&& column_0 = r.column<0>(); // id
auto&& column_3 = r.column<3>(); // orient
```

Finally, now that we understand rows, I can reveal that you can _also_ use them with `push_back()` and `insert()`:
Finally, you can use them with `push_back()` and `insert()`:

```cpp
e.push_back(e[0]); // push a copy of row[0] onto the end of the table
Expand All @@ -793,7 +793,7 @@ e.push_back(e[0]); // push a copy of row[0] onto the end of the table

@section intro_equality Equality

If all the column types implement the named requirement <i>[EqualityComparable]</i> \(i.e. they have `operator==`\), then so too
If all the column types implement the named requirement EqualityComparable \(i.e. they have `operator==`\), then so too
do your tables:

```cpp
Expand Down Expand Up @@ -821,7 +821,7 @@ true
false
@eout

The same is true of rows; if all of the viewed members are <i>[EqualityComparable]</i>, then so too are the rows:
The same is true of rows; if all of the viewed members are EqualityComparable, then so too are the rows:

```
std::cout << (e1[0] == e2[0]) << "\n";
Expand All @@ -833,16 +833,16 @@ true
false
@eout

@note Rows do not have to have come from a table that is entirely <i>[EqualityComparable]</i>; it only depends on whether or not
@note Rows do not have to have come from a table that is entirely EqualityComparable; it only depends on whether or not
their viewed columns are. You can take a row view of only a few columns of a much larger table, and so long as the
viewed columns are <i>[EqualityComparable]</i>, so too is the resulting #soagen::row type.
viewed columns are EqualityComparable, so too is the resulting #soagen::row type.

<!-- --------------------------------------------------------------------------------------------------------------- -->

@section intro_comparison Comparison

Tables are comparable with operators `<`, `<=`, `>` and `>=` if all their column types implement the named
requirement <i>[LessThanComparable]</i> \(i.e. they have `operator<`\). Comparison is done row-wise, with row members
requirement LessThanComparable \(i.e. they have `operator<`\). Comparison is done row-wise, with row members
compared lexicographically:

```cpp
Expand Down Expand Up @@ -876,7 +876,7 @@ false
false
@eout

@note Just as with <i>[EqualityComparable]</i>, rows are <i>[LessThanComparable]</i> if their viewed members are, too.
@note Just as with EqualityComparable, rows are LessThanComparable if their viewed members are, too.
It does not depend on the source table.

<!-- --------------------------------------------------------------------------------------------------------------- -->
Expand Down Expand Up @@ -960,7 +960,7 @@ allocator = 'foo::fancy_allocator' # ...can also be overridden set per-struct

The only requirements of your allocator are:

- It must properly implement the named requirement <i>[Allocator]</i>, and
- It must properly implement the named requirement Allocator, and
- Have a `value_type` of `char`, `unsigned char` or `std::byte`.

@subsection intro_customizing_allocators Customizing allocators for soagen
Expand Down Expand Up @@ -1004,7 +1004,7 @@ Soagen will choose this overload over any others if it is present.
@section intro_access_underlying_buffer Accessing the underlying buffer

Soagen allocates one contiguous buffer for the entire table. If all the column types in your table are
<i>[TriviallyCopyable]</i> you'll be able to access the underlying buffer directly with `data()`, and determine it's size with
TriviallyCopyable you'll be able to access the underlying buffer directly with `data()`, and determine it's size with
`allocation_size()`, allowing you to serialize/deserialize it directly, stream it, hash it, et cetera.

@see <ul>
Expand Down Expand Up @@ -1033,7 +1033,7 @@ To use a #soagen::table directly, you need to express it terms of #soagen::table
using entities = soagen::table<soagen::table_traits<
soagen::column_traits<unsigned>,
soagen::column_traits<std::string>,
soagen::column_traits<vec3, soagen::param_type<vec3>, 32>,
soagen::column_traits<vec3, 32>,
soagen::column_traits<quaternion>
>>;

Expand Down Expand Up @@ -1077,7 +1077,7 @@ Thanks!
\[p\]
I'm <a href="https://github.com/marzer">Mark</a>. You might know me as the <a href="https://marzer.github.io/tomlplusplus/">toml++</a> guy.
I write code. Some of it is alright. Almost all of it is C++.
\[span class="socials"\]
\[span class="poxy-socials"\]
<a href="https://github.com/marzer">\[img src="poxy/poxy-icon-github.svg" class="poxy-icon"\]</a>
<a href="https://twitter.com/marzer8789">\[img src="poxy/poxy-icon-twitter.svg" class="poxy-icon"\]</a>
<a href="mailto:[email protected]">\[img src="poxy/poxy-icon-email.svg" class="poxy-icon"\]</a>
Expand All @@ -1097,8 +1097,4 @@ I write code. Some of it is alright. Almost all of it is C++.
[`unordered_erase()`]: classsoagen_1_1examples_1_1entities.html#a117807c0fbe9e2ed2fbe39c9193ff231
[`row()`]: classsoagen_1_1examples_1_1entities.html#ac24830714a0cf3a0f677b77936a79e73
[`aligned_stride`]: structsoagen_1_1table__traits.html#a7b18454ef28aa4279e1f1fc61bd15381
[Allocator]: https://en.cppreference.com/w/cpp/named_req/Allocator
[EqualityComparable]: https://en.cppreference.com/w/cpp/named_req/EqualityComparable
[LessThanComparable]: https://en.cppreference.com/w/cpp/named_req/LessThanComparable
[TriviallyCopyable]: https://en.cppreference.com/w/cpp/named_req/TriviallyCopyable
[roadmap]: https://github.com/marzer/soagen/issues/1
34 changes: 17 additions & 17 deletions examples/entities.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
// See https://github.com/marzer/soagen/blob/master/LICENSE for the full license text.
// SPDX-License-Identifier: MIT
//----------------------------------------------------------------------------------------------------------------------
// This file was generated by soagen v0.1.1 - do not modify it directly
// This file was generated by soagen v0.1.2 - do not modify it directly
// https://marzer.github.io/soagen
//----------------------------------------------------------------------------------------------------------------------
#pragma once
Expand Down Expand Up @@ -54,8 +54,8 @@ SOAGEN_DISABLE_SPAM_WARNINGS;
#ifndef SOAGEN_MAKE_NAME
#define SOAGEN_MAKE_NAME(...) static_assert(true)
#endif
#ifndef SOAGEN_MAKE_COL
#define SOAGEN_MAKE_COL(...) static_assert(true)
#ifndef SOAGEN_MAKE_COLUMN
#define SOAGEN_MAKE_COLUMN(...) static_assert(true)
#endif
#ifndef SOAGEN_NODISCARD
#define SOAGEN_NODISCARD
Expand Down Expand Up @@ -120,6 +120,8 @@ SOAGEN_DISABLE_SPAM_WARNINGS;

/// @cond

// clang-format off

namespace soagen::examples
{
class entities;
Expand All @@ -133,8 +135,6 @@ namespace soagen

namespace soagen::detail
{
// clang-format off

#ifndef SOAGEN_NAME_id
#define SOAGEN_NAME_id
SOAGEN_MAKE_NAME(id);
Expand All @@ -155,16 +155,14 @@ namespace soagen::detail
SOAGEN_MAKE_NAME(pos);
#endif

// clang-format on

template <>
struct table_traits_type_<soagen::examples::entities>
{
using type = table_traits<
/* id */ make_column<unsigned>,
/* name */ make_column<std::string>,
/* pos */ make_column<vec3, param_type<vec3>, 32>,
/* orient */ make_column<quaternion>>;
/* id */ column_traits<unsigned>,
/* name */ column_traits<std::string>,
/* pos */ column_traits<vec3, soagen::max(size_t{ 32 }, alignof(vec3))>,
/* orient */ column_traits<quaternion>>;
};

template <>
Expand All @@ -173,10 +171,10 @@ namespace soagen::detail
using type = soagen::allocator;
};

SOAGEN_MAKE_COL(soagen::examples::entities, 0, id);
SOAGEN_MAKE_COL(soagen::examples::entities, 1, name);
SOAGEN_MAKE_COL(soagen::examples::entities, 2, pos);
SOAGEN_MAKE_COL(soagen::examples::entities, 3, orient);
SOAGEN_MAKE_COLUMN(soagen::examples::entities, 0, id);
SOAGEN_MAKE_COLUMN(soagen::examples::entities, 1, name);
SOAGEN_MAKE_COLUMN(soagen::examples::entities, 2, pos);
SOAGEN_MAKE_COLUMN(soagen::examples::entities, 3, orient);

template <>
struct table_type_<soagen::examples::entities>
Expand All @@ -185,6 +183,8 @@ namespace soagen::detail
};
}

// clang-format on

/// @endcond

//----------------------------------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -286,9 +286,9 @@ namespace soagen::examples
};
#endif

/// @brief Gets the name of the specified column as a string.
/// @brief Gets the name of the specified column as a null-terminated string.
template <size_type Column>
static constexpr auto& column_name = soagen::detail::col_name_<entities, Column>::value;
static constexpr auto& column_name = soagen::detail::column_name_<entities, Column>::value;

private:
/// @cond
Expand Down
2 changes: 1 addition & 1 deletion examples/entities.natvis
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
// This file was generated by soagen v0.1.1 - do not modify it directly
// This file was generated by soagen v0.1.2 - do not modify it directly
// https://marzer.github.io/soagen
-->
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
Expand Down
70 changes: 35 additions & 35 deletions examples/shapes.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
// See https://github.com/marzer/soagen/blob/master/LICENSE for the full license text.
// SPDX-License-Identifier: MIT
//----------------------------------------------------------------------------------------------------------------------
// This file was generated by soagen v0.1.1 - do not modify it directly
// This file was generated by soagen v0.1.2 - do not modify it directly
// https://marzer.github.io/soagen
//----------------------------------------------------------------------------------------------------------------------
#pragma once
Expand Down Expand Up @@ -53,8 +53,8 @@ SOAGEN_DISABLE_SPAM_WARNINGS;
#ifndef SOAGEN_MAKE_NAME
#define SOAGEN_MAKE_NAME(...) static_assert(true)
#endif
#ifndef SOAGEN_MAKE_COL
#define SOAGEN_MAKE_COL(...) static_assert(true)
#ifndef SOAGEN_MAKE_COLUMN
#define SOAGEN_MAKE_COLUMN(...) static_assert(true)
#endif
#ifndef SOAGEN_NODISCARD
#define SOAGEN_NODISCARD
Expand Down Expand Up @@ -119,6 +119,8 @@ SOAGEN_DISABLE_SPAM_WARNINGS;

/// @cond

// clang-format off

namespace soagen::examples
{
class boxes;
Expand All @@ -136,8 +138,6 @@ namespace soagen

namespace soagen::detail
{
// clang-format off

#ifndef SOAGEN_NAME_center_x
#define SOAGEN_NAME_center_x
SOAGEN_MAKE_NAME(center_x);
Expand Down Expand Up @@ -178,19 +178,17 @@ namespace soagen::detail
SOAGEN_MAKE_NAME(radius);
#endif

// clang-format on

template <>
struct table_traits_type_<soagen::examples::boxes>
{
using type = table_traits<
/* center_x */ make_column<float, param_type<float>, 32>,
/* center_y */ make_column<float, param_type<float>, 32>,
/* center_z */ make_column<float, param_type<float>, 32>,
/* extents_x */ make_column<float, param_type<float>, 32>,
/* extents_y */ make_column<float, param_type<float>, 32>,
/* extents_z */ make_column<float, param_type<float>, 32>,
/* mass */ make_column<float>>;
/* center_x */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* center_y */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* center_z */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* extents_x */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* extents_y */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* extents_z */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* mass */ column_traits<float>>;
};

template <>
Expand All @@ -199,13 +197,13 @@ namespace soagen::detail
using type = soagen::allocator;
};

SOAGEN_MAKE_COL(soagen::examples::boxes, 0, center_x);
SOAGEN_MAKE_COL(soagen::examples::boxes, 1, center_y);
SOAGEN_MAKE_COL(soagen::examples::boxes, 2, center_z);
SOAGEN_MAKE_COL(soagen::examples::boxes, 3, extents_x);
SOAGEN_MAKE_COL(soagen::examples::boxes, 4, extents_y);
SOAGEN_MAKE_COL(soagen::examples::boxes, 5, extents_z);
SOAGEN_MAKE_COL(soagen::examples::boxes, 6, mass);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 0, center_x);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 1, center_y);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 2, center_z);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 3, extents_x);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 4, extents_y);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 5, extents_z);
SOAGEN_MAKE_COLUMN(soagen::examples::boxes, 6, mass);

template <>
struct table_type_<soagen::examples::boxes>
Expand All @@ -217,11 +215,11 @@ namespace soagen::detail
struct table_traits_type_<soagen::examples::spheres>
{
using type = table_traits<
/* center_x */ make_column<float, param_type<float>, 32>,
/* center_y */ make_column<float, param_type<float>, 32>,
/* center_z */ make_column<float, param_type<float>, 32>,
/* radius */ make_column<float, param_type<float>, 32>,
/* mass */ make_column<float>>;
/* center_x */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* center_y */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* center_z */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* radius */ column_traits<float, soagen::max(size_t{ 32 }, alignof(float))>,
/* mass */ column_traits<float>>;
};

template <>
Expand All @@ -230,11 +228,11 @@ namespace soagen::detail
using type = soagen::allocator;
};

SOAGEN_MAKE_COL(soagen::examples::spheres, 0, center_x);
SOAGEN_MAKE_COL(soagen::examples::spheres, 1, center_y);
SOAGEN_MAKE_COL(soagen::examples::spheres, 2, center_z);
SOAGEN_MAKE_COL(soagen::examples::spheres, 3, radius);
SOAGEN_MAKE_COL(soagen::examples::spheres, 4, mass);
SOAGEN_MAKE_COLUMN(soagen::examples::spheres, 0, center_x);
SOAGEN_MAKE_COLUMN(soagen::examples::spheres, 1, center_y);
SOAGEN_MAKE_COLUMN(soagen::examples::spheres, 2, center_z);
SOAGEN_MAKE_COLUMN(soagen::examples::spheres, 3, radius);
SOAGEN_MAKE_COLUMN(soagen::examples::spheres, 4, mass);

template <>
struct table_type_<soagen::examples::spheres>
Expand All @@ -243,6 +241,8 @@ namespace soagen::detail
};
}

// clang-format on

/// @endcond

//----------------------------------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -361,9 +361,9 @@ namespace soagen::examples
};
#endif

/// @brief Gets the name of the specified column as a string.
/// @brief Gets the name of the specified column as a null-terminated string.
template <size_type Column>
static constexpr auto& column_name = soagen::detail::col_name_<boxes, Column>::value;
static constexpr auto& column_name = soagen::detail::column_name_<boxes, Column>::value;

static constexpr float default_mass = 2.0;

Expand Down Expand Up @@ -1703,9 +1703,9 @@ namespace soagen::examples
};
#endif

/// @brief Gets the name of the specified column as a string.
/// @brief Gets the name of the specified column as a null-terminated string.
template <size_type Column>
static constexpr auto& column_name = soagen::detail::col_name_<spheres, Column>::value;
static constexpr auto& column_name = soagen::detail::column_name_<spheres, Column>::value;

static constexpr float default_mass = 1.0;

Expand Down
2 changes: 1 addition & 1 deletion examples/shapes.natvis
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
// This file was generated by soagen v0.1.1 - do not modify it directly
// This file was generated by soagen v0.1.2 - do not modify it directly
// https://marzer.github.io/soagen
-->
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
Expand Down
Loading

0 comments on commit b6ae3f3

Please sign in to comment.