From b76c24a4d1588412a01baf444a1ba54b7ae40ee8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= Date: Tue, 22 Mar 2022 09:08:22 +0100 Subject: [PATCH 1/5] Add examples in README.md --- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5c88703..a3da5bf 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,54 @@ A pooled representation of arrays for purposes of compression when there are few unique elements. - **Installation**: at the Julia REPL, `import Pkg; Pkg.add("PooledArrays")` +**Usage**: + +Working with `PooledArray` objects does not differ from working with general `AbstractArray` objects, with two exceptions: +* If you hold mutable objects in PooledArray it is not allowed to modify them after they are stored in it. +* In multi-threaded context it is not safe to assign values that are not already present in a `PooledArray`'s pool + from one thread while either reading or writing to the same array from another thread. + +Keeping in mind these two restrictions, as a user, the only thing you need to learn is how to create `PooledArray` objects. +This is accomplished by passing an `AbstractArray` to the `PooledArray` constructor: + +``` +julia> using PooledArrays + +julia> PooledArray(["a" "b"; "c" "d"]) +2×2 PooledMatrix{String, UInt32, Matrix{UInt32}}: + "a" "b" + "c" "d" + ``` + +`PooledArray` performs compression by storing an array of reference integers and a mapping from integers to its elements in a dictionary. +In this way, if the size of the reference integer is smaller than the size of the actual elements the resulting object has a smaller memory footprint. +By default `UInt32` is used as a type of reference integers. However, you can specify the reference integer type you want to use by passing it +as a second argument to the constructor. This is usually done when you know that you will have only a few unique elements in the `PooledArray`. + +``` +julia> PooledArray(["a", "b", "c", "d"], UInt8) +4-element PooledVector{String, UInt8, Vector{UInt8}}: + "a" + "b" + "c" + "d" + ``` + +Alternatively you can pass the `compress` and `signed` keyword arguments to the `PooledArray` constructor to automatically select the reference integer type. +When you pass `compress=true` then reference integer type is chosen to be the smallest type that is large enough to hold all unique values in array. +When you pass `signed=true` the reference type is signed (by default it is unsigned). + +``` +julia> PooledArray(["a", "b", "c", "d"]; compress=true, signed=true) +4-element PooledVector{String, Int8, Vector{Int8}}: + "a" + "b" + "c" + "d" +``` + **Maintenance**: PooledArrays is maintained collectively by the [JuliaData collaborators](https://github.com/orgs/JuliaData/people). Responsiveness to pull requests and issues can vary, depending on the availability of key collaborators. From d123125a9c8dd80fb295d1fff6ef56beeb20edc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= Date: Sat, 26 Mar 2022 17:49:25 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Milan Bouchet-Valat --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a3da5bf..6ada3f5 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ julia> PooledArray(["a" "b"; "c" "d"]) ``` `PooledArray` performs compression by storing an array of reference integers and a mapping from integers to its elements in a dictionary. -In this way, if the size of the reference integer is smaller than the size of the actual elements the resulting object has a smaller memory footprint. +In this way, if the size of the reference integer is smaller than the size of the actual elements the resulting `PooledArray` has a smaller memory footprint than the equivalent `Array`. By default `UInt32` is used as a type of reference integers. However, you can specify the reference integer type you want to use by passing it as a second argument to the constructor. This is usually done when you know that you will have only a few unique elements in the `PooledArray`. @@ -45,7 +45,7 @@ julia> PooledArray(["a", "b", "c", "d"], UInt8) ``` Alternatively you can pass the `compress` and `signed` keyword arguments to the `PooledArray` constructor to automatically select the reference integer type. -When you pass `compress=true` then reference integer type is chosen to be the smallest type that is large enough to hold all unique values in array. +When you pass `compress=true` then the reference integer type is chosen to be the smallest type that is large enough to hold all unique values in array. When you pass `signed=true` the reference type is signed (by default it is unsigned). ``` From f8262f63eda2df1c7e05c6f182c15ca92680aac8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= Date: Sat, 26 Mar 2022 17:50:49 +0100 Subject: [PATCH 3/5] Update README.md --- README.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6ada3f5..97e2d61 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,14 @@ julia> PooledArray(["a" "b"; "c" "d"]) "c" "d" ``` -`PooledArray` performs compression by storing an array of reference integers and a mapping from integers to its elements in a dictionary. -In this way, if the size of the reference integer is smaller than the size of the actual elements the resulting `PooledArray` has a smaller memory footprint than the equivalent `Array`. -By default `UInt32` is used as a type of reference integers. However, you can specify the reference integer type you want to use by passing it -as a second argument to the constructor. This is usually done when you know that you will have only a few unique elements in the `PooledArray`. +`PooledArray` performs compression by storing an array of reference integers and +a mapping from integers to its elements in a dictionary. In this way, if the +size of the reference integer is smaller than the size of the actual elements +the resulting `PooledArray` has a smaller memory footprint than the equivalent +`Array`. By default `UInt32` is used as a type of reference integers. However, +you can specify the reference integer type you want to use by passing it as a +second argument to the constructor. This is usually done when you know that you +will have only a few unique elements in the `PooledArray`. ``` julia> PooledArray(["a", "b", "c", "d"], UInt8) @@ -44,10 +48,11 @@ julia> PooledArray(["a", "b", "c", "d"], UInt8) "d" ``` -Alternatively you can pass the `compress` and `signed` keyword arguments to the `PooledArray` constructor to automatically select the reference integer type. -When you pass `compress=true` then the reference integer type is chosen to be the smallest type that is large enough to hold all unique values in array. -When you pass `signed=true` the reference type is signed (by default it is unsigned). - +Alternatively you can pass the `compress` and `signed` keyword arguments to the +`PooledArray` constructor to automatically select the reference integer type. +When you pass `compress=true` then the reference integer type is chosen to be +the smallest type that is large enough to hold all unique values in array. When +you pass `signed=true` the reference type is signed (by default it is unsigned). ``` julia> PooledArray(["a", "b", "c", "d"]; compress=true, signed=true) 4-element PooledVector{String, Int8, Vector{Int8}}: @@ -57,7 +62,8 @@ julia> PooledArray(["a", "b", "c", "d"]; compress=true, signed=true) "d" ``` -**Maintenance**: PooledArrays is maintained collectively by the [JuliaData collaborators](https://github.com/orgs/JuliaData/people). +**Maintenance**: PooledArrays is maintained collectively by the +[JuliaData collaborators](https://github.com/orgs/JuliaData/people). Responsiveness to pull requests and issues can vary, depending on the availability of key collaborators. ## Related Packages From 639b54fc352de92960841704b658c3c3503e0d26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= Date: Sat, 26 Mar 2022 17:51:57 +0100 Subject: [PATCH 4/5] Update README.md --- README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 97e2d61..f6b134d 100644 --- a/README.md +++ b/README.md @@ -13,13 +13,17 @@ A pooled representation of arrays for purposes of compression when there are few **Usage**: -Working with `PooledArray` objects does not differ from working with general `AbstractArray` objects, with two exceptions: -* If you hold mutable objects in PooledArray it is not allowed to modify them after they are stored in it. -* In multi-threaded context it is not safe to assign values that are not already present in a `PooledArray`'s pool - from one thread while either reading or writing to the same array from another thread. +Working with `PooledArray` objects does not differ from working with general +`AbstractArray` objects, with two exceptions: +* If you hold mutable objects in PooledArray it is not allowed to modify them + after they are stored in it. +* In multi-threaded context it is not safe to assign values that are not already + present in a `PooledArray`'s pool from one thread while either reading or + writing to the same array from another thread. -Keeping in mind these two restrictions, as a user, the only thing you need to learn is how to create `PooledArray` objects. -This is accomplished by passing an `AbstractArray` to the `PooledArray` constructor: +Keeping in mind these two restrictions, as a user, the only thing you need to +learn is how to create `PooledArray` objects. This is accomplished by passing +an `AbstractArray` to the `PooledArray` constructor: ``` julia> using PooledArrays @@ -64,7 +68,8 @@ julia> PooledArray(["a", "b", "c", "d"]; compress=true, signed=true) **Maintenance**: PooledArrays is maintained collectively by the [JuliaData collaborators](https://github.com/orgs/JuliaData/people). -Responsiveness to pull requests and issues can vary, depending on the availability of key collaborators. +Responsiveness to pull requests and issues can vary, +depending on the availability of key collaborators. ## Related Packages From 0af16b23e4b8420653fabdb8f8ec495ac8d1ef2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= Date: Sat, 26 Mar 2022 17:56:13 +0100 Subject: [PATCH 5/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f6b134d..df6e2c8 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ A pooled representation of arrays for purposes of compression when there are few Working with `PooledArray` objects does not differ from working with general `AbstractArray` objects, with two exceptions: -* If you hold mutable objects in PooledArray it is not allowed to modify them +* If you hold mutable objects in `PooledArray` it is not allowed to modify them after they are stored in it. * In multi-threaded context it is not safe to assign values that are not already present in a `PooledArray`'s pool from one thread while either reading or