Skip to content
This repository has been archived by the owner on Oct 17, 2024. It is now read-only.

Update numberOf{Leading,Trailing}Zeros documentation #119

Closed
wants to merge 1 commit into from
Closed

Update numberOf{Leading,Trailing}Zeros documentation #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 0 additions & 4 deletions lib/src/int64.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,8 +634,6 @@ class Int64 implements IntX {
return this;
}

/// Returns the number of leading zeros in this [Int64] as an [int]
/// between 0 and 64.
@override
int numberOfLeadingZeros() {
int b2 = u.numberOfLeadingZeros(_h);
Expand All @@ -651,8 +649,6 @@ class Int64 implements IntX {
}
}

/// Returns the number of trailing zeros in this [Int64] as an [int]
/// between 0 and 64.
@override
int numberOfTrailingZeros() {
int zeros = u.numberOfTrailingZeros(_l);
Expand Down
14 changes: 10 additions & 4 deletions lib/src/intx.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,12 +125,18 @@ abstract class IntX implements Comparable<Object> {
/// value, add one, i.e. use `x.bitLength + 1`.
int get bitLength;

/// Returns the number of high-order zeros in this integer's bit
/// representation.
/// Returns the number of leading (most significant) zeros in this integer's
Copy link
Contributor

@lrhn lrhn Oct 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

If we're touching this, remove the "Returns". It's a getter, so document using a noun phrase.

(Actually, it's not a getter. It definitely should have been. But it's named as one, with a noun phrase name, so it should still be documented the same way.)

/// two's complement representation.
///
/// For zero, the result is the same as the integer type's bit max. bit
Copy link
Contributor

@lrhn lrhn Oct 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Something left over here? "bit max.bit length".

I don't know what a "bit max" is, and it's not defined.

Maybe:

/// For the value zero, the number of leading zeros is the entire
/// number of bits of the type (64 for [Int64], 32 for [Int32]).

Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe also worth adding that

/// Negative numbers have no leading zero bits, their most signfiicant
/// bit is always set.

/// length.
int numberOfLeadingZeros();

/// Returns the number of low-order zeros in this integer's bit
/// representation.
/// Returns the number of trailing (least significant) zeros in this
Copy link
Contributor

Choose a reason for hiding this comment

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

Drop "Returns" here too.

/// integer's two's complement representation.
///
/// For zero, the result is the same as the integer type's bit max. bit
/// length.
Copy link
Contributor

@lrhn lrhn Oct 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Same phrase,

/// For the value zero, the number of leading zeros is the entire
/// number of bits of the type (64 for [Int64], 32 for [Int32]).

And consider adding

/// Odd numbers have no trailing zero bits, their least significant bit
/// is always set.

It's just explanatory, but may help intuition.

Can also add

/// A number `n` is evenly divisible by `pow(2, n.numberOfTrailingZeros())`.

as another intuitional hint, building on the odd one.

int numberOfTrailingZeros();

/// Returns the least significant [width] bits of this integer, extending the
Expand Down