[RFC] document the unsafe conversions Bytes.unsafe_{to,of}_string#90
Closed
gasche wants to merge 4 commits intoocaml:4.02from
Closed
[RFC] document the unsafe conversions Bytes.unsafe_{to,of}_string#90gasche wants to merge 4 commits intoocaml:4.02from
gasche wants to merge 4 commits intoocaml:4.02from
Conversation
Users will inevitably do dirty things during the -safe-string migration. Better document the available dirty hacks, rather than letting them use Obj.magic by lack of information.
Contributor
|
I've been previously frustrated by the approach of not documenting function considered unsafe, since it basically means you have to be a member of "the club" to know what the function does and how to use it correctly, so I applaud this initiative. I've read your documentation, and I find it clear and informative. |
Member
Author
|
I've just applied Daniel's suggestions. Thanks! |
stdlib/bytes.mli
Outdated
Member
There was a problem hiding this comment.
"converting between [bytes] and [string]" reads better here.
chambart
pushed a commit
to chambart/ocaml-1
that referenced
this pull request
Aug 4, 2021
Import middle_end/flambda2 from ocaml-flambda/ocaml rev 068eb9f (Fexpr support for rec info, coercions (ocaml#567)) squashed with the following fixes (from mshinwell/flambda-backend branch import-flambda2): * Fix inlining attributes in middle_end/flambda2/compilenv_deps/patricia_tree.ml * Fix inlining attributes in middle_end/flambda2/naming/name_abstraction.ml * Update Lambda_conversions to cope with the removal of the size+tag propagation * dune file fixes for Flambda 2 compilation in the Flambda backend * Stub out Flambda_features temporarily * Fixes for Immutable_unique and tag/size removal patch * is_c_builtin * probes * Support for probes and C builtins (as used for intrinisics) * Removal of Double_u, use Double instead * Use exhaustive match in close_c_call * menhir version change in middle_end/flambda2/parser/flambda_parser.ml * Avoid Location.print_compact * Avoid Lambda.print_scoped_location
stedolan
pushed a commit
to stedolan/ocaml
that referenced
this pull request
Oct 5, 2021
Import middle_end/flambda2 from ocaml-flambda/ocaml rev 068eb9f (Fexpr support for rec info, coercions (ocaml#567)) squashed with the following fixes (from mshinwell/flambda-backend branch import-flambda2): * Fix inlining attributes in middle_end/flambda2/compilenv_deps/patricia_tree.ml * Fix inlining attributes in middle_end/flambda2/naming/name_abstraction.ml * Update Lambda_conversions to cope with the removal of the size+tag propagation * dune file fixes for Flambda 2 compilation in the Flambda backend * Stub out Flambda_features temporarily * Fixes for Immutable_unique and tag/size removal patch * is_c_builtin * probes * Support for probes and C builtins (as used for intrinisics) * Removal of Double_u, use Double instead * Use exhaustive match in close_c_call * menhir version change in middle_end/flambda2/parser/flambda_parser.ml * Avoid Location.print_compact * Avoid Lambda.print_scoped_location
sadiqj
pushed a commit
to sadiqj/ocaml
that referenced
this pull request
Feb 21, 2023
stedolan
pushed a commit
to stedolan/ocaml
that referenced
this pull request
Mar 21, 2023
c703f5f Incorporate upstream comments into type-variable refactor (ocaml#121) 362ba23 Constrain curry modes to increase along applications (ocaml#108) b1f0cf9 Simplify the extension handling (ocaml#114) 4fd53a1 Remove pat_mode from typedtree (ocaml#105) cf6fcbc Handle attributes on lambdas with locally abstract types (ocaml#120) 5fa80fe Don't track attributes inside attributes for warning 53 (ocaml#115) 8a69777 Handle unclosed `[: ... :]` patterns (via `Generic_array` machinery) (ocaml#117) b0737f4 Add promote-one Makefile target (ocaml#118) c6ad684 Refactoring and fixes around module lookup (ocaml#107) b0a6495 Add documentation for global constructor arguments (ocaml#69) dd79aec Print `nlocal` in the `-d(raw)lambda` output (ocaml#112) 8035026 Fix `nlocal` in the generated Lambda for list comprehensions (ocaml#113) afbcdf0 Immutable arrays (ocaml#47) bfe1490 fix several issues when removing exp_mode (ocaml#110) 8f46060 Better error message for under-applied functions (ocaml#74) 27331d8 Consistently use Lmutvar or Lvar in comprehensions (ocaml#111) 01e965b Skip failing test for now 0131357 Fix test case to use comprehensions_experimental 22a7368 Temporarily disable list comprehensions tests due to locals bug e08377d Make `comprehensions` into `comprehensions_experimental` for now (ocaml#109) 947cf89 List and array comprehensions (ocaml#46) bd9e051 remove exp_mode from typedtree (ocaml#100) a9268d2 Fix misplaced attribute warning when using external parser (and some cleanup) (ocaml#101) 2b33f24 Refactor toplevel local escape check (ocaml#104) ed2aec6 Comment functions exported from TyVarEnv. 87838ba Move new variable creation into TyVarEnv. a3f60ab Encapsulate functions that work with tyvars 43d83a6 Prevent possibility of forgetting to re-widen 2f3dd34 Encapsulate context when narrowing type env't d78ff6d Make immediate64 things mode cross (ocaml#97) aa25ab9 Fix version number (ocaml#94) d01ffa0 Fix .depend file (ocaml#93) 942f2ab Bootstrap (ocaml#92) 05f7e38 Check Menhir version (ocaml#91) 1569b58 Move the CI jobs from 4.12 to 4.14. (ocaml#90) git-subtree-dir: ocaml git-subtree-split: c703f5f
EmileTrotignon
pushed a commit
to EmileTrotignon/ocaml
that referenced
this pull request
Jan 12, 2024
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The attached patch contains a tentative documentation of the two new functions [Bytes.unsafe_of_string] and [Bytes.unsafe_to_string] that are intended for use when migrating code to support the new
-safe-stringoption.It is only a preliminary patch; in particular, it does not contain much OCamldoc formatting (I will add those laters). I would be interested in feedback on the content. The objectives of documenting these functions are the following:
Bytes.of_stringandBytes.to_stringwhich are correct and fast enough for most purposes)Obj.magicor"%identity"instead.Not documenting at all is a very good way to reach goal (1), but does pretty badly on (2). Do you feel the proposed documentation is effective? How should it be improved?
Finally, be aware that documenting unsafe functions is still a controversial topic among OCaml maintainers. I'd like to get as good a proposal as possible, but it is possible that maintainers decide to keep those undocumented in any case. Invest your time wisely.