quran-meta/lib_cjs/ayahStringSplitter.d.cts

Library with meta data and functionality related to Holy Quran

import { SurahAyahSegment } from "./types.cjs";

//#region src/ayahStringSplitter.d.ts

/**
 * Splits a string representation of Quran reference into surah and ayah components
 * @param str - The string to parse, expected format: "surah:ayah" or "surah:ayahStart-ayahEnd"
 * @param isStrict - If true, enforces strict format checking. Defaults to true. If false, allows for additional characters in the string
 * @returns A tuple containing surah number and either a single ayah number or a range [start, end]
 * @throws {@link Error} If the string format is invalid
 * @throws {@link Error} If surah number is invalid
 * @throws {@link Error} If ayah number(s) are invalid
 * @throws {@link sError} If ayah range is invalid (start should be less than end)
 * @example
 * ```ts
 * ayahStringSplitter("2:255") // returns [2, 255]
 * ayahStringSplitter("1:1-7") // returns [1, [1, 7]]
 * ```
 */
declare function ayahStringSplitter(str: string, isStrict?: boolean): SurahAyahSegment;
/**
 * Splits a string containing surah and ayah numbers into their numeric components.
 *
 * @param str - Input string containing numbers separated by non-digits (e.g., "2:255" or "2 255" or "2-255")
 * @returns An object containing the parsed numbers, or null if parsing fails
 *          - ayah: The ayah number if present
 *          - ayahTo: The ending ayah number if a range is specified
 *          - surahOrAyah: The surah number
 * @example
 * stringNumberSplitter("2:255") // returns { ayah: 255, ayahTo: 0, surahOrAyah: 2 }
 * stringNumberSplitter("2:255-260") // returns { ayah: 255, ayahTo: 260, surahOrAyah: 2 }
 * stringNumberSplitter("invalid") // returns null
 */
declare function string2NumberSplitter(str: string): {
  ayah?: number;
  ayahTo?: number;
  surahOrAyah?: number;
} | null;
/**
 * Splits a string in the format "surah:ayah" or "surah:ayah-ayah" into its numeric components.
 *
 * @param str - The input string to parse in the format "surah:ayah" or "surah:ayah-ayah"
 * @returns An object containing the parsed numbers:
 *          - surahOrAyah: The surah number
 *          - ayah: The first or only ayah number
 *          - ayahTo: The ending ayah number (if range specified)
 * @throws {@link Error} When the input string format is invalid or contains non-numeric values
 *
 * @example
 * string2NumberSplitterStrict("2:255")    // returns { surahOrAyah: 2, ayah: 255, ayahTo: NaN }
 * string2NumberSplitterStrict("2:255-260") // returns { surahOrAyah: 2, ayah: 255, ayahTo: 260 }
 */
declare function string2NumberSplitterStrict(str: string): {
  ayah?: number;
  ayahTo?: number;
  surahOrAyah?: number;
} | null;
//#endregion
export { ayahStringSplitter, string2NumberSplitter, string2NumberSplitterStrict };