Merge pull request #15 from bavix/bxp-docs

godoc

.github/dependabot.yml

@@ -5,3 +5,8 @@ updates:
   schedule:
     interval: daily
   open-pull-requests-limit: 10
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10

.golangci.yml

@@ -31,4 +31,5 @@ issues:
   exclude-rules:
     - path: (.+)_test.go
       linters:
+        - gochecknoglobals
         - dupl

bench_test.go

@@ -10,15 +10,25 @@ import (
 	"github.com/bavix/boxpacker3"
 )
 
+// BenchmarkPacker benchmarks the Pack method of the Packer type.
+//
+// This benchmark uses a list of 100 random items and the default box list.
+// The benchmark reports the number of allocations and resets the timer before
+// the loop.
+//
+// The loop iterates over the items and packs them into boxes.
 func BenchmarkPacker(b *testing.B) {
+	// Create a slice of 100 random items
 	items := make([]*boxpacker3.Item, 0, 100)
 
-	for range 100 {
+	for range cap(items) {
+		// Generate random dimensions for the item
 		w, _ := rand.Int(rand.Reader, big.NewInt(150))
 		l, _ := rand.Int(rand.Reader, big.NewInt(150))
 		h, _ := rand.Int(rand.Reader, big.NewInt(150))
 		w2, _ := rand.Int(rand.Reader, big.NewInt(100))
 
+		// Create a new item with the random dimensions
 		items = append(items, boxpacker3.NewItem(
 			uuid.New().String(),
 			float64(w.Int64()),
@@ -28,11 +38,16 @@ func BenchmarkPacker(b *testing.B) {
 		))
 	}
 
+	// Create a new box list with the default boxes
 	boxes := NewDefaultBoxList()
+	// Create a new packer
 	packer := boxpacker3.NewPacker()
 
+	// Report allocations and reset the timer
+	b.ReportAllocs()
 	b.ResetTimer()
 
+	// Iterate over the items and pack them into boxes
 	for i := 0; i < b.N; i++ {
 		_ = packer.Pack(boxes, items)
 	}

box.go

@@ -1,37 +1,72 @@
 package boxpacker3
 
-import (
-	"slices"
-)
-
+// Box represents a box that can hold items.
+//
+// It has fields for the box's dimensions and maximum weight.
+// It also has fields for tracking the box's current items and their volume and weight.
 type Box struct {
-	id        string
-	width     float64
-	height    float64
-	depth     float64
+	// id is the box's unique identifier.
+	id string
+
+	// width is the box's width.
+	width float64
+
+	// height is the box's height.
+	height float64
+
+	// depth is the box's depth.
+	depth float64
+
+	// maxWeight is the maximum weight the box can hold.
 	maxWeight float64
-	volume    float64
-	items     []*Item
 
-	maxLength   float64
+	// volume is the box's volume (width * height * depth).
+	volume float64
+
+	// items is a slice of items currently in the box.
+	items []*Item
+
+	// maxLength is the length of the box's longest side.
+	maxLength float64
+
+	// itemsVolume is the total volume of the items in the box.
 	itemsVolume float64
+
+	// itemsWeight is the total weight of the items in the box.
 	itemsWeight float64
 }
 
+// boxSlice is a slice of boxes.
+//
+// It implements the sort.Interface by defining Len, Less and Swap methods.
 type boxSlice []*Box
 
+// Len returns the length of the boxSlice.
 func (bs boxSlice) Len() int {
 	return len(bs)
 }
 
+// Less compares two boxes by volume.
 func (bs boxSlice) Less(i, j int) bool {
 	return bs[i].volume < bs[j].volume
 }
 
+// Swap swaps two boxes in the boxSlice.
 func (bs boxSlice) Swap(i, j int) {
 	bs[i], bs[j] = bs[j], bs[i]
 }
 
+// NewBox creates a new Box with the given id, dimensions, and maximum weight.
+//
+// Parameters:
+// - id: a unique identifier for the box.
+// - w: the width of the box.
+// - h: the height of the box.
+// - d: the depth of the box.
+// - mw: the maximum weight the box can hold.
+//
+// Returns:
+// - A pointer to the newly created Box.
 func NewBox(id string, w, h, d, mw float64) *Box {
 	//nolint:exhaustruct
 	return &Box{
@@ -40,82 +75,161 @@ func NewBox(id string, w, h, d, mw float64) *Box {
 		height:    h,
 		depth:     d,
 		maxWeight: mw,
-		maxLength: slices.Max([]float64{w, h, d}),
+		maxLength: max(w, h, d),
 		volume:    w * h * d,
-		items:     nil,
+		items:     make([]*Item, 0, 1),
 	}
 }
 
+// GetID returns the unique identifier of the box.
 func (b *Box) GetID() string {
 	return b.id
 }
 
+// GetWidth returns the width of the box.
 func (b *Box) GetWidth() float64 {
 	return b.width
 }
 
+// GetHeight returns the height of the box.
 func (b *Box) GetHeight() float64 {
 	return b.height
 }
 
+// GetDepth returns the depth of the box.
 func (b *Box) GetDepth() float64 {
 	return b.depth
 }
 
+// GetVolume returns the volume of the box.
 func (b *Box) GetVolume() float64 {
 	return b.volume
 }
 
+// GetMaxWeight returns the maximum weight the box can hold.
 func (b *Box) GetMaxWeight() float64 {
 	return b.maxWeight
 }
 
+// GetItems returns a slice of pointers to the items currently in the box.
+//
+// The slice is a copy and not a reference to the original slice, so modifying
+// the slice returned by this function will not affect the contents of the box.
 func (b *Box) GetItems() []*Item {
-	return b.items
-}
-
-// PutItem Attempts to place an element at anchor point p of box b.
+	return append([]*Item(nil), b.items...)
+}
+
+// PutItem Attempts to place the given item at the specified anchor point within the box.
+//
+// Attempts to place the given item at the specified anchor point within the box.
+//
+// It tries to place the item at the given anchor point by iterating through each
+// rotation type (Whd, Hwd, Hdw, Dhw, Dwh, Wdh) and checks if the item can be
+// placed within the box without intersecting with any of the other items in the box.
+// If the item can be placed, it inserts the item into the box and returns true.
+// If the item cannot be placed, it returns false.
+//
+// Parameters:
+//   - item: The item to be placed in the box.
+//   - p: The anchor point at which to attempt placing the item within the box.
+//
+// Returns:
+//   - bool: True if the item was successfully placed within the box, false otherwise.
 func (b *Box) PutItem(item *Item, p Pivot) bool {
+	// Check if the item can fit in the box based on volume and weight quotas.
 	if !b.canQuota(item) {
 		return false
 	}
 
+	// Set the item's position to the anchor point.
 	item.position = p
 
+	// Iterate through each rotation type to find a suitable placement.
 	for rt := RotationTypeWhd; rt <= RotationTypeWdh; rt++ {
+		// Set the item's rotation type to the current rotation type.
 		item.rotationType = rt
-		d := item.GetDimension()
 
-		if b.width < p[WidthAxis]+d[WidthAxis] || b.height < p[HeightAxis]+d[HeightAxis] || b.depth < p[DepthAxis]+d[DepthAxis] {
+		// Get the dimensions of the item in its current rotation type.
+		itemDimensions := item.GetDimension()
+
+		// Check if the box has enough dimensions to accommodate the item.
+		if b.width < p[WidthAxis]+itemDimensions[WidthAxis] ||
+			b.height < p[HeightAxis]+itemDimensions[HeightAxis] ||
+			b.depth < p[DepthAxis]+itemDimensions[DepthAxis] {
 			continue
 		}
 
-		for _, ib := range b.items {
-			if ib.Intersect(item) {
-				return false
-			}
+		// Check if the item intersects with any other items in the box.
+		if b.itemsIntersect(item) {
+			continue
 		}
 
+		// Insert the item into the box and return true.
 		b.insert(item)
 
 		return true
 	}
 
+	// If no suitable placement is found, return false.
 	return false
 }
 
+// itemsIntersect checks if any of the items in the box intersect with the given item.
+// It iterates through each item in the box and calls the Intersect method on the item.
+// If an intersection is found, it returns true.
+// If no intersection is found, it returns false.
+func (b *Box) itemsIntersect(item *Item) bool {
+	for _, ib := range b.items {
+		if ib.Intersect(item) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// canQuota checks if the box can accommodate the given item based on both volume and weight quotas.
+//
+// It calls the canFitVolume and canFitWeight methods to check if the box has enough room for the
+// item's volume and weight. If both conditions are true, it returns true. Otherwise, it returns false.
 func (b *Box) canQuota(item *Item) bool {
-	return b.itemsVolume+item.volume <= b.volume && b.itemsWeight+item.weight <= b.maxWeight
+	return b.canFitVolume(item) && b.canFitWeight(item)
+}
+
+// canFitVolume checks if the box can accommodate the given item based on volume.
+//
+// It compares the sum of the item's volume and the current volume of items in the box
+// to the box's total volume. If the sum is less than or equal to the box's total volume,
+// it returns true. Otherwise, it returns false.
+func (b *Box) canFitVolume(item *Item) bool {
+	return b.itemsVolume+item.volume <= b.volume
+}
+
+// canFitWeight checks if the box can accommodate the given item based on weight.
+//
+// It compares the sum of the item's weight and the current weight of items in the box
+// to the box's maximum weight. If the sum is less than or equal to the box's maximum weight,
+// it returns true. Otherwise, it returns false.
+func (b *Box) canFitWeight(item *Item) bool {
+	return b.itemsWeight+item.weight <= b.maxWeight
 }
 
+// insert inserts an item into the box and updates the total volume and weight.
+//
+// It appends the item to the box's items slice and adds the item's volume and weight to the
+// box's total volume and weight.
 func (b *Box) insert(item *Item) {
 	b.items = append(b.items, item)
 	b.itemsVolume += item.volume
 	b.itemsWeight += item.weight
 }
 
-func (b *Box) purge() {
-	b.items = make([]*Item, 0, len(b.items))
+// Reset clears the box and resets the volume and weight.
+//
+// It removes all items from the box by slicing the items slice to an empty slice.
+// It sets the total volume and weight of items in the box to 0.
+func (b *Box) Reset() {
+	b.items = b.items[:0]
 	b.itemsVolume = 0
 	b.itemsWeight = 0
 }

consts.go

@@ -1,25 +1,37 @@
 package boxpacker3
 
+// RotationType represents the type of rotation for an item.
 type RotationType int
 
+// RotationTypeWhd represents the rotation type where the width is the longest dimension.
 const (
 	RotationTypeWhd RotationType = iota
+	// RotationTypeHwd represents the rotation type where the height is the longest dimension.
 	RotationTypeHwd
+	// RotationTypeHdw represents the rotation type where the depth is the longest dimension.
 	RotationTypeHdw
+	// RotationTypeDhw represents the rotation type where the depth is the longest dimension.
 	RotationTypeDhw
+	// RotationTypeDwh represents the rotation type where the width is the longest dimension.
 	RotationTypeDwh
+	// RotationTypeWdh represents the rotation type where the height is the longest dimension.
 	RotationTypeWdh
 )
 
+// Axis represents the axis of a dimension.
 type Axis int
 
+// WidthAxis represents the width axis.
 const (
 	WidthAxis Axis = iota
+	// HeightAxis represents the height axis.
 	HeightAxis
+	// DepthAxis represents the depth axis.
 	DepthAxis
 )
 
-type (
-	Pivot     [3]float64
-	Dimension [3]float64
-)
+// Pivot represents the position of an item within a box.
+type Pivot [3]float64
+
+// Dimension represents the dimensions of an item or a box.
+type Dimension [3]float64

copyptr.go

@@ -1,23 +1,35 @@
 package boxpacker3
 
 // CopyPtr creates a copy of a pointer.
+//
+// It takes a pointer to a generic type T as an argument and returns a new pointer
+// to a copy of the original value. If the original pointer is nil, it returns nil.
 func CopyPtr[T any](original *T) *T {
+	// If the original pointer is nil, return nil.
 	if original == nil {
 		return nil
 	}
 
+	// Create a copy of the value pointed to by the original pointer.
 	copyOfValue := *original
 
+	// Return a new pointer to the copied value.
 	return &copyOfValue
 }
 
 // CopySlicePtr creates a copy of a slice of pointers.
+//
+// It takes a slice of pointers as an argument and returns a new slice with the same
+// elements, but with each element being a copy of the original.
 func CopySlicePtr[T any](data []*T) []*T {
+	// Create a new slice with the same length as the original.
 	result := make([]*T, len(data))
 
+	// Iterate over the original slice and copy each element to the new slice.
 	for i, item := range data {
 		result[i] = CopyPtr(item)
 	}
 
+	// Return the new slice.
 	return result
 }