Skip to content

[spec/expression] Improve placement new docs #4338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 3, 2025
Merged

[spec/expression] Improve placement new docs #4338

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
18 changes: 10 additions & 8 deletions spec/expression.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3094,9 +3094,9 @@ $(H4 $(LNAME2 new_multidimensional, Multidimensional Arrays))
}
-----------

$(H4 $(LNAME2 placement-expression, Placement Expression))
$(H4 $(LNAME2 placement-expression, Placement New))

$(P The $(I PlacementExpression) explicitly provides the storage for $(I NewExpression) to initialize with
$(P The $(GLINK PlacementExpression) explicitly provides the storage for $(I NewExpression) to initialize with
the newly created value, rather than using the $(DDLINK spec/garbage, Garbage Collection, garbage
collected) heap.)

Expand All @@ -3105,9 +3105,6 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))

$(P The $(I Type) of the $(I PlacementExpression) need not be the same as the $(I Type) of the object being created.)

$(P Alternatively, the $(I PlacementExpression) can be a dynamic array, which must represent sufficient memory
for the object being created.)

$(BEST_PRACTICE Using a static array of `void` is preferred for the $(I PlacementExpression).)

$(P The lifetime of the object presented as an lvalue ends with the execution of the $(I NewExpression),
Expand All @@ -3131,7 +3128,7 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
---
)

(If Type is a class, the $(I PlacementExpression) must produce an lvalue of a type that is of a
$(P If *Type* is a class, the $(I PlacementExpression) must produce an lvalue of a type that is of a
sufficient size to hold the class object such as `void[__traits(classInstanceSize, Type)]`
or a dynamic array representing sufficient memory for the class object.)

Expand All @@ -3152,11 +3149,16 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
---
)

$(P $(I PlacementExpression) cannot be used for associative arrays, as associative arrays
$(P Restrictions:)
$(UL
$(LI The $(I PlacementExpression) type must be mutable and not `shared`.)

$(LI $(I Type) cannot be an associative array, as associative arrays
are designed to be on the GC heap. The size of the associative array allocated is determined
by the runtime library, and cannot be set by the user.)

$(P The use of $(I PlacementExpression) is not allowed in `@safe` code.)
$(LI Placement `new` is not allowed in `@safe` code.)
)

$(P To allocate storage with an allocator function such as `malloc()`, a simple template can be used:)

Expand Down