x-iztro
x-iztroRustPythonGo

工具函数

索引换算、亮度与四化查表、命身宫推算、大限小限、四柱展示串。

这些函数是排盘算法的零件。自己实现斗数逻辑、或要复核某一步推算时用得上； 日常排盘不必直接调用。

参数与返回值中的标识都与语言无关，可直接与星盘上的 *Key 字段互操作。

FixIndex / FixIndex12

用途　把任意整数约束到循环区间。

斗数含义　十二宫首尾相接，从丑宫（索引 11）再走一格回到寅宫（索引 0）。 所有「顺数几格、逆数几格」的推算都靠这个回绕。

签名

func FixIndex(index int, max int) (int, error)
func FixIndex12(index int) int

参数

参数类型必填默认说明
indexint是—待修正的索引，可为负
maxint是—循环长度；传 0 取默认值 12，天干用 10。负数返回错误

返回值　落在 0..max 的索引（含 0，不含 max）。 FixIndex12 固定模 12、不返回错误——十二宫回绕直接用它。

示例

a, _ := iztro.FixIndex(-1, 0)
b, _ := iztro.FixIndex(13, 0)
c, _ := iztro.FixIndex(11, 10)

fmt.Println(a, b, c)
fmt.Println(iztro.FixIndex12(-1), iztro.FixIndex12(13))

_, err := iztro.FixIndex(0, -1)
fmt.Println(err)

输出

11 1 1
11 1
iztro: invalid max '-1': expected a positive integer

边界与陷阱

max 传 0 表示「用默认值 12」，不是「模 0」

这是复刻 iztro fixIndex(index, max = 12) 默认参数的写法，与 Go 的零值直觉相反： FixIndex(13, 0) 得到 1 而不是报错。十二宫回绕请直接用 FixIndex12， 省掉这个歧义与那个永远不会发生的 error。

负数按数学取模回绕（-1 → 11），不是截断到 0。 这两个函数在 Go 侧直接算，不往返 wasm。

EarthlyBranchToPalaceIndex

用途　地支转宫位索引。

斗数含义　十二宫的排列从寅宫起，而地支的自然顺序从子起，两者差两格。 这个函数负责这层换算：寅 → 0，卯 → 1，⋯，子 → 10，丑 → 11。

签名

func EarthlyBranchToPalaceIndex(branchKey string) (int, error)

返回值　int，0–11。

示例

yin, _ := iztro.EarthlyBranchToPalaceIndex(iztro.BranchYin)
zi, _ := iztro.EarthlyBranchToPalaceIndex(iztro.BranchZi)

fmt.Println(yin, zi)

输出

0 10

TimeToIndex

用途　小时数转时辰索引。

斗数含义　一天十二时辰，每时辰两小时，但子时横跨午夜被拆成早子时（0）与晚子时（12）， 因此索引有 13 个值。

签名

func TimeToIndex(hour uint8) (uint8, error)

参数

参数类型必填默认说明
houruint8是—小时数 0–23，越界返回错误

返回值　uint8，0–12——正好是排盘入口 timeIndex 参数的类型，可以直接传过去。

示例

a, _ := iztro.TimeToIndex(0)
b, _ := iztro.TimeToIndex(4)
c, _ := iztro.TimeToIndex(23)

fmt.Println(a, b, c)

_, err := iztro.TimeToIndex(24)
fmt.Println(err)

// 结果可直接喂给排盘入口
chart, err := iztro.BySolar("2000-8-16", b, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(chart.Time)

输出

0 2 12
iztro: invalid hour '24': expected 0-23
寅时

0 点为早子时，4 点为寅时，23 点为晚子时。排盘时不确定时辰索引，用这个函数换算。

GetAgeIndex

用途　由生年地支取小限起始宫位索引。

斗数含义　小限从固定的宫起，按虚岁逐年推移。起宫由生年地支所属的三合组决定： 寅午戌年起辰宫、申子辰年起戌宫、巳酉丑年起未宫、亥卯未年起丑宫。

签名

func GetAgeIndex(branchKey string) (int, error)

返回值　int，0–11。

示例

idx, _ := iztro.GetAgeIndex(iztro.BranchChen)
fmt.Println(idx)

输出

8

辰年属申子辰组，小限从戌宫起，戌宫的索引是 8。

GetBrightness

用途　查某颗星落在某宫时的亮度。

签名

func GetBrightness(starKey string, palaceIndex int, config *Config) (string, error)

参数

参数类型必填默认说明
starKeystring是—星耀标识
palaceIndexint是—宫位索引，越界会对 12 取模
config*Config是—自定义亮度表会改变结果

返回值　亮度标识；该星没有亮度表时返回空串。

示例

a, _ := iztro.GetBrightness(iztro.StarZiweiMaj, 4, nil)
b, _ := iztro.GetBrightness(iztro.StarLucunMin, 0, nil)

fmt.Printf("%q %q\n", a, b)

输出

"miao" ""

紫微在午宫（索引 4）庙；禄存没有亮度表。

GetMutagen / GetMutagensByHeavenlyStem

用途　查天干四化。

斗数含义　十天干各自固定指派四颗星化禄、权、科、忌。 GetMutagen 问「这颗星在这个天干下化什么」， GetMutagensByHeavenlyStem 问「这个天干化哪四颗星」。

签名

func GetMutagen(starKey string, stemKey string, config *Config) (string, error)
func GetMutagensByHeavenlyStem(stemKey string, config *Config) ([]string, error)

返回值　GetMutagen 返回四化标识，该星不在此天干的四化表内时返回空串。 GetMutagensByHeavenlyStem 返回四项切片，顺序为禄、权、科、忌。

示例

a, _ := iztro.GetMutagen(iztro.StarTaiyangMaj, iztro.StemGeng, nil)
b, _ := iztro.GetMutagen(iztro.StarZiweiMaj, iztro.StemGeng, nil)
c, _ := iztro.GetMutagensByHeavenlyStem(iztro.StemGeng, nil)

fmt.Printf("%q %q\n%v\n", a, b, c)

输出

"sihuaLu" ""
[taiyangMaj wuquMaj taiyinMaj tiantongMaj]

GetSoulAndBody

用途　由农历月索引、时辰与年干推命宫、身宫。

斗数含义　命宫是整张盘的起点：从寅宫起正月，顺数到生月，再从生月逆数到生时。 身宫用同样的起点但顺数生时。命宫的天干由五虎遁从年干推得。

签名

func GetSoulAndBody(monthIndex int, timeIndex uint8, yearlyStemKey string) (*SoulAndBody, error)

参数

参数类型必填默认说明
monthIndexint是—农历月索引，正月为 0；由 FixLunarMonthIndex 求得
timeIndexuint8是—时辰索引 0–12
yearlyStemKeystring是—生年天干标识

返回值　*SoulAndBody，含 SoulIndex、BodyIndex、HeavenlyStemOfSoul、EarthlyBranchOfSoul。

示例

sb, _ := iztro.GetSoulAndBody(6, 2, iztro.StemGeng)
fmt.Printf("%+v\n", *sb)

输出

{SoulIndex:4 BodyIndex:8 HeavenlyStemOfSoul:renHeavenly EarthlyBranchOfSoul:wuEarthly}

GetFiveElementsClass

用途　由命宫干支推五行局。

斗数含义　五行局（水二、木三、金四、土五、火六）决定两件大事： 紫微星的起宫位置，以及大限的起运岁数。

签名

func GetFiveElementsClass(stemKey string, branchKey string) (string, error)

返回值　五行局标识。

示例

fe, _ := iztro.GetFiveElementsClass(iztro.StemRen, iztro.BranchWu)
fmt.Println(fe)

输出

wood3rd

GetPalaceNames

用途　由命宫索引推十二宫名。

斗数含义　命宫定下后，其余十一宫按固定顺序逆时针排开： 命、兄弟、夫妻、子女、财帛、疾厄、迁移、仆役、官禄、田宅、福德、父母。

签名

func GetPalaceNames(soulIndex int) ([]string, error)

返回值　十二项标识切片（不是译名），按宫位索引排列—— 第 i 项就是 chart.Palaces[i] 的 NameKey。 与 GetConstants().Palaces 不同：那个给的是宫名的固定排列顺序，与具体盘无关。

示例

names, _ := iztro.GetPalaceNames(4)
fmt.Println(names[:4])

输出

[wealthPalace childrenPalace spousePalace siblingsPalace]

命宫在索引 4，因此索引 0（寅宫）是财帛。

GetDecadalsAndAges

用途　由命宫索引与五行局推十二宫的大限与小限。

斗数含义　大限起运岁数由五行局决定（水二局 2 岁起、木三局 3 岁起，依此类推）， 顺逆由性别阴阳与年支阴阳决定；小限起宫由年支决定，按虚岁逐年推移。

签名

func GetDecadalsAndAges(
    soulIndex int, fiveElementsClass string, gender Gender, yearlyStemKey, yearlyBranchKey string,
) (DecadalsAndAges, error)

参数

参数类型必填默认说明
soulIndexint是—命宫宫位索引
fiveElementsClassstring是—五行局标识
genderGender是—GenderMale 或 GenderFemale
yearlyStemKeystring是—年干标识
yearlyBranchKeystring是—年支标识

返回值　DecadalsAndAges，含 Decadals []Decadal 与 Ages [][]int，均按宫位索引排列。

Decadal 与宫位上的 palace.Decadal 是同一个类型：

字段类型说明
Range[2]int大限起止虚岁，含两端
HeavenlyStem / HeavenlyStemKeystring大限天干的译名 / 标识
EarthlyBranch / EarthlyBranchKeystring大限地支的译名 / 标识

示例

da, _ := iztro.GetDecadalsAndAges(4, "wood3rd", iztro.GenderFemale, iztro.StemGeng, iztro.BranchChen)

fmt.Printf("%+v\n", da.Decadals[0])
fmt.Println(da.Ages[0][:3])

输出

{Range:[43 52] HeavenlyStem:戊 HeavenlyStemKey:wuHeavenly EarthlyBranch:寅 EarthlyBranchKey:yinEarthly}
[9 21 33]

边界与陷阱

整盘排出的每个宫位上已有 Decadal 与 Ages 字段，内容与本函数一致， 连译名与标识两组字段的含义都相同。这个函数用于不排整盘、只推大限小限的场合。

译名固定按 zh-CN

这个函数不收 language 参数，Decadal 的译名字段一律是中文。 要别的语言用 HeavenlyStemKey 走 Translate。

FixLunarMonthIndex / FixLunarDayIndex

用途　求修正后的农历月索引与日索引。

斗数含义　闰月归属与晚子时归属是斗数两个长期有争议的边界，这两个函数把规则落定： 闰月十六日起按下月算（可关，且晚子时不进位），晚子时的日索引属次日。

签名

func FixLunarMonthIndex(lunarMonth int, lunarDay int, isLeap bool, timeIndex uint8, fixLeap bool) (int, error)
func FixLunarDayIndex(lunarDay int, timeIndex uint8) (int, error)

返回值　月索引为 0-based（正月为 0）；日索引在晚子时不减一。

FixLunarMonthIndex 进位要同时满足四个条件：isLeap 为真、fixLeap 为真、 lunarDay 大于 15、且 timeIndex 不是 12。四者缺一，就按本月算。

示例

m, _ := iztro.FixLunarMonthIndex(7, 17, false, 2, true)
d1, _ := iztro.FixLunarDayIndex(17, 2)
d2, _ := iztro.FixLunarDayIndex(17, 12)

fmt.Println(m, d1, d2)

输出

6 16 17

七月非闰月，索引为 6；十七日在寅时减一得 16，在晚子时属次日故保持 17。

TranslateChineseDate

用途　把四柱干支拼成展示串。

签名

func TranslateChineseDate(pillars [4][2]string, language Language) (string, error)

参数

参数类型必填默认说明
pillars[4][2]string是—四柱标识 [年, 月, 日, 时]，每柱为 [天干, 地支]
languageLanguage是—盘面语言

返回值　词条均为单字符时柱内紧凑相连、柱间空格； 任一词条为多字符时柱内空格、柱间 -。

示例

s, _ := iztro.TranslateChineseDate([4][2]string{
    {iztro.StemGeng, iztro.BranchChen},
    {iztro.StemJia, iztro.BranchShen},
    {iztro.StemBing, iztro.BranchWu},
    {iztro.StemGeng, iztro.BranchYin},
}, "zh-CN")
fmt.Println(s)

// 星盘上的四柱标识可直接取
s2, _ := iztro.TranslateChineseDate(chart.RawDates.ChineseDate.PillarKeys(), iztro.LanguageZhCN)
fmt.Println(s2)

输出

庚辰 甲申 丙午 庚寅
庚辰 甲申 丙午 庚寅

边界与陷阱

干支标识非法时返回错误。定长数组保证了柱数必为四，不必再校验长度。

MergeStars

用途　把多组「十二宫星耀」按宫位合并成一组。

斗数含义　安星是分批进行的：主星、辅星、杂耀各出一组十二宫列表。 要把它们并成一张完整盘面时用这个函数。

签名

func MergeStars(groups ...[][]Star) ([][]Star, error)

参数

参数类型必填默认说明
groups...[][]Star是—若干组十二宫星耀，每组长度须为 12

返回值　合并后的十二宫切片，同宫内按传入顺序首尾相接。

示例

birth := iztro.StarBirth{SolarDate: "2000-8-16", TimeIndex: 2, Gender: iztro.GenderFemale, FixLeap: true}
major, _ := iztro.GetMajorStar(birth)
minor, _ := iztro.GetMinorStar(birth)

merged, _ := iztro.MergeStars(major, minor)
names := []string{}
for _, s := range merged[0] {
    names = append(names, s.Name)
}
fmt.Println(names)

输出

[武曲 天相 天马]

边界与陷阱

某一组的长度不是 12 时返回错误。这是纯本地实现，不经 wasm。

轻量查询

不排整盘就能拿到的生肖、星座与命宫主星。

安星模块

按出生数据取某一组星耀的落宫。

本页目录

FixIndex / FixIndex12EarthlyBranchToPalaceIndexTimeToIndexGetAgeIndexGetBrightnessGetMutagen / GetMutagensByHeavenlyStemGetSoulAndBodyGetFiveElementsClassGetPalaceNamesGetDecadalsAndAgesFixLunarMonthIndex / FixLunarDayIndexTranslateChineseDateMergeStars