Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README #501

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Improve README #501

wants to merge 2 commits into from

Conversation

AlexMaryW
Copy link
Contributor

Issue: #443

Hi, I had a go at improving the README. Do let me know what you think. Thanks! :)

Copy link
Contributor

@Shimuuar Shimuuar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

After many years of waiting someone improved rather anemic readme. I added suggestions which basically rewrote description of vectors.

And sorry for the wait.

vector/README.md Outdated
- [Vectors Available in the Package](#vectors-available-in-the-package)
- [Fusion](#fusion)

## Installation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need Installation section? There's nothing nonstandard it works like any other package

vector/README.md Outdated
Comment on lines 85 to 89
An optimisation framework provided in this package, fusion
is a technique that merges several functions into one and forces
it to produce only one outcome. Without fusion, your program might
generate intermediate results for each function separately and
stall its performance.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Specifically stream fusion as opposed to build/foldr fusion used for lists.

Suggested change
An optimisation framework provided in this package, fusion
is a technique that merges several functions into one and forces
it to produce only one outcome. Without fusion, your program might
generate intermediate results for each function separately and
stall its performance.
Vector uses stream fusion for optimizations. This is technique
allows to avoid creation of intermediate data structures. For example
following expression `sum . filter g . map f` will not allocate temporary vectors
if compiled with optimizations.

vector/README.md Outdated
Comment on lines 64 to 66
**Boxed vectors** store each of its elements as a pointer to its value.
Because we cannot directly access the contents of a boxed vector, they
are slower in comparison to unboxed vectors.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Boxed vectors** store each of its elements as a pointer to its value.
Because we cannot directly access the contents of a boxed vector, they
are slower in comparison to unboxed vectors.
**Lazy boxed vectors** (`Data.Vector`) can store any haskell value. Their elements are
stored as pointers to heap-allocated values and that extra indirection results in worse
performance.
**Strict boxed vectors** (`Data.Vector.Strict`) boxed vector which is strict in its elements.

vector/README.md Outdated
Comment on lines 78 to 81
**Primitive vectors** contain elements of primitive type.
Primitive types can be recognised by the hash sign attached at
the end of value and/or type’s name, e.g. `3#` or `Int#`. You can read
more about them [here](https://downloads.haskell.org/~ghc/5.00/docs/set/primitives.html).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's more precise to say that they can hold values that are instances of Prim. In fact it can't hold Int# — wrong kind.

Suggested change
**Primitive vectors** contain elements of primitive type.
Primitive types can be recognised by the hash sign attached at
the end of value and/or type’s name, e.g. `3#` or `Int#`. You can read
more about them [here](https://downloads.haskell.org/~ghc/5.00/docs/set/primitives.html).
**Primitive vectors** (`Data.Vector.Primitive`). This vector is backed by simple
byte array and can hold data types which are instances of `Prim` type class.
This is data types which are represented in memory as sequence of bytes without
pointer. Think `Int`, `Double`, etc. Usually it's better to use unboxed vectors since
they have same performance and more general.

vector/README.md Outdated
Comment on lines 69 to 71
**Unboxed vectors** store solely their elements’ values instead of pointers.
To be unboxed, the elements need to be constant in size. Since we can directly
access the contents of the unboxed vector, working with them is quite efficient.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case name lies.

Suggested change
**Unboxed vectors** store solely their elements’ values instead of pointers.
To be unboxed, the elements need to be constant in size. Since we can directly
access the contents of the unboxed vector, working with them is quite efficient.
**Unboxed vectors** (`Data.Vector.Unboxed`) is vector which determines representation
of an array from type of its element. For primitives (`Int`, `Double`, etc) it's backed by primitive
arrays and for tuples and product types by structure of arrays. Generally it uses unboxed
representation so it's quite efficient

vector/README.md Outdated
Comment on lines 74 to 75
**Storable vectors** are pinned, convertible to and from pointers, and
usable in C functions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Storable vectors** are pinned, convertible to and from pointers, and
usable in C functions.
**Storable vectors** (`Data.Vector.Storable`) are backed by pinned memory. Their primary
use case is C FFI.

@AlexMaryW
Copy link
Contributor Author

Thanks for all the suggestions and no worries about the wait! I'll have some time tomorrow to go through your comments and make the necessary changes.

@AlexMaryW
Copy link
Contributor Author

I read through and adapted your suggestions into the README + deleted the installation section.

Copy link
Contributor

@Shimuuar Shimuuar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I finally got review README again. Few more comments

@lehins @Bodigrim do you any input? After this PR is merged I want to start preparing long overdue 0.13.2.0 release

Comment on lines +4 to +11
This package includes various modules that will allow you to
work with vectors and use an optimisation framework called [*fusion*](#fusion).
In this context, vector is an `Int`-indexed array-like data structure with a simpler
API that can contain any Haskell value. Additionally, its equivalence
to C-style arrays and optimisation via fusion accelerates vector’s
performance and makes it a great alternative to list. By installing this
package, you’ll be able to work with [boxed, unboxed, storable, and primitive
vectors](#vectors-available-in-the-package) as well as their generic interface.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This package includes various modules that will allow you to
work with vectors and use an optimisation framework called [*fusion*](#fusion).
In this context, vector is an `Int`-indexed array-like data structure with a simpler
API that can contain any Haskell value. Additionally, its equivalence
to C-style arrays and optimisation via fusion accelerates vector’s
performance and makes it a great alternative to list. By installing this
package, you’ll be able to work with [boxed, unboxed, storable, and primitive
vectors](#vectors-available-in-the-package) as well as their generic interface.
An efficient implementation of `Int`-indexed arrays (both mutable and immutable).
This package provides multiple representations: [boxed, unboxed, storable, and primitive
vectors](#vectors-available-in-the-package) and generic API which is polymorphic in
vector type. It also has powerful optimization framework based on [stream-fusion](#fusion)
which could eliminate intermediate data structures.

I think it would be better to cut down this paragraph a bit.

the tutorial on [Haskell Wiki](https://wiki.haskell.org/Numeric_Haskell:_A_Vector_Tutorial)
covers more ground.

## Vector vs Array
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we even need to compare with array. I think at this point it's mostly legacy and barely used

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants