aznum2words

README

---

AzNum2Words - Azərbaycan dilində ədədlərin sözlə yazılışı(və ya təsviri) üçün nəzərdə tutulan Go dilində yazılmış, açıq qaynaqlı kitabxanadır.

---

Məqsəd | Goal

Azərbaycan dilində ədədlərin(və ya rəqəmlərin) sözlə yazılış təsvirinə ehtiyac yarandığı hallar olur. Proqram səviyyəsində bu kimi ehtiyacları qarşılamaq üçün vahid bir kitabxananın olması, proqramçıların işini xeyli asanlaşdırır. Kitabxana tam və ya kəsr ədədlərin Azərbaycan dilində sözlə yazılışı(və ya təsviri) üçün nəzərdə tutulub.

---

İstifadə formaları | Usage forms

Həm library, həm də command-line tool kimi istifadə edilə bilər. Bundan əlavə web-app kimi də istifadə edərək mövcud sisteminə integrasiya etmək mümkündür.

Bu kitabxana vasitəsilə - müsbət, mənfi tam və ya kəsr ədədlərin sözlə yazılış təsvirini əldə etmək mümkündür.

---

İstifadə yerləri | Use cases

Azərbaycan dilində ədədlərin təsvirinə ehtiyac duyulan hallarda istifadə oluna bilər.

• Statistik hesabatların tərtib olunması.
• Maliyyə əməliyyatları zamanı məbləğin sözlə təsvir olunması.
• Hüquqi və maliyyə sənədləri tez-tez çaşqınlığın qarşısını almaq və dəqiqliyi təmin etmək üçün rəqəmlərin ifadə sözünün istifadəsini tələb edir.
• Çek yazarkən, dəyişikliklərin və ya saxtakarlığın qarşısını almaq üçün rəqəmsal məbləğə əlavə olaraq məbləğin sözlə ifadəsini də yazmaq adi bir təcrübədir.

---

Özəlliklər | Features

• Tam ədədlərin sözlə təsvir olunması
• Kəsr ədədlərin sözlə təsvir olunması
• Müsbət vəya mənfi ədədlərin sözlə təsvir olunması
• Söz ilə təsvir oluna biləcək maksimum tam ədəd: 10^63
• Söz ilə təsvir oluna biləcək minumum kəsr ədəd: (10^-15)

---

Kitabxananın proyektə əlavə edilməsi | Add library into the project

go get github.com/egasimov/aznum2words@latest

Kitabxana kimi istifadə qaydası | Guideline for using as library

package main

import (
	"fmt"
	"github.com/egasimov/aznum2words"
)

func main() {
	// in real use, do not discard errors, rather handle it properly :)
	result1, _ := aznum2words.SpellNumber("-95412")
	result2, _ := aznum2words.SpellNumber("-2.7021")
	result3, _ := aznum2words.SpellNumber("5611113210")

	fmt.Println(result1)
	fmt.Println(result2)
	fmt.Println(result3)
}

NƏTİCƏ | OUTPUT

mənfi doxsan beş min dörd yüz on iki
mənfi iki tam on mində yeddi min iyirmi bir
beş milyard altı yüz on bir milyon bir yüz on üç min iki yüz on

---

CLI kimi quraşdırılması | CLI-Installation

// installs the binaries into $GOPATH/bin
go install github.com/egasimov/aznum2words/cmd/aznum2words-cli@latest

CLI kimi istifadə qaydası | Guideline for using as CLI app

$ aznum2words-cli -- 12.3
on iki tam onda üç

$ aznum2words-cli -- -12.3
mənfi on iki tam onda üç

---

Web app kimi quraşdırılması | Web-App Installations

// Clone the repository
git clone https://github.com/egasimov/aznum2words.git@latest

Web app kimi istifadə qaydası | Guideline for using as Web app

$ cd ./cmd/aznum2words-webapp/ 
$ go run ./aznum2words-webapp.go

curl --location 'http://localhost:8080/api/v1/conversion/to-word' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "number": "123.45"
}'

Qeyd: open-api-spec contract istifadə edərək online swagger-ui, Postman kimi alətlər ilə REST APİ-ni interaktiv test etmək mümkündür.

---

Test caseləri yoxlanması | Check test cases

go test ./...

Benchmark yoxlanılması

go test -bench=. -run=^# -benchmem

---

Versiyalar | Releases

Kitabxananın versiyaları Semver yanaşması ilə tənzimlənir.

---

Lisenziya | License

Kitabxana MIT Lisenziya altında lisenziyalaşdırılmışdır. Ətraflı məlumat üçün LICENSE faylını nəzərdən keçirin.

---

Proyektə necə dəstək olmaq olar | How to contribute to project ?

Proyektə contribute etmək üçün aşağıdakı təlimatları nəzərə ala bilərsiniz.

Testləri olmayan vəya nəzərə alınmayan PRlar qəbul edilməyəcək

1. Reponu fork et
2. Yeni feature branch yarat (git checkout -b my-new-feature)
3. Dəyişiklikləri commit et (git commit -am 'Added some feature')
4. Local branchı origin(remote repo) push et (git push origin my-new-feature)
5. Yeni Pull Request yarat

---

Contributorlar

Bu layihəyə aşağıdakı şəxslər töhfə verib:

Documentation

Index

• Constants
• Variables
• func SpellNumber(numberAsStr string) (string, error)

Constants

const (
	MaxNumberDigitCount int = 66
	MaxNumberScaleCount int = 15
)

const (

	//single digits numbers
	ZeroAsString  string = "sıfır"  // 0
	OneAsString   string = "bir"    // 1
	TwoAsString   string = "iki"    // 2
	ThreeAsString string = "üç"     // 3
	FourAsString  string = "dörd"   // 4
	FiveAsString  string = "beş"    // 5
	SixAsString   string = "altı"   // 6
	SevenAsString string = "yeddi"  // 7
	EightAsString string = "səkkiz" // 8
	NineAsString  string = "doqquz" // 9

	//two digits numbers
	TenAsString     string = "on"     // 10
	TwentyAsString  string = "iyirmi" // 20
	ThirtyAsString  string = "otuz"   // 30
	FortyAsString   string = "qırx"   // 40
	FiftyAsString   string = "əlli"   // 50
	SixtyAsString   string = "altmış" // 60
	SeventyAsString string = "yetmiş" // 70
	EightyAsString  string = "səksən" // 80
	NinetyAsString  string = "doxsan" // 90

	//three digits numbers
	HundredAsString string = "yüz" // 10^2

	//others
	ThousandAsString        string = "min"            // 10^3
	MillionAsString         string = "milyon"         // 10^6
	BillionAsString         string = "milyard"        // 10^9
	TrillionAsString        string = "trilyon"        // 10^12
	QuadrillionAsString     string = "kvadrilyon"     // 10^15
	QuintillionAsString     string = "kvintilyon"     // 10^18
	SextillionAsString      string = "sekstilyon"     // 10^21
	SeptillionAsString      string = "septilyon"      // 10^24
	OctillionAsString       string = "oktilyon"       // 10^27
	NonillionAsString       string = "nonilyon"       // 10^30
	DecillionAsString       string = "desilyon"       //10^33
	UndecillionAsString     string = "undesilyon"     //10^36
	DodecillionAsString     string = "dodesilyon"     //10^39
	TredecillionAsString    string = "tredesilyon"    //10^42
	CathodecillionAsString  string = "katordesilyon"  //10^45
	KendecillionAsString    string = "kendesilyon"    //10^48
	SexdecillionAsString    string = "seksdesilyon"   //10^51
	SeptendecillionAsString string = "septendesilyon" //10^54
	OctodecillionAsString   string = "oktodesilyon"   //10^57
	NovedesillionAsString   string = "novemdesilyon"  //10^60
	VigintillionAsString    string = "vigintilyon"    //10^63
)

const (
	NegativeAsWord        string = "mənfi" // -
	SeparatorAsWord       string = "tam"
	DecimalPointSeparator string = "."
)

Variables

var (
	ErrInvalidArgument      = errors.New("an invalid argument provided")
	ErrTooBigNumber         = errors.New("max supported number digits is 66")
	ErrTooBigScale          = errors.New("max supported scale for real numbers is 15")
	ErrUnexpectedBehaviour  = errors.New("an unexpected behaviour occurred")
	ErrUnsupportedOperation = errors.New("an operation is not supported")
)

Functions

func SpellNumber

func SpellNumber(numberAsStr string) (string, error)

SpellNumber takes a string input numberAsStr and returns a string and an error. The purpose of the function is to convert a given number string into its equivalent Azerbaijani words. The function starts by validating the input string using a regular expression. If the input string is not in a valid format, it returns an error. If the input string is valid, it then checks whether it is a floating-point number or an integer number. Depending on this, it calls either `handleFloatingPointNumberConversion` or `handleIntegerNumberConversion` to convert the number into its equivalent Azerbaijani words. If the conversion is successful, the function returns the result as a string. If an error occurs during the conversion, the function returns an error.