Skip to content

Unify missing-value handling with types.Nullable - #10

Merged
utahta merged 5 commits into
mainfrom
nullable-types
Jul 18, 2026
Merged

utahta merged 5 commits into
mainfrom
nullable-types

Conversation

@utahta

@utahta utahta commented Jul 18, 2026

Copy link
Copy Markdown
Owner

概要

J-Quants APIの欠損値表現(null・空文字・-・*・数値文字列)の処理を単一のジェネリック型 types.Nullable[T] に統一し、旧カスタム型と interface{} フィールドを全廃する。あわせて、配当情報で「未定(-)」と「非設定(空文字)」を区別して取得できるようにする。

背景

欠損値の処理がファイルごとに3方言(Float64String / Float64StringWithDash / interface{} + ローカルパースヘルパー7個)に分かれており、「どの型がどの欠損表現を扱えるか」が暗黙知になっていた。PR #9 の空文字→0化けバグはこの非対称性が原因。

変更内容

types.Nullable[T] の導入(破壊的変更)

  • null / ""(非設定)/ "*"(該当なし。ETFの上場比など)/ "-"(未定)/ 数値 / 数値文字列 を単一の型で受容
  • Get() (T, bool) / Ptr() *T / Or(def T) T / IsUndetermined() bool のアクセサ
  • MarshalJSON 実装により取得データの往復(キャッシュ保存など)が可能に
  • NullableInt64 は整数文字列を ParseInt、小数・指数表記を big.Rat で厳密に評価し、float64 の丸め(2^53超の精度損失・範囲外の飽和)を排除
  • 旧型5種(Float64String, Float64StringWithDash, StringWithDash, 未使用の Int64String, BoolString)と変換ヘルパーを削除

公開APIの改善(破壊的変更)

  • dividend: DivRate 等8フィールドと PayDate を Nullable 化し、「未定(-)」を IsUndetermined() で判別可能に。IsDividendRateUndecided() が非設定でも true を返していたバグを修正
  • futures / options: ナイトセッション・前場の四本値が interface{} → *float64 になり、型アサーション不要に。Has*Session() は nil を「データなし」として正しく判定
  • daily_margin_interest: interface{} フィールド8個 → types.NullableFloat64。「*」(ETFのため該当なし)を含む実データを正しく処理
  • 公開構造体の方針: 「absentか値か」だけのフィールドは素の *float64 を維持し、Nullable を公開するのは「未定」の区別が意味を持つ dividend のみ

utahta added 5 commits July 18, 2026 23:40
The J-Quants API represents missing values inconsistently across
endpoints: null (price endpoints), empty strings (financial
endpoints), and "-" for undetermined values (dividend endpoints),
with numbers appearing as both JSON numbers and strings.

types.Nullable[T] accepts all of these representations in one type,
distinguishes absent from undetermined via IsUndetermined(), and
implements MarshalJSON so decoded data can round-trip.
Dividend amounts and payable dates distinguish undetermined (-) from
not set (empty), but both decoded to nil and the distinction was
lost. Dividend now uses types.Nullable fields so callers can tell
them apart via IsUndetermined().

This also fixes IsDividendRateUndecided(), which returned true for
values that were merely not set, and drops RawDividend since Nullable
fields unmarshal directly.
Replace the three raw-parsing dialects (Float64String,
Float64StringWithDash, and interface{} fields with per-file parse
helpers) with types.Nullable across all services, and delete the
legacy types along with unused Int64String and BoolString.

Futures/Option night and morning session fields change from
interface{} to *float64, so callers no longer need type assertions.
Their Has*Session() methods now report absent data as false instead
of treating a nil interface{} as present.
The margin-alert endpoint uses two more special values: "-" when the
previous day's figure was not published, and "*" for ratios that do
not apply to ETFs. Nullable now accepts "*" as absent (without the
undetermined flag), and the eight interface{} fields move to
types.NullableFloat64, replacing type-assertion accessors.
NullableInt64 routed quoted integers and decimal/exponent forms
through float64, which silently loses precision above 2^53
("9007199254740993" became 9007199254740992) and let out-of-range
values saturate instead of failing ("92233720368547758070" became
MaxInt64, "-9223372036854775809" became MinInt64).

Parse plain integer strings with strconv.ParseInt and evaluate
decimal/exponent forms exactly from the original text with big.Rat,
so values like "9007199254740993.0" now decode to the exact integer
and unrepresentable values return an error. Non-integral values now
error instead of silently truncating.
@utahta
utahta merged commit 287a99e into main Jul 18, 2026
4 checks passed
@utahta
utahta deleted the nullable-types branch July 18, 2026 23:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant