Skip to content

Commit

Permalink
doc: remove use of the word 'experiment'
Browse files Browse the repository at this point in the history
While bstr is not yet at 1.0, it is not really an experiment any more.
Its API has and will remain stable for many years to come (with only
very minor breaking changes planned for 1.0, which should happen soon).

In general, the docs used the word "experiment" to refer to two
different things:

1. The idea that "UTF-8 by convention" is more useful in some cases than
   "required valid UTF-8."
2. That dependency trees should be kept to a minimum, i.e., providing a
   cohesive crate rather than a big tree of micro-crates.

(1) seems to be very clearly settled. There are folks using bstr in big
projects precisely because it makes their life a lot easier.

(2) is perhaps still questionable, but it doesn't really make sense to
call it an "experiment" and scare folks away. I think it makes more
sense to just declare "small dependency tree" as a goal that we strive
for.

Closes #99
  • Loading branch information
BurntSushi committed Sep 20, 2021
1 parent fffcb0f commit 602c147
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 27 deletions.
29 changes: 13 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,12 +171,12 @@ My hope is to move to `1.0` within the next year and commit to its API so that
`bstr` can be used as a public dependency.

A large part of the API surface area was taken from the standard library, so
from an API design perspective, a good portion of this crate should be mature.
The main differences from the standard library are in how the various substring
search routines work. The standard library provides generic infrastructure for
supporting different types of searches with a single method, where as this
library prefers to define new methods for each type of search and drop the
generic infrastructure.
from an API design perspective, a good portion of this crate should be on solid
ground already. The main differences from the standard library are in how the
various substring search routines work. The standard library provides generic
infrastructure for supporting different types of searches with a single method,
where as this library prefers to define new methods for each type of search and
drop the generic infrastructure.

Some _probable_ future considerations for APIs include, but are not limited to:

Expand All @@ -195,10 +195,10 @@ Here are some examples that are _probably_ out of scope for this crate:

The exact scope isn't quite clear, but I expect we can iterate on it.

In general, as stated below, this crate is an experiment in bringing lots of
related APIs together into a single crate while simultaneously attempting to
keep the total number of dependencies low. Indeed, every dependency of `bstr`,
except for `memchr`, is optional.
In general, as stated below, this crate brings lots of related APIs together
into a single crate while simultaneously attempting to keep the total number of
dependencies low. Indeed, every dependency of `bstr`, except for `memchr`, is
optional.


### High level motivation
Expand Down Expand Up @@ -229,13 +229,10 @@ Consider, for example, trimming and splitting, along with their different
variants.

In other words, `bstr` is partially a way of pushing back against the
micro-crate ecosystem that appears to be evolving. It's not clear to me whether
this experiment will be successful or not, but it is definitely a goal of
micro-crate ecosystem that appears to be evolving. Namely, it is a goal of
`bstr` to keep its dependency list lightweight. For example, `serde` is an
optional dependency because there is no feasible alternative, but `twoway` is
not, where we instead prefer to implement our own substring search. In service
of this philosophy, currently, the only required dependency of `bstr` is
`memchr`.
optional dependency because there is no feasible alternative. In service of
this philosophy, currently, the only required dependency of `bstr` is `memchr`.


### License
Expand Down
23 changes: 12 additions & 11 deletions src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*!
An experimental byte string library.
A byte string library.
Byte strings are just like standard Unicode strings with one very important
difference: byte strings are only *conventionally* UTF-8 while Rust's standard
Expand Down Expand Up @@ -98,10 +98,10 @@ method converts any `&[u8]` to a `&BStr`.
# When should I use byte strings?
This library is somewhat of an experiment that reflects my hypothesis that
UTF-8 by convention is a better trade off in some circumstances than guaranteed
UTF-8. It's possible, perhaps even likely, that this is a niche concern for
folks working closely with core text primitives.
This library reflects my hypothesis that UTF-8 by convention is a better trade
off in some circumstances than guaranteed UTF-8. It's possible, perhaps even
likely, that this is a niche concern for folks working closely with core text
primitives.
The first time this idea hit me was in the implementation of Rust's regex
engine. In particular, very little of the internal implementation cares at all
Expand Down Expand Up @@ -134,15 +134,16 @@ incremental way by only parsing chunks at a time, but this is often complex to
do or impractical. For example, many regex engines only accept one contiguous
sequence of bytes at a time with no way to perform incremental matching.
In summary, the conventional UTF-8 byte strings provided by this library is an
experiment. They are definitely useful in some limited circumstances, but how
useful they are more broadly isn't clear yet.
In summary, conventional UTF-8 byte strings provided by this library are
definitely useful in some limited circumstances, but how useful they are more
broadly isn't clear yet.
# `bstr` in public APIs
Since this library is still experimental, you should not use it in the public
API of your crates until it hits `1.0` (unless you're OK with with tracking
breaking releases of `bstr`).
Since this library is not yet `1.0`, you should not use it in the public API of
your crates until it hits `1.0` (unless you're OK with with tracking breaking
releases of `bstr`). It is expected that `bstr 1.0` will be released before
2022.
In general, it should be possible to avoid putting anything in this crate into
your public APIs. Namely, you should never need to use the `ByteSlice` or
Expand Down

0 comments on commit 602c147

Please sign in to comment.