Add MPR#6975: truncate in Buffer module#902
Add MPR#6975: truncate in Buffer module#902gasche merged 11 commits intoocaml:trunkfrom dc-mak:buffer_truncate
Conversation
stdlib/buffer.mli
Outdated
| on the output channel [oc]. *) | ||
|
|
||
| val truncate : t -> int -> unit | ||
| (** [truncate b len] truncates the length of [b] to |
stdlib/buffer.mli
Outdated
| val truncate : t -> int -> unit | ||
| (** [truncate b len] truncates the length of [b] to | ||
| Note: it does not change the size of the underlying buffer. | ||
| Raise [Invalid_argument] if [len < 0] or [len > b.position]. *) |
There was a problem hiding this comment.
b.position is a bit opaque for users; you could use len > Buffer.length b.
stdlib/buffer.mli
Outdated
|
|
||
| val truncate : t -> int -> unit | ||
| (** [truncate b len] truncates the length of [b] to | ||
| Note: it does not change the size of the underlying buffer. |
There was a problem hiding this comment.
There is no other reference to the "underlying buffer" in the current doc. Perhaps "the internal byte sequence is not shortened", or "no memory is reclaimed"?
stdlib/buffer.ml
Outdated
|
|
||
| let truncate b len = | ||
| if len < 0 || len > b.position then | ||
| invalid_arg "Buffer.truncate" |
There was a problem hiding this comment.
The style is to use 2-space indentations.
|
I'm in favor of this proposal (and so was @damiendoligez according to the Mantis ticket). Please add a unit test and a Changes entry. |
Please enter the commit message for your changes. Lines starting
stdlib/buffer.mli
Outdated
|
|
||
| val truncate : t -> int -> unit | ||
| (** [truncate b len] truncates the length of [b] to [len] | ||
| Note: the intenal byte sequence is not shortenend. |
There was a problem hiding this comment.
Yes, on them (and test cases) now.
There was a problem hiding this comment.
Actually, speaking of test cases, can you point me to a canonical example of what a good test looks like? The examples in the tests directory are inconsistent, follow their own conventions, duplicate many functions, etc. across different modules/directories.
There was a problem hiding this comment.
One thing you can do to avoid existential worries is to add your tests to a file already testing buffer, namely basic-more/tbuffer.ml.
In general tests are done by having tests print some output (either by running the program, or the compiler or toplevel on the program), and comparing it to a reference output. The best outputs, I think, are those which give useful information when they fail: basic-more/tbuffer.ml just prints the list of test numbers that pass or fail, it's not very useful compared to lib-printf/pr6534.reference which gives useful information out failure. But that is a second-order concern: just having a good test that fails at the right time is the important thing here, and being locally consistent with wherever you decide to add your tests suffices. If you don't find a place you like, you can create tests/lib-buffer, which would be the natural place for Buffer test, and invent your own perfect convention.
stdlib/buffer.mli
Outdated
| val truncate : t -> int -> unit | ||
| (** [truncate b len] truncates the length of [b] to [len] | ||
| Note: the intenal byte sequence is not shortenend. | ||
| Raise [Invalid_argument] if [len < 0] or [len > b.position]. *) |
There was a problem hiding this comment.
b.position is an implementation detail, not exposed in the interface. Better:
or [len > length b]
Changes
Outdated
| (see Bigarray documentation) | ||
| (Laurent Mazare, | ||
| review by Gabriel Scherer, Alain Frisch and Hezekiah M. Carty) | ||
| >>>>>>> upstream/trunk |
Changes
Outdated
| (Gabriel de Perthuis, with contributions from Alain Frisch, review by | ||
| Hezekiah M. Carty and Simon Cruanes, initial report by Gerd Stolpmann) | ||
|
|
||
| - MPR#6975: Truncate function added to stdlib Buffer module |
There was a problem hiding this comment.
While we are at it (sorry for the endless nit-picking): as mentioned in the contributing guidelines, you should include both mantis and github numbers: PR#6975, GPR#902 (for now the convention is still PR# and not MPR#), and it should be at the top of the "Standard library" section because we order by mantis PR numbers first, so entries without a mantis ticket are last.
There was a problem hiding this comment.
Oh not at all, in fact, (as a first timer) I'm sorry for all the mistakes - I'm really grateful for and appreciate the patience shown by everyone who's commented.
|
I think it's good and would be willing to merge. My inner unit tester is telling me that two natural cases to test (that seem to be missing currently) would be resetting at the current length, and resetting at length |
|
I squashed and merged, thanks for the nice PR! |
MPR#6975: add truncate in Buffer module
b11eea1 flambda-backend: Introduce Import_info (ocaml#1036) bc5b135 flambda-backend: Fix `ocamlobjinfo` on flambda2 .cmx files (ocaml#1029) c8babbd flambda-backend: Compilation_unit optimisations (ocaml#1035) e8d3e22 flambda-backend: Use 4.14.0 opam switch for building (includes upgrading ocamlformat to 0.24.1) (ocaml#1030) eb14a86 flambda-backend: Port PR81 from ocaml-jst (ocaml#1024) 131bc12 flambda-backend: Merge ocaml-jst 2022-12-13 (ocaml#1022) 06c189a flambda-backend: Make stack allocation the default (ocaml#1013) 98debd5 flambda-backend: Initial support for value slots not of value kind (ocaml#946) deb1714 flambda-backend: Add is_last flag to closinfo words (ocaml#938) d07fce1 flambda-backend: Disable poll insertion in Configure (ocaml#967) 0f1ce0e flambda-backend: Regenerate ocaml/configure autoconf 2.69 (instead of 2.71) (ocaml#1012) 27132d8 flambda-backend: Fix for spurious typing error related to expanding through functor arguments (ocaml#997) 724fb68 flambda-backend: Use `Compilation_unit.t` instead of `Ident.t` for globals (ocaml#871) 396d5b8 flambda-backend: Add a test for frametable setup in natdynlinked libraries (ocaml#983) b73ab12 flambda-backend: Fix invocation of `caml_shared_startup` in native dynlink (ocaml#980) 7c7d75a flambda-backend: Fix split_default_wrapper which did not trigger anymore with flambda2 (ocaml#970) 8fb75bd flambda-backend: Port ocaml#11727 and ocaml#11732 (ocaml#965) fdb7987 flambda-backend: Fix include functor issue after 4.14 merge. (ocaml#948) 9745cdb flambda-backend: Print -dprofile/-dtimings output to stdout like 4.12 (ocaml#943) 5f51f21 flambda-backend: Merge pull request ocaml#932 from mshinwell/4.14-upgrade 841687d flambda-backend: Run make alldepend in ocaml/ (ocaml#936) 72a7658 flambda-backend: Remove reformatting changes only in dynlink/dune (preserving PR889 and adjusting to minimise diff) 6d758cd flambda-backend: Revert whitespace changes in dune files, to match upstream c86bf6e flambda-backend: Remove duplicate tests for polling 971dbeb flambda-backend: Testsuite fixes 32f8356 flambda-backend: Topeval fix for symbols patch befea01 flambda-backend: Compilation fixes / rectify merge faults a84543f flambda-backend: Merge ocaml-jst 8e65056 flambda-backend: Merge ocaml-jst 4d70045 flambda-backend: Remove filename from system frametable (amd64) (ocaml#920) 5e57b7d flambda-backend: Bugfix for runtime frame_descr logic for C frames (ocaml#918) 6423d5e flambda-backend: Merge pull request ocaml#914 from mshinwell/merge-ocaml-jst-2022-10-24 ead605c flambda-backend: Add a missing Extract_exception (ocaml#916) c8f1481 flambda-backend: Resolve conflicts and add specialise/specialised attributes to Builtin_attributes cf4d0d3 flambda-backend: Merge fixes (ocaml#21) c2f742f flambda-backend: Re-enable some tests for Flambda2 (ocaml#881) 3d38d13 flambda-backend: Long frames in frametable (ocaml#797) 85aec7b flambda-backend: Add loop attribute to Builtin_attributes c0f16e3 flambda-backend: Compilation fixes 90dea23 flambda-backend: Merge flambda-backend/main 5acc6ea flambda-backend: Fixes after merge e501946 flambda-backend: Merge ocaml-jst 115083b flambda-backend: Merge ocaml-jst 9943b2e flambda-backend: Revert "Revert "Transform tail-recursive functions into recursive continuations (ocaml#893)"" (ocaml#909) ce339f1 flambda-backend: Fix alloc modes and call kinds for overapplications (ocaml#902) e6a317c flambda-backend: Revert "Transform tail-recursive functions into recursive continuations (ocaml#893)" 853c488 flambda-backend: Transform tail-recursive functions into recursive continuations (ocaml#893) 5a977e4 flambda-backend: Fix missing End_region primitives on switch arms (ocaml#898) 7fa7f9d flambda-backend: Add missing dependencies to Dune files (ocaml#889) 3cd36f0 flambda-backend: Have Lambda `Pgetglobal` and `Psetglobal` take `Compilation_unit.t` (ocaml#896) 7565915 flambda-backend: [@poll error] attribute (ocaml#745) 9eb9448 flambda-backend: Backport the main safepoints PRs (ocaml#740) 689bdda flambda-backend: Add strict mode for ocamldep (ocaml#892) git-subtree-dir: ocaml git-subtree-split: b11eea1
5 participants
As requested by this Mantis request.
Since the intention of truncate is specifically to shorten, an argument greater than the current buffer length is seen as an error - it is the responsibility of the caller to ensure this is not the case.