( )⚙ D11623 dirstate-v2: Use "byte sequence" in docs

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D11623

dirstate-v2: Use "byte sequence" in docs
ClosedPublic

Authored by SimonSapin on Oct 11 2021, 4:31 PM.

Details

Reviewers
pulkit
Group Reviewers
hg-reviewers
Commits
rHGeb8092f9304f: dirstate-v2: Use "byte sequence" in docs
Summary

The patch originally sent as https://phab.mercurial-scm.org/D11546
used "byte string" but that was changed during review to avoid suggesting
Unicode or character encodings.

However "byte range" sounds to be like a range of *indices* within a byte
string/sequence elsewhere.

This changes to "byte sequence". Python docs use "sequence" a lot when
discussing the bytes type: https://docs.python.org/3/library/stdtypes.html

Diff Detail

Repository
rHG Mercurial
Branch
default
Lint
No Linters Available
Unit
No Unit Test Coverage

Revision Contents
Changeset List

Diff 30704

mercurial/helptext/internals/dirstate-v2.txt

* The "expanded contents" of an ignore files is the byte string made * The "expanded contents" of an ignore files is the byte string made
by the concatenation of its contents followed by the "expanded contents" by the concatenation of its contents followed by the "expanded contents"
of other files included with `include:` or `subinclude:` directives, of other files included with `include:` or `subinclude:` directives,
in inclusion order. This definition is recursive, as included files can in inclusion order. This definition is recursive, as included files can
themselves include more files. themselves include more files.
This hash is defined as the SHA-1 of the concatenation (in sorted This hash is defined as the SHA-1 of the concatenation (in sorted
order) of the "expanded contents" of each "root" ignore file. order) of the "expanded contents" of each "root" ignore file.
(Note that computing this does not require actually concatenating byte ranges into (Note that computing this does not require actually concatenating
contiguous memory. into a single contiguous byte sequence.
Instead a SHA-1 hasher object can be created and fed separate byte ranges one by Instead a SHA-1 hasher object can be created
one.) and fed separate chunks one by one.)
The data file format The data file format
-------------------- --------------------
This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs` This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs`
and `mercurial/dirstateutils/v2.py`. and `mercurial/dirstateutils/v2.py`.
The data file contains two types of data: paths and nodes. The data file contains two types of data: paths and nodes.
Paths and nodes can be organized in any order in the file, except that sibling Paths and nodes can be organized in any order in the file, except that sibling
nodes must be next to each other and sorted by their path. Contiguity lets nodes must be next to each other and sorted by their path.
the parent refer to them all by their count with a single pseudo-pointer, Contiguity lets the parent refer to them all
instead of storing one pseudo-pointer per child node. Sorting allows using by their count and a single pseudo-pointer,
binary seach to find a child node with a given name in `O(log(n))` byte ranges instead of storing one pseudo-pointer per child node.
comparisons. Sorting allows using binary seach to find a child node with a given name
in `O(log(n))` byte sequence comparisons.
The current implemention writes paths and child node before a given node The current implemention writes paths and child node before a given node
for ease of figuring out the value of pseudo-pointers by the time the are to be for ease of figuring out the value of pseudo-pointers by the time the are to be
written, but this is not an obligation and readers must not rely on it. written, but this is not an obligation and readers must not rely on it.
A path is stored as a byte string anywhere in the file, without delimiter. A path is stored as a byte string anywhere in the file, without delimiter.
It is refered to by one or more node by a pseudo-pointer to its start, and its It is refered to by one or more node by a pseudo-pointer to its start, and its
length in bytes. Since there is no delimiter, length in bytes. Since there is no delimiter,