Skip to content

Commit c5600a9

Browse files
authored
[spec/expression] Improve placement new docs (#4338)
Rename subheading *Placement New*. Add grammar link. Remove 'PlacementExpression can be a dynamic array' - see dlang/dmd#22164. Fix paragraph tag for class PlacementExpression. Use list for restrictions. PlacementExpression type must be mutable and not `shared`.
1 parent 9e34ce8 commit c5600a9

File tree

1 file changed

+10
-8
lines changed

1 file changed

+10
-8
lines changed

spec/expression.dd

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3094,9 +3094,9 @@ $(H4 $(LNAME2 new_multidimensional, Multidimensional Arrays))
30943094
}
30953095
-----------
30963096

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

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

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

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

3108-
$(P Alternatively, the $(I PlacementExpression) can be a dynamic array, which must represent sufficient memory
3109-
for the object being created.)
3110-
31113108
$(BEST_PRACTICE Using a static array of `void` is preferred for the $(I PlacementExpression).)
31123109

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

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

@@ -3152,11 +3149,16 @@ $(H4 $(LNAME2 placement-expression, Placement Expression))
31523149
---
31533150
)
31543151

3155-
$(P $(I PlacementExpression) cannot be used for associative arrays, as associative arrays
3152+
$(P Restrictions:)
3153+
$(UL
3154+
$(LI The $(I PlacementExpression) type must be mutable and not `shared`.)
3155+
3156+
$(LI $(I Type) cannot be an associative array, as associative arrays
31563157
are designed to be on the GC heap. The size of the associative array allocated is determined
31573158
by the runtime library, and cannot be set by the user.)
31583159

3159-
$(P The use of $(I PlacementExpression) is not allowed in `@safe` code.)
3160+
$(LI Placement `new` is not allowed in `@safe` code.)
3161+
)
31603162

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

0 commit comments

Comments
 (0)