incorrect documentation and additional suggestions

[Fytch]

Hello

I want to migrate from another SIMD library to libsimdpp but the quality of documentation makes it very cumbersome, unfortunately. A few examples:

• Equivalent operation involves &, shouldn't it be | instead?
• Title says insert, signature says extract
• Title says bit_cast, signature says for_each

(there are more but I couldn't recall them, sorry)

Some additional points:

• Why are there no fill constructors for vectors? You have to use make_... which is very cumbersome in generic code (for instance, I want to fill a vector of type T with 1, no matter whether it is float64 or int32, which is not possible without a workaround)
• There are load and store functions for aligned memory locations but why are there no helper functions for unaligned memory? Right now, I have to use a hack involving recursive template functions, which could have easily been part of the library. I know that broadcasting unaligned memory to SIMD registers may have some overhead but it's a common operation nonetheless.
• Why do insert and extract require compile-time indices? Wouldn't it be possible to provide additional overloads for runtime indices?
• for_each accepts a const-ref to a function. Why? You should pass it by value so that the functor may have a state. All functions within the STL pass functors and comparators by value, by the way.
• for_each works on const-ref vectors. How about a non-const version à la std::transform?

[p12tic]

Thanks for the bug report!

Equivalent operation involves &, shouldn't it be | instead?

Fixed in e9311e718cf8c4a190e7fdd4b2ddd3b882ee48bb.

Title says insert, signature says extract

Fixed in 87346665f251e06b6ab2d95ab98f4f00522062fe.

Title says bit_cast, signature says for_each

Fixed in fadf2f7b02e10bd5b56a0fe0b3e2c4d39796f68f

Why are there no fill constructors for vectors? You have to use make_... which is very cumbersome in generic code (for instance, I want to fill a vector of type T with 1, no matter whether it is float64 or int32, which is not possible without a workaround)

Valid criticism. I've opened https://github.com/p12tic/libsimdpp/issues/110.

There are load and store functions for aligned memory locations but why are there no helper functions for unaligned memory? Right now, I have to use a hack involving recursive template functions, which could have easily been part of the library. I know that broadcasting unaligned memory to SIMD registers may have some overhead but it's a common operation nonetheless.

Doesn't either load_splat or load_u work for you? Perhaps I'm misunderstanding something?

Why do insert and extract require compile-time indices? Wouldn't it be possible to provide additional overloads for runtime indices?

Mostly because I've not found need for this yet and it's likely that this operation is very slow on at least some architectures (e.g. SSE3), though I haven't looked into this in depth. I've opened https://github.com/p12tic/libsimdpp/issues/109.

for_each accepts a const-ref to a function. Why? You should pass it by value so that the functor may have a state. All functions within the STL pass functors and comparators by value, by the way.

That's bug in documentation, sorry. Fixed in fadf2f7b02e10bd5b56a0fe0b3e2c4d39796f68f.

for_each works on const-ref vectors. How about a non-const version à la std::transform

Isn't this the same as https://github.com/p12tic/libsimdpp/issues/107? I think it makes sense to have this for sure.