Printf وSprintf في Golang: مرجع أفعال التنسيق في fmt

للحزمة fmt ثلاث عائلات من دوال الطباعة، ولكل عائلة الأشكال الثلاثة نفسها:

package main

import (
	"fmt"
	"os"
)

func main() {
	name, score := "Ana", 92.456

	fmt.Println("Player", name, "scored", score)
	fmt.Printf("Player %s scored %.1f\n", name, score)

	msg := fmt.Sprintf("%s: %.0f points", name, score)
	fmt.Println(msg, len(msg))

	fmt.Fprintf(os.Stdout, "%-6s|%6.2f|\n", name, score)

	err := fmt.Errorf("player %q not found", "Ben")
	fmt.Println(err)
}

تضيف Println مسافات بين المعاملات وسطرًا جديدًا في النهاية. أما Printf فلا تضيف شيئًا: تكتب \n بنفسك. وتضيف Print مسافات فقط بين معاملين ليس أي منهما نصًا، وهذا مفاجئ بما يكفي لتستخدم معظم الشيفرات Println أو Printf.

أفعال التنسيق

عامة

package main

import "fmt"

type User struct {
	Name string
	Age  int
	Tags []string
}

func main() {
	u := User{Name: "Ana", Age: 31, Tags: []string{"admin"}}

	fmt.Printf("%v\n", u)
	fmt.Printf("%+v\n", u)
	fmt.Printf("%#v\n", u)
	fmt.Printf("%T\n", u)
	fmt.Printf("%v\n", &u)

	m := map[string]int{"b": 2, "a": 1}
	fmt.Printf("%v %#v\n", m, m)
}

%+v هو ما تلجأ إليه عند تتبّع الأخطاء. المؤشر إلى بنية يُطبع بالشكل &{...} لا كعنوان. وتُطبع الخرائط بمفاتيح مرتّبة، فتكون المخرجات ثابتة رغم أن ترتيب المرور على الخريطة عشوائي.

الأعداد الصحيحة

الأعداد العشرية

يقرّب %.2f القيمة الثنائية الدقيقة للعدد العشري، فتكون fmt.Sprintf("%.2f", 2.675) مساوية لـ 2.67: أقرب float64 إلى 2.675 أقل منه بقليل. لا تنسّق المال من عدد عشري أبدًا؛ احتفظ بالسنتات في عدد صحيح.

النصوص والبايتات

يطبع %s على []byte محتواها كنص؛ بينما يطبع %v الأرقام ([104 105]).

أنواع أخرى

العرض والدقة والحشو

بين % والفعل يمكنك وضع أعلام وعرض ودقة:

package main

import "fmt"

func main() {
	fmt.Printf("|%5d|%-5d|%05d|\n", 42, 42, 42)
	fmt.Printf("|%8.2f|%-8.2f|%.0f|\n", 3.14159, 3.14159, 2.5)
	fmt.Printf("|%10s|%-10s|%.3s|\n", "gopher", "gopher", "gopher")
	fmt.Printf("|%+d|%+d|\n", 5, -5)
	fmt.Printf("|%*d|\n", 7, 42) // width from an argument

	fmt.Println()
	items := []struct {
		name  string
		price float64
	}{{"Keyboard", 49.9}, {"Mouse", 19.5}, {"Monitor", 229}}
	for _, it := range items {
		fmt.Printf("%-10s %8.2f\n", it.name, it.price)
	}
}

لاحظ أن %.0f للقيمة 2.5 تطبع 2: تقرّب Go هنا النصف إلى الزوجي. يعدّ العرض الـ runes في النصوص لا أعمدة العرض، فقد تُفسد أحرف CJK والرموز التعبيرية محاذاة الجدول. للأعمدة المحاذاة ذات النصوص المتغيّرة، تتولّى text/tabwriter القياس نيابة عنك.

فهارس الوسائط

يختار %[n] وسيطًا بموقعه، وهذا يتيح لك إعادة استخدامه:

fmt.Printf("%[2]s %[1]s\n", "world", "hello") // hello world
fmt.Printf("%d %[1]x %[1]b\n", 10)             // 10 a 1010

Errorf و%w

تبني fmt.Errorf قيمة error من نص تنسيق. ومع %w تغلّف أيضًا خطأ آخر، فيستطيع المستدعون اكتشاف الأصل:

package main

import (
	"errors"
	"fmt"
	"os"
)

func loadConfig(path string) error {
	_, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("load config %s: %w", path, err)
	}
	return nil
}

func main() {
	err := loadConfig("/no/such/file.yaml")
	fmt.Println(err)
	fmt.Println("not exist?", errors.Is(err, os.ErrNotExist))

	// %v formats the same text but does not wrap
	flat := fmt.Errorf("load config: %v", os.ErrNotExist)
	fmt.Println("wrapped?", errors.Is(flat, os.ErrNotExist))
}

استخدم %w عندما قد يحتاج المستدعون إلى فحص السبب، و%v عندما تخفيه عمدًا. منذ Go 1.20 يمكن أن يحتوي استدعاء Errorf واحد عدة أفعال %w. صفحة معالجة الأخطاء تشرح التغليف بالتفصيل.

تنسيق مخصّص بـ String()

أي نوع له تابع String() string يتحكّم في طريقة عرض %v و%s وPrintln له:

package main

import "fmt"

type Money int64 // cents

func (m Money) String() string {
	return fmt.Sprintf("$%d.%02d", m/100, m%100)
}

func main() {
	price := Money(129950)
	fmt.Println(price)
	fmt.Printf("%v | %s | %d\n", price, price, price)
}

يتجاوز %d التابع String() ويطبع الرقم الأساسي. في أنواع الأخطاء التابع المقابل هو Error() string، وله الأسبقية على String().

عندما يكون الفعل خاطئًا

لا تسبّب fmt أبدًا panic بسبب تنسيق خاطئ. بل تطبع المشكلة في مكانها:

fmt.Printf("%d\n", "oops")
fmt.Printf("%d %d\n", 1)
fmt.Printf("%d\n", 1, 2)

%!d(string=oops)
1 %!d(MISSING)
1
%!(EXTRA int=2)

هذه المخرجات تصل غالبًا إلى الإنتاج لأنها لا توقف شيئًا. يكتشف go vet الحالات الثلاث وقت البناء:

./main.go:8:2: fmt.Printf format %d has arg "oops" of wrong type string
./main.go:9:2: fmt.Printf format %d reads arg #2, but call has 1 arg
./main.go:10:2: fmt.Printf call needs 1 arg but has 2 args

ملاحظات عن الأداء

تأخذ fmt كل وسيط كـ any وتفحص نوعه وقت التشغيل (وتلجأ إلى الانعكاس reflection للبنى والشرائح والخرائط)، وهذا مقبول للتسجيل والمخرجات لكنه ملموس في الحلقات الضيّقة. لتحويل رقم واحد، strconv.Itoa وstrconv.FormatFloat أسرع من Sprintf. ولبناء نص طويل في حلقة، اكتب في strings.Builder بـ fmt.Fprintf(&b, ...) بدل ضمّ نتائج Sprintf.