Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Minor edits to guide #564

Merged
merged 1 commit into from
Feb 10, 2024
Merged

Minor edits to guide #564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions docs/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ The `ip` interpolator returns an `IpAddress`, the `ipv4` interpolator returns an

## IPv6 String Formats

IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead, you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.
IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.

```scala
import com.comcast.ip4s._
Expand Down Expand Up @@ -98,11 +98,11 @@ When compiling for the JVM, the various IP address classes have a `toInetAddress

```scala
val homeIA = ip"127.0.0.1".toInetAddress
// homeIA: java.net.InetAddress = /127.0.0.1
// homeIA: InetAddress = /127.0.0.1
val home4IA = ipv4"127.0.0.1".toInetAddress
// home4IA: java.net.Inet4Address = /127.0.0.1
// home4IA: Inet4Address = /127.0.0.1
val home6IA = ipv6"::1".toInetAddress
// home6IA: java.net.InetAddress = /0:0:0:0:0:0:0:1
// home6IA: InetAddress = /0:0:0:0:0:0:0:1
```

# Multicast
Expand Down Expand Up @@ -133,16 +133,16 @@ To construct instances of `Multicast[A]` and `SourceSpecificMulticast[A]`, we ca

```scala
val multicastIps = ips.flatMap(_.asMulticast)
// multicastIps: List[com.comcast.ip4s.Multicast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
// multicastIps: List[Multicast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
val ssmIps = ips.flatMap(_.asSourceSpecificMulticast)
// ssmIps: List[SourceSpecificMulticast.Strict[IpAddress]] = List(232.11.11.11, ff3b::11)
// ssmIps: List[Strict[IpAddress]] = List(232.11.11.11, ff3b::11)
```

It's common for source specific multicast to be used with group addresses outside the designated source specific multicast address range. To support such cases, use `asSourceSpecificMulticastLenient`:

```scala
val lenient = ips.flatMap(_.asSourceSpecificMulticastLenient)
// lenient: List[com.comcast.ip4s.SourceSpecificMulticast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
// lenient: List[SourceSpecificMulticast[IpAddress]] = List(224.10.10.10, 232.11.11.11, ff00::10, ff3b::11)
```

Additionally, the `SourceSpecificMulticast.Strict[A]` type provides the guarantee that the wrapped address is in the RFC defined source specific range.
Expand Down Expand Up @@ -172,17 +172,17 @@ case class AnySourceMulticastJoin[A <: IpAddress](group: Multicast[A]) extends M
case class SourceSpecificMulticastJoin[A <: IpAddress](source: A, group: SourceSpecificMulticast[A]) extends MulticastJoin[A]
```

`MulticastJoin` and its subtypes are parameterized by the address type in order to allow domain modelling that requires a V4, V6, or either. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.
`MulticastJoin` and its subtypes are parameterized by the address type in order to optionally constrain the join to V4 or V6 addresses. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.

To construct a `MulticastJoin`, we can use the `asm` and `ssm` methods in the `MulticastJoin` companion.

```scala
val j1 = MulticastJoin.ssm(ipv4"10.11.12.13", ssmipv4"232.1.2.3")
// j1: com.comcast.ip4s.MulticastJoin[Ipv4Address] = 10.11.12.13@232.1.2.3
// j1: MulticastJoin[Ipv4Address] = 10.11.12.13@232.1.2.3
val j2 = MulticastJoin.ssm(ipv4"10.11.12.13", ipv4"232.1.2.3".asSourceSpecificMulticast.get)
// j2: com.comcast.ip4s.MulticastJoin[Ipv4Address] = 10.11.12.13@232.1.2.3
// j2: MulticastJoin[Ipv4Address] = 10.11.12.13@232.1.2.3
val j3 = MulticastJoin.asm(mipv6"ff3b::10")
// j3: com.comcast.ip4s.MulticastJoin[Ipv6Address] = ff3b::10
// j3: MulticastJoin[Ipv6Address] = ff3b::10
```

# CIDR
Expand Down Expand Up @@ -251,7 +251,7 @@ A socket address is an IP address and a TCP/UDP port number. This is roughly mod
case class SocketAddress[+A <: IpAddress](ip: A, port: Port)
```

Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of contraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.
Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of constraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.

```scala
val s = SocketAddress(ipv4"127.0.0.1", port"5555")
Expand All @@ -268,7 +268,7 @@ On the JVM, a `SocketAddress` can be converted to a `java.net.InetSocketAddress`

```scala
val u = t.toInetSocketAddress
// u: java.net.InetSocketAddress = /[0:0:0:0:0:0:0:1]:5555
// u: InetSocketAddress = /[0:0:0:0:0:0:0:1]:5555
```

## Multicast Socket Addresses
Expand All @@ -292,11 +292,11 @@ The `Hostname` type models an RFC1123 compliant hostname -- limited to 253 total
val home = Hostname.fromString("localhost")
// home: Option[Hostname] = Some(localhost)
val ls = home.map(_.labels)
// ls: Option[List[Hostname.Label]] = Some(List(localhost))
// ls: Option[List[Label]] = Some(List(localhost))
val comcast = host"comcast.com"
// comcast: Hostname = comcast.com
val cs = comcast.labels
// cs: List[Hostname.Label] = List(comcast, com)
// cs: List[Label] = List(comcast, com)
```

## Hostname Resolution
Expand Down
6 changes: 3 additions & 3 deletions docs/src/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The `ip` interpolator returns an `IpAddress`, the `ipv4` interpolator returns an

## IPv6 String Formats

IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead, you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.
IPv6 addresses have a number of special string formats. The default format (what's returned by `toString`) adheres to [RFC5952](https://tools.ietf.org/html/rfc5952) -- e.g., maximal use of `::` to condense string length. If instead you want a string that does not use `::` and expresses each hextet as 4 characters, call `.toUncondensedString`. Note that the `toString` method never outputs a mixed string consisting of both V6 hextets and a dotted decimal V4 address. For example, the address consisting of 12 0 bytes followed by 127, 0, 0, 1 is rendered as `::7f00:1` instead of `::127.0.0.1`. `Ipv6Address.fromString` and `IpAddress.fromString` can parse all of these formats.

```scala mdoc:reset:to-string
import com.comcast.ip4s._
Expand Down Expand Up @@ -147,7 +147,7 @@ case class AnySourceMulticastJoin[A <: IpAddress](group: Multicast[A]) extends M
case class SourceSpecificMulticastJoin[A <: IpAddress](source: A, group: SourceSpecificMulticast[A]) extends MulticastJoin[A]
```

`MulticastJoin` and its subtypes are parameterized by the address type in order to allow domain modelling that requires a V4, V6, or either. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.
`MulticastJoin` and its subtypes are parameterized by the address type in order to optionally constrain the join to V4 or V6 addresses. The `AnySourceMulticastJoin` and `SourceSpecificMulticastJoin` types are exposed, instead of being kept as an implementation detail (or data constructor), for a similar reason -- to allow modelling where a type or function wants a very specific type like `SourceSpecificMulticastJoin[Ipv6Address]` while supporting other scnenarios that want something much more general like a `MulticastJoin[IpAddress]`.

To construct a `MulticastJoin`, we can use the `asm` and `ssm` methods in the `MulticastJoin` companion.

Expand Down Expand Up @@ -207,7 +207,7 @@ A socket address is an IP address and a TCP/UDP port number. This is roughly mod
case class SocketAddress[+A <: IpAddress](ip: A, port: Port)
```

Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of contraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.
Like we saw with `CIDR` and `MulticastJoin`, `SocketAddress` is polymorphic in address type, allowing expression of constraints like a socket address with an IPv6 IP. `SocketAddress` can be converted to and from a string representation, where V6 addresses are surrounded by square brackets.

```scala mdoc:nest:to-string
val s = SocketAddress(ipv4"127.0.0.1", port"5555")
Expand Down