Jule Manual

Appearance

std/net ​

Index ​

Variables
fn JoinHostPort(host: str, port: str): str
fn SplitHostPort(hostport: str)!: (host: str, port: str)
fn Listen(network: Network, addr: str)!: Listener
fn ListenUDP(network: Network, addr: str)!: &UDPConn
fn Dial(network: Network, addr: str)!: Conn
fn DialTimeout(network: Network, addr: str, timeout: time::Duration)!: Conn
fn IPv4(a: byte, b: byte, c: byte, d: byte): IP
trait Addr
trait Conn
trait Listener
struct TCPListener
    static fn Bind(addr: str)!: &TCPListener
    static fn Dial(addr: str)!: &TCPConn
    static fn DialTimeout(addr: str, timeout: time::Duration)!: &TCPConn
    fn Accept(self)!: Conn
    fn Network(self): Network
    fn Close(mut self)!
struct TCPConn
    fn Read(mut self, mut buf: []byte)!: int
    fn Write(mut self, buf: []byte)!: int
    fn SetReadTimeout(mut self, timeout: time::Duration)!
    fn SetWriteTimeout(mut self, timeout: time::Duration)!
    fn Network(self): Network
    fn Close(mut self)!
struct TCPAddr
    static fn Resolve(mut network: Network, addr: str)!: &TCPAddr
    fn Network(self): str
    fn Str(self): str
struct UDPAddr
    static fn Resolve(mut network: Network, addr: str)!: &UDPAddr
    fn Network(self): str
    fn Str(self): str
type HardwareAddr
    static fn Parse(addr: str)!: HardwareAddr
    fn Str(self): str
struct UDPConn
    static fn Bind(addr: str)!: &UDPConn
    static fn Dial(addr: str)!: &UDPConn
    fn Read(mut self, mut buf: []byte)!: (n: int)
    fn Write(mut self, buf: []byte)!: (n: int)
    fn SetReadTimeout(mut self, timeout: time::Duration)!
    fn SetWriteTimeout(mut self, timeout: time::Duration)!
    fn Network(self): Network
    fn Close(mut self)!
type IP
    static fn Empty(): IP
    fn Empty(self): bool
    fn Equal(self, other: IP): bool
    fn IsUnspecified(self): bool
    fn IsLoopback(self): bool
    fn IsPrivate(self): bool
    fn To4(mut self): IP
    fn To16(mut self): IP
    fn Str(self): str
enum Error
enum AddrError
enum Network

Variables ​

jule
const IPv4Len = 1 << 2

Length of IPv4 address in bytes.

jule
static mut Broadcast = IPv4(255, 255, 255, 255)

The IPv4 address known as limited broadcast. The IP that returned is statically allocated and mutable.

jule
static mut IPv4AllSystems = IPv4(224, 0, 0, 1)

The IPv4 address known as all systems. The IP that returned is statically allocated and mutable.

jule
static mut IPv4AllRouters = IPv4(224, 0, 0, 2)

The IPv4 address known as all routers. The IP that returned is statically allocated and mutable.

jule
static mut IPv4Zero = IPv4(0, 0, 0, 0)

The IPv4 address known as all zeros. The IP that returned is statically allocated and mutable.

jule
const IPv6Len = 1 << 4

Length of IPv6 address in bytes.

jule
static mut IPv6Zero = IP([ ... ])

The IPv6 address known as all zeros. The IP that returned is statically allocated and mutable.

jule
static mut IPv6Unspecified = IP([ ... ])

The IPv6 address known as unspecified. The IP that returned is statically allocated and mutable.

jule
static mut IPv6Loopback = IP([ ... ])

The IPv6 address known as loopback. The IP that returned is statically allocated and mutable.

jule
static mut IPv6InterfaceLocalAllNodes = IP([ ... ])

The IPv6 address known as interterface local all nodes. The IP that returned is statically allocated and mutable.

jule
static mut IPv6LinkLocalAllNodes = IP([ ... ])

The IPv6 address known as link local all nodes. The IP that returned is statically allocated and mutable.

jule
static mut IPv6LinkLocalAllRouters = IP([ ... ])

The IPv6 address known as link local all routers. The IP that returned is statically allocated and mutable.

JoinHostPort ​

jule
fn JoinHostPort(host: str, port: str): str

Combines host and port into a network address of the form "host:port". If host contains a colon, as found in literal IPv6 addresses, then JoinHostPort returns "[host]:port".

See the [Dial] function for a description of the host and port parameters.

SplitHostPort ​

jule
fn SplitHostPort(hostport: str)!: (host: str, port: str)

Splits a network address of the form "host:port", "host%zone:port", "[host]:port" or "[host%zone]:port" into host or host%zone and port.

A literal IPv6 address in hostport must be enclosed in square brackets, as in "[::1]:80", "[::1%lo0]:80".

See the [Dial] function for a description of the hostport parameter, and host and port results.

Exceptionals are always will be AddrError.

Listen ​

jule
fn Listen(network: Network, addr: str)!: Listener

Listens the address on the named network. It will forward any exceptional from network connectors.

For UDP network, the [ListenUDP] function should be used. If the network parameter is points udp network, function will panic.

See the [Dial] function for a description of the network and addr parameters.

ListenUDP ​

jule
fn ListenUDP(network: Network, addr: str)!: &UDPConn

Listens the address on the named network. It will forward any exceptional from network connectors. Just for UDP networks.

See the [Dial] function for a description of the network and addr parameters.

Dial ​

jule
fn Dial(network: Network, addr: str)!: Conn

Connects to the address on the named network. Network should be one of the fields of the Network enum. The addr parameter is should represent valid address according to network.

For TCP:

The address has the form "host:port".
The host must be a literal IP address, or a host name that can be
resolved to IP addresses such as "localhost".
The port must be a literal port number or a service name.
If the host is a literal IPv6 address it must be enclosed in brackets,
as in "[2001:db8::1]:80" or "[fe80::1%zone]:80".
The zone specifies the scope of the literal IPv6 address as defined
in RFC 4007. The functions [JoinHostPort] and [SplitHostPort] manipulate
a pair of host and port in this form.

If network is Tcp4, it will accept only IPv4 addresses and if address is IPv6,
will try to convert IPv4. If network is Tcp6, it will accept only IPv6 address and
address is IPv4, will not try to convert IPv6. If network is Tcp, it will use Tcp4
for empty addresses and try for IPv4 if possible. If address is IPv4 or IPv6 which
is converted to IPv4 successfully, will use Tcp4, otherwise IPv6 and Tcp6 preferred.

For UDP:

The address has the form "host:port".
The host must be a literal IP address, or a host name that can be
resolved to IP addresses such as "localhost".
The port must be a literal port number or a service name.
If the host is a literal IPv6 address it must be enclosed in brackets,
as in "[2001:db8::1]:80" or "[fe80::1%zone]:80".
The zone specifies the scope of the literal IPv6 address as defined
in RFC 4007. The functions [JoinHostPort] and [SplitHostPort] manipulate
a pair of host and port in this form.

If network is Udp4, it will accept only IPv4 addresses and if address is IPv6,
will try to convert IPv4. If network is Udp6, it will accept only IPv6 address and
address is IPv4, will not try to convert IPv6. If network is Udp, it will use Udp4
for empty addresses and try for IPv4 if possible. If address is IPv4 or IPv6 which
is converted to IPv4 successfully, will use Udp4, otherwise IPv6 and Udp6 preferred.

It will forward any exceptional from network connectors.

DialTimeout ​

jule
fn DialTimeout(network: Network, addr: str, timeout: time::Duration)!: Conn

Same as Dial, but uses timeout. For UDP networks, timeout will be ignored. Timeout precision is microseconds. If the timeout is below one microsecond it will be ignored. If timeout is invalid or out of range, throws exceptional with Error.InvalidTimeout.

IPv4 ​

jule
fn IPv4(a: byte, b: byte, c: byte, d: byte): IP

Returns the IP address (in 16-byte form) of the IPv4 address a.b.c.d.

Addr ​

jule
trait Addr {
	// Returns name of the network.
	fn Network(self): str

	// String form of address.
	fn Str(self): str
}

Represents a network end point address.

Conn ​

jule
trait Conn {
	io::Reader
	io::Writer
	io::Closer
	fn SetReadTimeout(mut self, timeout: time::Duration)!
	fn SetWriteTimeout(mut self, timeout: time::Duration)!
	fn Network(self): Network
}

Common connection behavior. Inherits the io::Reader, io::Writer, and io::Closer traits.

Listener ​

jule
trait Listener {
	io::Closer
	fn Accept(self)!: Conn
	fn Network(self): Network
}

Common listener behavior. Inherits the io::Closer trait.

TCPListener ​

jule
struct TCPListener {
	// NOTE: contains filtered hidden or unexported fields
}

TCP listener. In most cases, represents TCP server.

Implemented Traits ​

  • Listener

Bind ​

jule
static fn Bind(addr: str)!: &TCPListener

Binds new TCP listener and starts listening given address. Returns relevant created &TCPListener if success. If addr is not a valid address, it will forward relevant parse exceptionals. In addition, any bind and listening error will be return as exceptional.

See the [Dial] function for a description of the addr parameter.

Dial ​

jule
static fn Dial(addr: str)!: &TCPConn

Connects to TCP listener by given address. Returns relevant created &TCPConn if success. If addr is not a valid address, it will forward relevant parse exceptionals. In addition, any bind and listening error will be return as exceptional.

See the [Dial] function for a description of the addr parameter.

DialTimeout ​

jule
static fn DialTimeout(addr: str, timeout: time::Duration)!: &TCPConn

Same as TCPListener.Dial, but uses timeout.

Accept ​

jule
fn Accept(self)!: Conn

Accepts incoming connection, returns &TCPConn. All exceptionals are error code of implementation. Panics if connection is closed.

Network ​

jule
fn Network(self): Network

Returns network name which is listening. If connection closed, returns Network.TCP as a general network.

Close ​

jule
fn Close(mut self)!

Closes connection. All exceptionals are error code of implementation.

TCPConn ​

jule
struct TCPConn {
	Addr:   &TCPAddr
	// NOTE: contains filtered hidden or unexported fields
}

TCP connection. In most cases, represents TCP client.

Implemented Traits ​

  • Conn
  • io::Reader
  • io::Writer
  • io::Stream
  • io::WriteCloser

Read ​

jule
fn Read(mut self, mut buf: []byte)!: int

Read bytes to buffer from connection and returns read byte count. The number of bytes read can never exceed the length of the buffer. If the buffer is larger than the number of bytes that can be read, the buffer will not cause an overflow. It will panic if connection is closed. If connection is closed by server, it returns zero and sets connection state as closed. So if you try read again, function will panic because of connection state is closed. All exceptionals are error code of implementation.

Write ​

jule
fn Write(mut self, buf: []byte)!: int

Writes bytes to connection and returns written byte count. The number of bytes written can never exceed the length of the buffer. All exceptionals are error code of implementation.

SetReadTimeout ​

jule
fn SetReadTimeout(mut self, timeout: time::Duration)!

Sets read timeout for connection. Timeout precision is microseconds. If the timeout is below one microsecond it will be accepted as zero. The zero timeout, clears current timeout if exist. All exceptionals are error code of implementation.

SetWriteTimeout ​

jule
fn SetWriteTimeout(mut self, timeout: time::Duration)!

Sets write timeout for connection. Timeout precision is microseconds. If the timeout is below one microsecond it will be accepted as zero. The zero timeout, clears current timeout if exist. All exceptionals are error code of implementation.

Network ​

jule
fn Network(self): Network

Returns network name which is connected. If connection closed, returns Network.TCP as a general network.

Close ​

jule
fn Close(mut self)!

Closes connection. All exceptionals are error code of implementation.

TCPAddr ​

jule
struct TCPAddr {
	IP:   IP
	Port: int
	Zone: str // IPv6 scoped addressing zone.
}

Represents the address of a TCP end point.

Implemented Traits ​

  • Addr

Resolve ​

jule
static fn Resolve(mut network: Network, addr: str)!: &TCPAddr

Returns an address of TCP end point. The network must be a TCP network name.

See the [Dial] function for a description of the network and addr parameters.

Exceptionals are always will be AddrError.

Network ​

jule
fn Network(self): str

Returns the address's network name.

Str ​

jule
fn Str(self): str

Returns string form of address.

UDPAddr ​

jule
struct UDPAddr {
	IP:   IP
	Port: int
	Zone: str // IPv6 scoped addressing zone.
}

Represents the address of a UDP end point.

Implemented Traits ​

  • Addr

Resolve ​

jule
static fn Resolve(mut network: Network, addr: str)!: &UDPAddr

Returns an address of UDP end point. The network must be a UDP network name.

See the [Dial] function for a description of the network and addr parameters.

Exceptionals are always will be AddrError.

Network ​

jule
fn Network(self): str

Returns the address's network name.

Str ​

jule
fn Str(self): str

Returns string form of address.

HardwareAddr ​

jule
type HardwareAddr: []byte

Physical hardware address.

Parse ​

jule
static fn Parse(addr: str)!: HardwareAddr

Parses s as an IEEE 802 MAC-48, EUI-48, EUI-64, or a 20-octet IP over InfiniBand link-layer address using one of the following formats:

00:00:5e:00:53:01
02:00:5e:10:00:00:00:01
00:00:00:00:fe:80:00:00:00:00:00:00:02:00:5e:10:00:00:00:01
00-00-5e-00-53-01
02-00-5e-10-00-00-00-01
00-00-00-00-fe-80-00-00-00-00-00-00-02-00-5e-10-00-00-00-01
0000.5e00.5301
0200.5e10.0000.0001
0000.0000.fe80.0000.0000.0000.0200.5e10.0000.0001

Exceptional is always will be AddrError.Unable.

Str ​

jule
fn Str(self): str

Returns address in string form.

UDPConn ​

jule
struct UDPConn {
	Addr:          &UDPAddr
	// NOTE: contains filtered hidden or unexported fields
}

UDP connection. This structure represents server and client connections.

Implemented Traits ​

  • Conn
  • io::Reader
  • io::Writer
  • io::Stream
  • io::WriteCloser

Bind ​

jule
static fn Bind(addr: str)!: &UDPConn

Binds new UDP listener and starts listening given address. Returns relevant created &UDPConn if success. If addr is not a valid address, it will forward relevant parse exceptionals. In addition, any bind and listening error will be return as exceptional.

See the [Dial] function for a description of the addr parameter.

Dial ​

jule
static fn Dial(addr: str)!: &UDPConn

Connects to UDP listener by given address. Returns relevant created &UDPConn if success. If addr is not a valid address, it will forward relevant parse exceptionals. In addition, any bind and listening error will be return as exceptional.

See the [Dial] function for a description of the addr parameter.

Read ​

jule
fn Read(mut self, mut buf: []byte)!: (n: int)

Read bytes to buffer from connection and returns read byte count. The number of bytes read can never exceed the length of the buffer. If the buffer is larger than the number of bytes that can be read, the buffer will not cause an overflow. It will panic if connection is closed. All exceptionals are error code of implementation.

Write ​

jule
fn Write(mut self, buf: []byte)!: (n: int)

Writes bytes to connection and returns written byte count. The number of bytes written can never exceed the length of the buffer. All exceptionals are error code of implementation.

SetReadTimeout ​

jule
fn SetReadTimeout(mut self, timeout: time::Duration)!

Sets read timeout for connection. Timeout precision is microseconds. If the timeout is below one microsecond it will be accepted as zero. The zero timeout, clears current timeout if exist. All exceptionals are error code of implementation.

SetWriteTimeout ​

jule
fn SetWriteTimeout(mut self, timeout: time::Duration)!

Sets write timeout for connection. Timeout precision is microseconds. If the timeout is below one microsecond it will be accepted as zero. The zero timeout, clears current timeout if exist. All exceptionals are error code of implementation.

Network ​

jule
fn Network(self): Network

Returns network name which is connected or listening. If connection closed, returns Network.UDP as a general network.

Close ​

jule
fn Close(mut self)!

Closes connection. All exceptionals are error code of implementation.

IP ​

jule
type IP: []byte

An IP is a single IP address, wrapper for a slice of bytes. Functions in this package accept either 4-byte (IPv4) or 16-byte (IPv6) slices as input.

Note that in this documentation, referring to an IP address as an IPv4 address or an IPv6 address is a semantic property of the address, not just the length of the byte slice: a 16-byte slice can still be an IPv4 address.

Some methods might return mutable data. There is no immutability promises.

Empty ​

jule
static fn Empty(): IP

Returns empty IP address.

Empty ​

jule
fn Empty(self): bool

Reports whether IP is empty.

Equal ​

jule
fn Equal(self, other: IP): bool

Reports wherher IPs are points to the same address. An IPv4 address and that same address in IPv6 from are considered to be equal.

IsUnspecified ​

jule
fn IsUnspecified(self): bool

Reports whether IP is an unspecified address, which is "0.0.0.0" in IPv4 or "::" in IPv6.

IsLoopback ​

jule
fn IsLoopback(self): bool

Reports whether IP is a loopback address.

IsPrivate ​

jule
fn IsPrivate(self): bool

Reports whether IP is a private address according to RFC 1918 (for IPv4) and RFC 4193 (for IPv6).

To4 ​

jule
fn To4(mut self): IP

Converts the IPv4 address to a 4-byte representation. Returns empty if IP is not an IPv4 address. Returned IP may use the common mutable allocation with self.

To16 ​

jule
fn To16(mut self): IP

Converts the IP address to a 16-byte representation. Returns empty if address is not an IP address (it is the wrong length).

Str ​

jule
fn Str(self): str

Returns string form of the IP address. It returns one of 4 forms:

  • "<nil>", if ip is empty
  • dotted decimal ("192.0.2.1"), if ip is an IPv4 or IP4-mapped IPv6 address
  • IPv6 conforming to RFC 5952 ("2001:db8::1"), if ip is a valid IPv6 address
  • the hexadecimal form of ip, without punctuation, if no other cases apply

Error ​

jule
enum Error {
	InvalidTimeout, // Timeout value is not valid. Duration is out of range.
}

Common connection error codes.

AddrError ​

jule
enum AddrError {
	NoSuitable,                    // No suitable address.
	Unable,                        // Unable to parse address.
	MissingIPv6,                   // IPv6 address is missing.
	UnexpectedToken,               // Address have unexpected token(s).
	TooShort,                      // Address is too short.
	TooLong,                       // Address is too long.
	IPv4FieldValueOverflow,        // IPv4 address field has value > 255.
	EmptyField,                    // IPv4 address field must have at least one digit.
	IPv4FieldOctetWithLeadingZero, // IPv4 field has octet with leading zero.
	EmptyZone,                     // Zone must be a non-empty string.
	IPv6FieldValueOverflow,        // Each group must have 4 or less digits or field has value >=2^16.
	IPv6ShortColon,                // Colon must be followed by more characters.
	MissingPort,                   // Port is missing.
	InvalidPort,                   // Port is invalid.
	TooManyColons,                 // There is too many colons.
	MissingRBracket,               // There is missing right bracket "]".
	UnexpectedLBracket,            // Address have unexpected left bracket "[".
	UnexpectedRBracket,            // Address have unexpected right bracket "]".
	UnknownNetwork,                // Unknown network name.
}

Address errors.

Network ​

jule
enum Network: str {
	TCP: "tcp",
	TCP4: "tcp4",
	TCP6: "tcp6",
	UDP: "udp",
	UDP4: "udp4",
	UDP6: "udp6",
}

Network names.