doc: add document for GCD and LCM function

mathutil/mathutil.go

@@ -287,8 +287,8 @@ func gcd[T constraints.Integer](a, b T) T {
 func LCM[T constraints.Integer](integers ...T) T {
 	result := integers[0]
 
-	for i := 1; i < len(integers)-1; i++ {
-		result = lcm(result, integers[i])
+	for k := range integers {
+		result = lcm(integers[k], result)
 	}
 
 	return result
@@ -296,5 +296,8 @@ func LCM[T constraints.Integer](integers ...T) T {
 
 // find Least Common Multiple (LCM) via GCD.
 func lcm[T constraints.Integer](a, b T) T {
+	if a == 0 || b == 0 {
+		panic("lcm function: provide non zero integers only.")
+	}
 	return a * b / gcd(a, b)
 }

mathutil/mathutil_exmaple_test.go

@@ -281,3 +281,39 @@ func ExampleIsPrime() {
 	// false
 	// true
 }
+
+func ExampleGCD() {
+	result1 := GCD(1, 1)
+	result2 := GCD(1, -1)
+	result3 := GCD(-1, 1)
+	result4 := GCD(-1, -1)
+	result5 := GCD(3, 6, 9)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+	fmt.Println(result4)
+	fmt.Println(result5)
+
+	// Output:
+	// 1
+	// 1
+	// -1
+	// -1
+	// 3
+}
+
+func ExampleLCM() {
+	result1 := LCM(1, 1)
+	result2 := LCM(1, 2)
+	result3 := LCM(3, 6, 9)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+	fmt.Println(result3)
+
+	// Output:
+	// 1
+	// 2
+	// 18
+}

mathutil/mathutil_test.go

@@ -239,12 +239,12 @@ func TestGCD(t *testing.T) {
 func TestLCM(t *testing.T) {
 	assert := internal.NewAssert(t, "TestLCM")
 
-	assert.Equal(0, LCM(0))
 	assert.Equal(1, LCM(1))
 	assert.Equal(-1, LCM(-1))
-	assert.Equal(0, LCM(0, -1))
-	assert.Equal(0, LCM(0, 1))
+	assert.Equal(-1, LCM(1, -1))
+	assert.Equal(1, LCM(-1, 1))
 	assert.Equal(1, LCM(1, 1))
-	assert.Equal(1, LCM(1, 2))
-	assert.Equal(6, LCM(3, 6, 9))
+	assert.Equal(-1, LCM(-1, -1))
+	assert.Equal(2, LCM(1, 2))
+	assert.Equal(18, LCM(3, 6, 9))
 }