Skip to content

Commit

Permalink
Fix spaces in doc.
Browse files Browse the repository at this point in the history
  • Loading branch information
emmt committed May 25, 2023
1 parent 45e8707 commit 8f7dad8
Show file tree
Hide file tree
Showing 6 changed files with 69 additions and 67 deletions.
8 changes: 4 additions & 4 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@

- New aliases `ArrayAxis` to `AbstractUnitRange{Int}` and `MaybeArrayAxis` to
`AbstractUnitRange{Integer}` to represent an argument that is a valid array
axis or eligible to be an array axis. Similarly `ArrayAxes` and
axis or eligible to be an array axis. Similarly `ArrayAxes` and
`MaybeArrayAxes` are aliases to tuples of `ArrayAxis` and `MaybeArrayAxis` to
represent an argument that is a valid tuple of array axes or eligible to be a
tuple of array axes. New methods `to_axis` and `to_axes` are provided to
tuple of array axes. New methods `to_axis` and `to_axes` are provided to
respectively convert their argument(s) to instances of `ArrayAxis` and
`ArrayAxes`.

Expand All @@ -37,7 +37,7 @@
## Version 0.2.1

- `isfastarray` and `isflatarray` deprecated in favor of `is_fast_array` and
`is_flat_array` which are more readable and thus less confusing. `fastarray`
`is_flat_array` which are more readable and thus less confusing. `fastarray`
and `flatarray` deprecated in favor of `to_fast_array` and `to_flat_array`
which are more clear about their purpose.

Expand All @@ -53,7 +53,7 @@

- `dimensions(A::AbstractArray)` has been deprecated in favor of
`standard_size(A)` while `dimensions` has been deprecated in favor of
`to_size` for other types of arguments. Union `Dimensions` has been
`to_size` for other types of arguments. Union `Dimensions` has been
deprecated favor of `ArraySize`.

- New method `to_int` for quick conversion of values to `Int`.
Expand Down
86 changes: 43 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ These are useful to implement methods to process arrays in a generic way.
## Rubber indices

The constants `..` and `` (type `\dots` and hit the `tab` key) can be used in
array indexation to left or right justify the other indices. For instance,
array indexation to left or right justify the other indices. For instance,
assuming `A` is a `3×4×5×6` array, then all the following equalities hold:

```julia
Expand All @@ -31,10 +31,10 @@ A[2:3,..,1,2:4] == A[2:3,:,1,2:4]

As can be seen, the advantage of the *rubber index* `..` is that it
automatically expands as the list of colons needed to have the correct number
of indices. The expressions are also more readable. The idea comes from the
of indices. The expressions are also more readable. The idea comes from the
[`Yorick`](http://github.com/LLNL/yorick/) language by Dave Munro.

The rubber index may also be used for setting values. For instance:
The rubber index may also be used for setting values. For instance:

```julia
A[..] .= 1 # to fill A with ones
Expand All @@ -47,17 +47,17 @@ A[..,2:4,5] .= 7 # to set all elements in A[:,:,2:4,5] to 7
Leading/trailing indices may also be specified as Cartesian indices (of type
`CartesianIndex`).

Technically, the constant `..` is defined as `RubberIndex()` where `RubberIndex`
is the singleton type that represents any number of indices.
Technically, the constant `..` is defined as `RubberIndex()` where
`RubberIndex` is the singleton type that represents any number of indices.

Call `colons(n)` if you need a `n`-tuple of colons `:`. When `n` is known at
Call `colons(n)` if you need a `n`-tuple of colons `:`. When `n` is known at
compile time, it is faster to call `colons(Val(n))`.

:warning: **Warning.** A current limitation of the rubber index is that it will
confuse the interpretation of the `end` token appearing in the same index list
*after* the rubber index. This is beacuse the parser wrongly assumes that the
rubber index counts for a single dimension. The `end` token may however
appears *before* the rubber index. Example:
*after* the rubber index. This is beacuse the parser wrongly assumes that the
rubber index counts for a single dimension. The `end` token may however appears
*before* the rubber index. Example:

```.julia
A = rand(5,10,4,3);
Expand All @@ -72,7 +72,7 @@ A[..,5:end,:] == A[:,:,5:end,:] # throws a BoundsError

Julia array interface is very powerful and flexible, it is therefore tempting
to define custom array-like types, that is Julia types that behave like arrays,
without sacrificing efficiency. The `ArrayTools` package provides simple means
without sacrificing efficiency. The `ArrayTools` package provides simple means
to define such array-like types if the values to be accessed as if in an array
are stored in an array (of any concrete type) embedded in the object instance.

Expand Down Expand Up @@ -101,18 +101,18 @@ end

As a result, instances of your `CustomArray{T,N}` will be also seen as
instances of `AbstractArray{T,N}` and will behave as if they implement linear
indexing. Apart from the needs to extend the `Base.parent` method, the
indexing. Apart from the needs to extend the `Base.parent` method, the
interface to `LinearArray{T,N}` should provide any necessary methods for
indexation, getting the dimensions, the element type, *etc.* for the derived
custom type. You may however override these definitions by more optimized or
custom type. You may however override these definitions by more optimized or
more suitable methods specialized for your custom array-like type.

If your custom array-like type is based on an array whose index style is
`IndexCartesian()` (instead of `IndexLinear()` in the above example), just make
your custom type derived from `CartesianArray{T,N}` (instead of
`LinearArray{T,N}`). For such array-like object, index checking requires an
`LinearArray{T,N}`). For such array-like object, index checking requires an
efficient implementation of the `Base.axes()` method which you may have to
specialize. The default implementation is:
specialize. The default implementation is:

```julia
@inline Base.axes(A::CartesianArray) = axes(parent(A))
Expand Down Expand Up @@ -140,11 +140,11 @@ B = AnnotatedArray{T}(undef, dims, units = "µm", Δx = 0.10, Δy = 0.20)

Here the initial properties of `A` and `B` are specified by the keywords in the
call to the constructor; their properties will have symbolic names with any
kind of value. The array contents of `A` is an array of zeros, while the array
contents of `B` is created by the constructor with undefined values. Indexing
kind of value. The array contents of `A` is an array of zeros, while the array
contents of `B` is created by the constructor with undefined values. Indexing
`A` or `B` with integers of Cartesian indices is the same as accessing the
values of their array contents while indexing `A` or `B` by symbols is the same
as accessing their properties. For example:
as accessing their properties. For example:

```julia
A.Δx # yields 0.2
Expand All @@ -169,14 +169,14 @@ B = AnnotatedArray{T}(init, dims, prop)
where `arr` is an existing array or an expression whose result is an array,
`prop` specifies the initial properties (more on this below), `T` is the type
of array element, `init` is usually `undef` and `dims` is a tuple of array
dimensions. If `arr` is an existing array, the object `A` created above will
dimensions. If `arr` is an existing array, the object `A` created above will
reference this array and hence share its contents with the caller (call
`copy(arr)` to avoid that). The same applies if the initial properties are
`copy(arr)` to avoid that). The same applies if the initial properties are
specified by a dictionary.

The properties `prop` can be specified by keywords, by key-value pairs, as a
dictionary or as a named tuple. To avoid ambiguities, these different styles
cannot be mixed. Below are a few examples:
dictionary or as a named tuple. To avoid ambiguities, these different styles
cannot be mixed. Below are a few examples:

```julia
using ArrayTools.AnnotatedArrays
Expand All @@ -188,23 +188,23 @@ D = AnnotatedArray(arr, (units = "µm", Δx = 0.1, Δy = 0.2))
```

The two first examples (`A` and `B`) both yield an annotated array whose
properties have symbolic keys and can have any type of value. The third
example (`C`) yields an annotated array whose properties have string keys and
can have any type of value. The properties of `A`, `B` and `C` are *dynamic*:
they can be modified, deleted and new properties can be inserted. The fourth
example (`D`) yields an annotated array whose properties are stored by a *named
tuple*, they are *immutable* and have symbolic keys.
properties have symbolic keys and can have any type of value. The third example
(`C`) yields an annotated array whose properties have string keys and can have
any type of value. The properties of `A`, `B` and `C` are *dynamic*: they can
be modified, deleted and new properties can be inserted. The fourth example
(`D`) yields an annotated array whose properties are stored by a *named tuple*,
they are *immutable* and have symbolic keys.

Accessing a property is possible via the syntax `obj[key]` or, for symbolic and
textual keys, via the syntax `obj.key`. Accessing *immutable* properties is
the fastest while accessing textual properties as `obj.key` is the slowest
(because it involves converting a symbol into a string).
textual keys, via the syntax `obj.key`. Accessing *immutable* properties is the
fastest while accessing textual properties as `obj.key` is the slowest (because
it involves converting a symbol into a string).

When initially specified by keywords or as key-value pairs, the properties are
stored in a dictionary whose key type is specialized if possible (for
efficiency) but with value type `Any` (for flexibility). If one wants specific
efficiency) but with value type `Any` (for flexibility). If one wants specific
properties key and value types, it is always possible to explicitly specify a
dictionary in the call to `AnnotatedArray`. For instance:
dictionary in the call to `AnnotatedArray`. For instance:

```julia
E = AnnotatedArray(arr, Dict{Symbol,Int32}(:a => 1, :b => 2))
Expand All @@ -222,9 +222,9 @@ If the dictionary is unspecified, the properties are stored in a, initially
empty, dictionary with symbolic keys and value of any type, *i.e.*
`Dict{Symbol,Any}()`.

Iterating on an annotated array is iterating on its array values. To iterate
on its properties, call the `properties` method which returns the object
storing the properties:
Iterating on an annotated array is iterating on its array values. To iterate on
its properties, call the `properties` method which returns the object storing
the properties:

```julia
dims = (100, 50)
Expand All @@ -247,10 +247,10 @@ Similar types are provided by
### Array indexing

The `all_indices` method takes any number of array arguments and yields an
efficient iterator for visiting all indices each index of the arguments. Its
efficient iterator for visiting all indices each index of the arguments. Its
behavior is similar to that of `eachindex` method except that `all_indices`
throws a `DimensionMismatch` exception if the arrays have different axes. It
is always safe to specify `@inbounds` (and `@simd`) for a loop like:
throws a `DimensionMismatch` exception if the arrays have different axes. It is
always safe to specify `@inbounds` (and `@simd`) for a loop like:

```julia
for i in all_indices(A, B, C, D)
Expand Down Expand Up @@ -332,25 +332,25 @@ array form.

If `IndexStyle(A) === IndexLinear()`, then array `A` can be efficiently
indexed by one integer (even if `A` is multidimensional) and column-major
ordering is used to access the elements of `A`. The only (known) other
ordering is used to access the elements of `A`. The only (known) other
possibility is `IndexStyle(A) === IndexCartesian()`.

If `IndexingTrait(A) === FastIndexing()`, then `IndexStyle(A) ===
IndexLinear()` also holds (see above) **and** array `A` has standard 1-based
indices.

* What is the difference between `Base.has_offset_axes` (provided by Julia) and
`has_standard_indexing` (provided by `ArrayTools`)?
`has_standard_indexing` (provided by `ArrayTools`)?

For the caller, `has_standard_indexing(args...)` yields the opposite result
as `Base.has_offset_axes(args...)`. Furthermore, `has_standard_indexing` is
a bit faster.
as `Base.has_offset_axes(args...)`. Furthermore, `has_standard_indexing` is a
bit faster.


## Installation

`ArrayTools` is an [official Julia package][julia-pkgs-url] and is easy to
install. In Julia, hit the `]` key to switch to the package manager REPL (you
install. In Julia, hit the `]` key to switch to the package manager REPL (you
should get a `... pkg>` prompt) and type:

```julia
Expand Down
10 changes: 5 additions & 5 deletions docs/src/broadcasting.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ broadcasting rules (see `broadcast` standard method).
Making a copy of `A` is avoided by [`bcastlazy`](@ref) (hence its name), and
`A` or a view on `A` is returned if `A` is already an array with the correct
element type and dimensions or if it can be reshaped (by the `reshape` method)
to match the constraints. This means that the result may share the same
contents as `A`. If an array that does not share its contents with `A` is
to match the constraints. This means that the result may share the same
contents as `A`. If an array that does not share its contents with `A` is
needed, then call:

```julia
Expand All @@ -28,7 +28,7 @@ bcastcopy(A, [T=eltype(A),] dims...)

instead of [`bcastlazy`](@ref).

The result returned by [`bcastlazy`](@ref) and [`bcastcopy`](@ref) has 1-based
The result returned by [`bcastlazy`](@ref) and [`bcastcopy`](@ref) has 1-based
indices and contiguous elements which is suitable for fast linear indexing.

The [`bcastsize`](@ref) method may be useful to determine dimensions when
Expand All @@ -40,8 +40,8 @@ bcastsize(a, b) -> c
```

The first one yields the size `siz` of the array that would result from
applying broadcasting rules to arguments `A`, `B`, etc. The result is a tuple
of integers (of type `Int`). You may call [`check_size`](@ref) to ensure that
applying broadcasting rules to arguments `A`, `B`, etc. The result is a tuple
of integers (of type `Int`). You may call [`check_size`](@ref) to ensure that
the result is a valid list on nonnegative dimensions.

The second applies broadcasting rules for a single dimension, throwing an
Expand Down
8 changes: 4 additions & 4 deletions docs/src/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ packages](https://pkg.julialang.org/):
```

where `… pkg>` represents the package manager prompt (the ellipsis `` denote
your current environment). To start Julia's package manager, launch Julia and,
your current environment). To start Julia's package manager, launch Julia and,
at the [REPL of
Julia](https://docs.julialang.org/en/stable/manual/interacting-with-julia/),
hit the `]` key; you should get the above `… pkg>` prompt. To revert to
Julia's REPL, just hit the `Backspace` key at the `… pkg>` prompt.
hit the `]` key; you should get the above `… pkg>` prompt. To revert to Julia's
REPL, just hit the `Backspace` key at the `… pkg>` prompt.

To check whether the `ArrayTools` package works correctly, type:

Expand All @@ -28,7 +28,7 @@ Later, to update to the last version (and run tests), you can type:
```

If something goes wrong, it may be because you already have an old version of
`ArrayTools`. Uninstall `ArrayTools` as follows:
`ArrayTools`. Uninstall `ArrayTools` as follows:

```julia
pkg> rm ArrayTools
Expand Down
17 changes: 9 additions & 8 deletions docs/src/rubberindex.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Rubber indices

The constants `..` and `` (type `\dots` and hit the `tab` key) can be used in
array indexation to left or right justify the other indices. For instance,
array indexation to left or right justify the other indices. For instance,
assuming `A` is a `3×4×5×6` array, then all the following equalities hold:

```julia
Expand All @@ -15,11 +15,12 @@ A[2:3,..,1,2:4] == A[2:3,:,1,2:4]

As you can see, the advantage of the *rubber index* `..` is that it
automatically expands as the number of colons needed to have the correct number
of indices. The expressions are also more readable. The idea comes from the
[`Yorick`](http://github.com/LLNL/yorick/) language by Dave Munro. Similar notation
exists in [`NumPy`](https://numpy.org/doc/stable/user/basics.indexing.html).
of indices. The expressions are also more readable. The idea comes from the
[`Yorick`](http://github.com/LLNL/yorick/) language by Dave Munro. Similar
notation exists in
[`NumPy`](https://numpy.org/doc/stable/user/basics.indexing.html).

The rubber index may also be used for setting values. For instance:
The rubber index may also be used for setting values. For instance:

```julia
A[..] .= 1 # to fill A with ones
Expand All @@ -32,8 +33,8 @@ A[..,2:4,5] .= 7 # to set all elements in A[:,:,2:4,5] to 7
Leading/trailing indices may be specified as Cartesian indices (of type
`CartesianIndex`).

Technically, the constant `..` is defined as `RubberIndex()` where `RubberIndex`
is the singleron type that represents any number of indices.
Technically, the constant `..` is defined as `RubberIndex()` where
`RubberIndex` is the singleron type that represents any number of indices.

Call `colons(n)` if you need a `n`-tuple of colons `:`. When `n` is known at
Call `colons(n)` if you need a `n`-tuple of colons `:`. When `n` is known at
compile time, it is faster to call `colons(Val(n))`.
7 changes: 4 additions & 3 deletions docs/src/storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,15 @@ FORTRAN, etc.), you have to make sure that array arguments have the same
storage as assumed by these languages so that it is safe to pass the pointer of
the array to the compiled function.

To check whether the elements of an array `A` are stored in memory
contiguously and in column-major order, call:
To check whether the elements of an array `A` are stored in memory contiguously
and in column-major order, call:

```julia
is_flat_array(A) -> bool
```

which yield a bollean result. Several arguments can be checked in a single call:
which yield a bollean result. Several arguments can be checked in a single
call:

```julia
is_flat_array(A, B, C, ...)
Expand Down

2 comments on commit 8f7dad8

@emmt
Copy link
Owner Author

@emmt emmt commented on 8f7dad8 May 25, 2023

Choose a reason for hiding this comment

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

@JuliaRegistrator register branch=master

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

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

Registration pull request created: JuliaRegistries/General/84228

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.2.6 -m "<description of version>" 8f7dad89bbff4c081107a964e4b9082597828a0a
git push origin v0.2.6

Please sign in to comment.