Class IPUtil

A utility class that provides static methods for validating and formatting IP and CIDR strings. Unlike the IP class, these methods are stateless and ideal for one-off checks or transformations on varying inputs.

Hierarchy

  • IPBase
    • IPUtil

Methods

abbreviate checkEquality clean compareRanges contains containsAll containsAny equals equalsAll equalsAny getRangeObject isCIDR isIP isIPv4 isIPv4CIDR isIPv6 isIPv6CIDR isInAllRanges isInAnyRange isInRange lengthen parse parseAndStringify parseRange sanitize stringify validate

Methods

Staticabbreviate

  • abbreviate(ipStr, capitalize?, conditionPredicate?): null | string

  • Returns an abbreviated representation of an IP string.

    Examples:

    Inaccurate CIDRs are corrected automatically:

    • Input: fd12:3456:789a:1:0:0:0:1/64
    • Output: fd12:3456:789a:1::/64

    Parameters

    • ipStr: string

      IP or CIDR string to abbreviate.

    • Optionalcapitalize: boolean

      Whether to capitalize the output.

    • OptionalconditionPredicate: ConditionPredicate

      Optional condition for filtering valid IPs.

    Returns null | string

    Abbreviated string, or null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected StaticcheckEquality

  • checkEquality(ipObj, ipStr): null | boolean
  • Protected

    Checks if two IP addresses are equal.

    Parameters

    • ipObj: RangeObject

      Range object of the first IP.

    • ipStr: string | IP

      IP or CIDR string, or IP instance.

    Returns null | boolean

    null if the second input is invalid.

Staticclean

  • clean(str): string

  • Returns a trimmed string with all Unicode bidirectional characters removed.

    Unicode bidirectional characters are special invisible characters that can slip into cut-and-pasted strings, which are shown as red dots in WikiEditor. They can cause issues when parsing IP addresses.

    Parameters

    • str: string

    Returns string

    See

    MediaWikiTitleCodec::splitTitleString in MediaWiki core

Protected StaticcompareRanges

  • compareRanges(ip1, ip2, comparator): null | boolean
  • Protected

    Compares two IP address ranges to check for inclusion.

    Parameters

    • ip1: RangeObject

      Range object of the first IP.

    • ip2: string | IP

      IP string or IP instance to compare against.

    • comparator: "<" | ">"

      Use < if ip2 should contain ip1, or > if ip1 should contain ip2.

    Returns null | boolean

    null if ip2 is not a valid IP address.

Staticcontains

  • contains(cidrStr, ipStr): null | boolean

  • Checks whether a CIDR range contains the specified IP address.

    Parameters

    • cidrStr: string | IP

      The CIDR string or IP instance representing the containing range.

    • ipStr: string | IP

      The target IP address to check.

    Returns null | boolean

    true if cidrStr contains ipStr, false if not, or null if either input is invalid.

StaticcontainsAll

  • containsAll(cidrStr, ipArr): null | boolean

  • Checks whether a CIDR range contains all of the IP addresses in the array.

    Parameters

    • cidrStr: string | IP

      The CIDR string or IP instance representing the containing range.

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to test.

    Returns null | boolean

    true if all IPs are contained, false if any are not, or null if cidrStr is invalid or ipArr is not an array or an empty array.

StaticcontainsAny

  • containsAny(cidrStr, ipArr): null | number

  • Checks whether a CIDR range contains any of the IP addresses in the array.

    Parameters

    • cidrStr: string | IP

      The CIDR string or IP instance representing the containing range.

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to test.

    Returns null | number

    The index of the first match in ipArr, -1 if none match, or null if cidrStr is invalid.

Staticequals

  • equals(ipStr1, ipStr2): null | boolean

  • Checks whether two IP addresses are equal.

    Parameters

    • ipStr1: string | IP

      The first IP address to compare.

    • ipStr2: string | IP

      The second IP address to compare.

    Returns null | boolean

    true if the IPs are equal, false if not, or null if either input is invalid.

StaticequalsAll

  • equalsAll(ipStr, ipArr): null | boolean

  • Checks whether an IP address is equal to all addresses in a given array.

    Parameters

    • ipStr: string | IP

      The IP address to compare.

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to compare against.

    Returns null | boolean

    true if all addresses are equal to ipStr, false otherwise, or null if ipStr is invalid or ipArr is not an array or an empty array.

StaticequalsAny

  • equalsAny(ipStr, ipArr): null | number

  • Checks whether an IP address is equal to any address in a given array.

    Parameters

    • ipStr: string | IP

      The IP address to compare.

    • ipArr: (string | IP)[]

      An array of IP or CIDR strings or IP instances to check against.

    Returns null | number

    The index of the first match in ipArr, -1 if none match, or null if ipStr is invalid.

Protected StaticgetRangeObject

  • getRangeObject(ip): null | RangeObject
  • Protected

    Parses an IP string or instance into a range object.

    Parameters

    • ip: string | IP

      An IP/CIDR string or IP instance.

    Returns null | RangeObject

    Range object, or null if the input is not a valid IP.

StaticisCIDR

  • isCIDR(ipStr, mode?, options?): string | boolean

  • Checks whether the input is a valid CIDR (either IPv4 or IPv6).

    Parameters

    • ipStr: string

      The CIDR string to check.

    • Optionalmode: "strict"

      Require strict CIDR formatting if 'strict' is passed.

    • Optionaloptions: StringifyOptions

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisIP

  • isIP(ipStr, allowCidr?, options?): string | boolean

  • Checks whether the input is a valid IP or CIDR address.

    Parameters

    • ipStr: string

      The IP or CIDR string to check.

    • OptionalallowCidr: boolean | "strict" = false

      Whether to allow CIDRs, or require strict CIDR format.

    • Optionaloptions: StringifyOptions = {}

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisIPv4

  • isIPv4(ipStr, allowCidr?, options?): string | boolean

  • Checks whether the input is a valid IPv4 address or IPv4 CIDR.

    Parameters

    • ipStr: string

      The IPv4 or IPv4 CIDR string to check.

    • OptionalallowCidr: boolean | "strict" = false

      Whether to allow CIDRs, or require strict CIDR format.

    • Optionaloptions: StringifyOptions = {}

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisIPv4CIDR

  • isIPv4CIDR(ipStr, mode?, options?): string | boolean

  • Checks whether the input is a valid IPv4 CIDR.

    Parameters

    • ipStr: string

      The IPv4 CIDR string to check.

    • Optionalmode: "strict"

      Require strict CIDR formatting if 'strict' is passed.

    • Optionaloptions: StringifyOptions

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisIPv6

  • isIPv6(ipStr, allowCidr?, options?): string | boolean

  • Checks whether the input is a valid IPv6 address or IPv6 CIDR.

    Parameters

    • ipStr: string

      The IPv6 or IPv6 CIDR string to check.

    • OptionalallowCidr: boolean | "strict" = false

      Whether to allow CIDRs, or require strict CIDR format.

    • Optionaloptions: StringifyOptions = {}

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisIPv6CIDR

  • isIPv6CIDR(ipStr, mode?, options?): string | boolean

  • Checks whether the input is a valid IPv6 CIDR.

    Parameters

    • ipStr: string

      The IPv6 CIDR string to check.

    • Optionalmode: "strict"

      Require strict CIDR formatting if 'strict' is passed.

    • Optionaloptions: StringifyOptions

      Formatting options for corrected CIDRs.

    Returns string | boolean

    Returns true if valid, false if invalid, or a normalized CIDR string.

StaticisInAllRanges

  • isInAllRanges(ipStr, cidrArr): null | boolean

  • Checks whether a given IP address is within all CIDR ranges in the array.

    Parameters

    • ipStr: string | IP

      The IP address to evaluate.

    • cidrArr: (string | IP)[]

      An array of CIDR strings or IP instances to check against.

    Returns null | boolean

    true if the IP is within all CIDRs, false if not, or null if ipStr is invalid or cidrArr is not an array or an empty array.

StaticisInAnyRange

  • isInAnyRange(ipStr, cidrArr): null | number

  • Checks whether a given IP address is within any of the CIDR ranges in the array.

    Parameters

    • ipStr: string | IP

      The IP address to evaluate.

    • cidrArr: (string | IP)[]

      An array of CIDR strings or IP instances to check against.

    Returns null | number

    The index of the first matching CIDR in the array, -1 if none match, or null if ipStr is invalid.

StaticisInRange

  • isInRange(ipStr, cidrStr): null | boolean

  • Checks whether a given IP address is within the CIDR range of another.

    Parameters

    • ipStr: string | IP

      The target IP address to evaluate.

    • cidrStr: string | IP

      The CIDR string or IP instance representing the range.

    Returns null | boolean

    true if ipStr is within the range of cidrStr, false if not, or null if either input is invalid.

Staticlengthen

  • lengthen(ipStr, capitalize?, conditionPredicate?): null | string

  • Returns a fully expanded (lengthened) representation of an IP string.

    Examples:

    • 192.168.000.001
    • fd12:3456:789a:0001:0000:0000:0000:0000

    Inaccurate CIDRs are corrected automatically:

    • Input: fd12:3456:789a:1:0:0:0:1/64
    • Output: fd12:3456:789a:0001:0000:0000:0000:0000/64

    Parameters

    • ipStr: string

      IP or CIDR string to expand.

    • Optionalcapitalize: boolean

      Whether to capitalize the output.

    • OptionalconditionPredicate: ConditionPredicate

      Optional condition for filtering valid IPs.

    Returns null | string

    Expanded string, or null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected Staticparse

  • parse(ipStr, bitLen?): null | Parsed
  • Protected

    Parses a string potentially representing an IP or CIDR address.

    Parameters

    • ipStr: string

      The string to parse.

    • OptionalbitLen: number

      Optional bit length for CIDR parsing.

    Returns null | Parsed

    A parsed object, or null if:

    • ipStr is not a string.
    • It does not represent a valid IP address.
    • It contains an invalid CIDR bit length.

Protected StaticparseAndStringify

  • parseAndStringify(ipStr, options, conditionPredicate?): null | string
  • Protected

    Parses and stringifies an IP string with optional filtering.

    Parameters

    • ipStr: string

      IP or CIDR string to parse.

    • options: StringifyOptions

      Options for formatting.

    • OptionalconditionPredicate: ConditionPredicate

      A predicate to filter addresses by version and CIDR.

    Returns null | string

    null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected StaticparseRange

  • parseRange(parts, bitLen): RangeObject
  • Protected

    Returns the first and last IPs in the given range.

    Parameters

    • parts: number[]

      Decimal parts of the IP address.

    • bitLen: null | number

      Optional CIDR bit length.

    Returns RangeObject

Staticsanitize

  • sanitize(ipStr, capitalize?, conditionPredicate?): null | string

  • Returns a sanitized representation of an IP string.

    Examples:

    Inaccurate CIDRs are corrected automatically:

    • Input: fd12:3456:789a:1::1/64
    • Output: fd12:3456:789a:1:0:0:0:0/64

    Parameters

    • ipStr: string

      IP or CIDR string to sanitize.

    • Optionalcapitalize: boolean

      Whether to capitalize the output.

    • OptionalconditionPredicate: ConditionPredicate

      Optional condition for filtering valid IPs.

    Returns null | string

    Sanitized string, or null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected Staticstringify

  • stringify(decimals, suffix, options?): string
  • Protected

    Converts an array of decimal IP parts into a string.

    Parameters

    • decimals: number[]

      Array of decimal parts.

    • suffix: string

      Suffix to append (e.g., /24).

    • Optionaloptions: StringifyOptions = {}

    Returns string

Protected Staticvalidate

  • validate(ipStr, allowCidr, conditionPredicate?, options?): string | boolean
  • Protected

    Validates whether a string is a valid IP or CIDR address.

    • If allowCidr is true, CIDR suffixes are allowed.
    • If allowCidr is 'strict', the method returns a normalized CIDR string if the input is valid but not in canonical form.
    • If allowCidr is false, CIDR suffixes are disallowed.

    Return values:

    • true: The input is valid.
    • false: The input is invalid.
    • string: A corrected CIDR string (only if allowCidr === 'strict' and normalization is needed).

    Parameters

    • ipStr: string

      The IP or CIDR string to validate.

    • allowCidr: boolean | "strict"

      Whether to allow CIDRs, or require strict CIDR format.

    • OptionalconditionPredicate: ConditionPredicate

      Optional function to apply additional validation.

    • Optionaloptions: StringifyOptions

      Output formatting options (used only if returning a string).

    Returns string | boolean

    See above.

Settings

Member Visibility

On This Page

Methods