Forem: Simon Aust

Make your own card carousel in React

Simon Aust — Fri, 30 Jul 2021 09:39:05 +0000

When you have any sort of group of similar things, when it comes to presenting them you have a number of choices. You can use grids, tables, flexbox, they all do the job, but maybe you want to add a little bit of style and responsiveness to your page? If so, lets create our own carousel, a group of items we can swipe through with pointer events to add some interactivity. In the age of Instagram and Tinder, who doesn't like to swipe?

Making a Carousel
(Optional) Adding Mouse Events
(Optional) Carousel Pagination
(Optional) Make it Mobile Friendly

To make a functioning carousel you may only need to complete the first section, and then you'll have all you need to take it further yourself. I have added basic CSS to the layout and won't be adding all of the styles here to keep things concise, but you may check it out in the project repository and import it to match the styles seen.
NB: I'll use ellipses (...) to signify removed code in some parts to shorten code blocks.

Setting up the carousel

First thing we need is some data, which we will populate our cards with. Lets keep it simple, we can use a Javascipt array of objects and import them into our main app.js. Here's an example of some data, by all means edit or add your own touch to this.



export const data = [
  {
    name: "simon",
    img: "https://imgur.com/c43aAlv.jpg",
  },
  {
    name: "neo",
    img: "https://imgur.com/RF2a3PB.jpg",
  },
  {
    name: "morpheus",
    img: "https://imgur.com/B0SNpZI.jpg",
  },
  {
    name: "trinity",
    img: "https://imgur.com/KnXHM0K.jpg",
  },
];

Here we have a small array with some objects that have a name and img property. We will use these to populate the cards in the carousel later on.

In our App.js file we can add an import for the data like so - import {data} from "./data" - ready for later. This is a named import, so make sure to get the variable name matching your export variable. Onward to building our carousel!

Building the components of the carousel

First of all we need to make a component that will sit inside our carousel, the object which will slide across the screen. In this case I will call it a card and create it as a React component as so -



const Card = ({ name, img }) => {
  return (
    <div className="card">
      <img src={img} alt={name} />
      <h2>{name}</h2>
    </div>
  );
};

export default Card;

A simple component just holds two items, an image and a heading for our object name property. You can see the props are passed down into this component, lets set that up now from our data.js.

In App.js we will iterate over the data using the map() function and populate our root element with cards -



import "./App.css";

import Card from "./components/Card";
import { data } from "./data";

function App() {
  return (
    <div className="App">
      <div className="container">
        {data.map((person) => {
          return <Card {...person} />;
        })}
      </div>
    </div>
  );
}

export default App;

We're using the map() function to iterate over the data and create a new Card for each person, passing in the properties using the spread operator. We already know the names of these properties match the component arguments, but it's one thing to look out for if your card doesn't display as you expect.

Now you should have something that looks like this (as long as you applied the App.css from the repo) -

Positioning the cards

Now we need to work on our carousel. In a carousel cards typically slide from the right or left, so we need to position our cards in some order, lets say "prevCard" on the left, "nextCard" to the right. These will be CSS classes we give the cards depending on their position.

Firstly we will add position: absolute to the card CSS class, this stacks all our cards on top of each other. Now we create some new CSS styles prevCard, activeCard and nextCard -



.prevCard {
  left: 0;
}

.activeCard {
  left: 50%;
  transform: translateX(-50%); /* the card is centered 
                               /* to itself
                               /* instead of the left edge
                               /* resting on the center line
}

.nextCard {
  right: 0;
}

The next question is under what condition do we apply those styles to the cards? Well in the map() function we can add a parameter to read the current iteration index, data.map((person, index) => {}). This gives us the ability to apply the styles depending on a condition. But what condition? For example, we can say any card greater than index equal to zero should have the style nextCard applied. Lets look at the Javascript for this -



{data.map((person, index) => {
    let position = index > 0 ? "nextCard" : index === 0 ? 
        "activeCard" : "prevCard";
    return <Card {...person} cardStyle={position} />;
})}

We're using nested ternary operators here to check the index and apply a style to the card, which we pass down as a prop. We also need to update the card component to take a new parameter cardStyle and apply that to the className attribute. We can use a template string to concatinate the new style with our required card style like so -



const Card = ({ name, img, cardStyle }) => {
  return (
    <div className={`card ${cardStyle}`}>
...

If you save the app you may now see something like this -

Using Chrome dev tools and highlighting the container element, the problem here is that the nextCard "card" is positioning itself to its nearest positioned relative, of which there are none, so in this case is it the root element. We need to add a container, which will hold the cards and allow us to position them where we want.



// css
.card-container {
  position: relative;

  width: 36rem;
  height: 22rem;
}

For simplicity sake, we're setting the width of the card container to three cards width, accounting for margin. This will allow a nice transition later on.



// App.js
<div className="container">
    <div className="card-container"> /* wrap cards */
        {data.map((person, index) => {
            let position =
                index > 0 ? "nextCard" : index === 0 ? 
                "activeCard" : "prevCard";
            return <Card {...person} cardStyle={position} />;
        })}
    </div>
</div>

So we've positioned our cards, we can now add some controls to move them. Lets just use FontAwesome icons for this. You can find instructions for using FontAwesome and React here. We can simply use the faChevronLeft and faChevronRight. Once we've imported them, we can position them absolutely, and give them a onclick function, which we'll work on next.



import { FontAwesomeIcon } from "@fortawesome/react
fontawesome";
import { faChevronLeft, faChevronRight} from "@fortawesome/free-solid-svg-icons";

Carousel function

There is a glaring problem here. There is no previous card! This has been determined by our condition in the map function, so we need to fix this. At the same time, we can link in some functionality to our onClick handler, and also utilise useState hook from React. Lets break it down.

We need a starting point for our cards, an index, so we set up some state with a value of zero. We import the hook and declare our state variables -



import {useState} from "react";

const [index, setIndex] = useState(0)

We are going to change this state value with our onClick functions and instead of comparing a hardcoded value 0, we are going to compare the index of the map function with the state. This allows use to change the condition which applies the styles to the cards. First the functions -



const slideLeft = () => {
    setIndex(index - 1);
};

const slideRight = () => {
    setIndex(index + 1);
};

Update the FontAwesomeIcon component with a onClick function -



<FontAwesomeIcon
    onClick={slideLeft}
    className="leftBtn"
    icon={faChevronLeft}
/>
<FontAwesomeIcon
     onClick={slideRight}
     className="rightBtn"
     icon={faChevronRight}
/>

Finally the condition is updated to compare with the state value (updated the map index with a new name n) -



{data.map((person, n) => {
    let position = n > index ? "nextCard" 
        : n === index ? "activeCard" : "prevCard";
    return <Card {...person} cardStyle={position} />;
})}

On testing I had some issues at this point with the transitions, and discovered this to be my mistake when using the position properties left and right with the CSS. It creates a smooth tranistion if you stick to the same property throughout, although this meant I had to use some tweaks to get the cards in the right places, using the CSS calc() function. The updated CSS for the cards -



.prevCard {
    left: calc(0% + 2rem);
    opacity: 0;
}

.activeCard {
  left: 50%;
  transform: translateX(-50%);
}

.nextCard {
    left: 100%;
    transform: translateX(calc(-100% - 2rem));
    opacity: 0;
}

This will nicely position the cards left, center and right throughout the transition, accounting for the margin. Note the opacity: 0 property, this is the result -

Here is with no change to opacity, so you may see easily what is happening -

Woo! Looks pretty nice! I'm sure you're already thinking of awesome ways to improve this, but firstly we just need to improve our function and stop changing the state if our index goes out of bounds to the data length. Otherwise, we could keep clicking forward, or backward for eternity, and the state would keep changing.



 const slideLeft = () => {
    if (index - 1 >= 0) {
      setIndex(index - 1);
    }
  };

  const slideRight = () => {
    if (index + 1 <= data.length - 1) {
      setIndex(index + 1);
    }
  };

A couple of simple if conditions keep us within bounds and we can happily scroll left and right without a worry.

Adding Mouse Events

Pointer events are things like a mouse clicking, dragging, moving over an element. We've already used one, onClick, in our FontAwesomeIcon component to trigger a card to move. Want would be nice is if we can click and drag, and pull the card across the screen. We can do this with some other MouseEvent's that are available to us, like onMouseDown, onMouseMove and onMouseUp.

First we'll make a test function to see everything is working.



const handleMouseDown = (e) => {
    console.log(e.target);
  };

Now we pass this function as a prop to our Card component and give the onMouseDown attribute this function in the container div.



// App.js
<Card
    handleMouseDown={handleMouseDown}
    {...person}
    cardStyle={position}
/>
// Card.js
const Card = ({ handleMouseDown, name, img, cardStyle }) => {
    return (
        <div 
            className={`card ${cardStyle}`} 
            onMouseDown={handleMouseDown}>
...

Now if we click on a few cards we will see in the Chrome console something like -

On each click the event object is passed to our function which we use to log the target, which is the card. We can use the event to get the element we should move, the starting position of X, and use document.onMouseMove to track the cursors position. Once we have that, we can change the CSS left position property to reflect what the mouse does.

Firstly you may notice when dragging the card from the image it will be pulled along with your cursor. We need to stop this to prevent it interfering with our dragging of the card, we can do this in CSS by applying pointer-events: none; to the image. Other than that you may also be getting some selection happening when the mouse drags over the heading and image, to prevent that we can use user-select: none in the card class. An alternative if you want or need to allow selection is to have a specific area of the card as the draggable area, for this you would set your onMouseDown handler function to that particular element of the card, like a <header> or any other element you want.

So once that's sorted, now lets look at the function we need to track our mouse event -



const handleMouseDown = (e) => {
    /* this is our card we will move */
    let card = e.target;
    /* to keep track of the value to offset the card left */
    let offset = 0;
    /* keeps the initial mouse click x value */
    let initialX = e.clientX;
    /* set the documents onmousemove event to use this function*/
    document.onmousemove = onMouseMove;
    /* sets the documents onmouseup event to use this function */
    document.onmouseup = onMouseUp;

    /* when the mouse moves we handle the event here */
    function onMouseMove(e) {
      /* set offset to the current position of the cursor,
      minus the initial starting position  */
      offset = e.clientX - initialX;

      /* set the left style property of the card to the offset 
      value */
      card.style.left = offset + "px";
    }

    function onMouseUp(e) {
      /* remove functions from event listeners
      (stop tracking mouse movements) */
      document.onmousemove = null;
      document.onmouseup = null;
    }
};

Now there's a few issues, sadly. First of all you'll immediately notice what feels like mouse lag. This is the transition CSS property on the card slowing down it's movement as it animates between positions. You can comment that out to fix it, but of course this will disable the nice animation when clicking the left/right chevrons. The second issue is that when we move the card left is instantly set to a pixel value and the card appears to jump left. This is definitely not what we want! We can fix both these problems by adding a(nother!) container around our card, which will take on the transition property and our card will be aligned within, so there will be no jump left.

First we wrap our card with a <article> tag, trying to follow HTML semantics, that will be what is positioned in the card container, and have the transition. The actual card will be absolutely position to this element, so when changing its left property, there won't be any oddness, as it hasn't previously been set.



// Card.js
<article className={cardStyle}> /* class now applies here */
    <div className="card" onMouseDown={handleMouseDown}>
        <img src={img} alt={name} />
        <h2>{name}</h2>
    </div>
</article>



article {
    position: absolute;
    width: 12rem;
    height: 100%;

    transition: all 1s; /* cut from .card class */
}

Now that the card is kind-of draggable, you will notice that the other cards, previous and next, are interfering when you drag the visible card near them. We fix this by adding a <div> with a sole purpose of "hiding" these elements, by using z-index. We create a div called, creatively, background-block and give it a z-index: 0 and append our other elements accordingly. prevCard and nextCard get a z-index: -1.



// App.js
<div className="card-container">
          <div className="background-block"></div>
          ...



.background-block {
  position: absolute;
  width: 100%;
  height: 100%;
  z-index: 0;
}

This is what you should see -

The last thing we need to do, the whole point of this, is to trigger the slide to the next or previous card. We go back to our handleMouseDown function for this, and add some conditions checking the value of x. Inside onMouseMove we add -



function onMouseMove(e) {
    ...
    if (offset <= -100) {
        slideRight();
        return;
    }
    if (offset >= 100) {
        slideLeft();
        return;
    }
    ...
}

One last issue (I promise!), you'll notice that the cards retain the position after sliding back and forth. We can fix this by resetting their left property in the same block of code.



if (offset <= -100) {
        slideRight();
        /* if we're at the last card, snap back to center */
        if (index === data.length - 1) {
          card.style.left = 0;
        } else {
          /* hide the shift back to center 
        until after the transition */
          setTimeout(() => {
            card.style.left = 0;
          }, 1000);
        }
        return;
      }
      if (offset >= 100) {
        slideLeft();
        /* if we're at the first card, snap back to center */
        if (index === 0) {
          card.style.left = 0;
        } else {
          /* hide the shift back to center 
        until after the transition */
          setTimeout(() => {
            card.style.left = 0;
          }, 1000);
        }
        return;
      }

Also, if the user releases the mouse before +- 100 pixels, the card will "stick", we can sort that in the onMouseUp function -



function onMouseUp(e) {
    /* if user releases mouse early,
    card needs to snap back */
    if (offset < 0 && offset > -100) {
        card.style.left = 0;
    }
    if (offset > 0 && offset < 100) {
        card.style.left = 0;
    }
    ...

Actually, slight adjustments can be made to the style of prevCard; left:0; and nextCard; transform: translateX(-100%); - to keep a nice spacing after the change to wrapping with <article> element.

Et voila!

Carousel Pagination

Another optional thing we can do is add some visual feedback of where we are in the carousel. You can think of this as a form of pagination, although it's just for visual reference.

First we'll make a new component called Paginator. It will take two props, one is the length of the data, i.e. how many dots to represent the cards, and an index value which represents which card is active so we can style the respective dot to reflect this.

Here's our component -



const Paginator = ({ dataLength, activeIndex }) => {
    let dots = [];
    let classes = "";
    for (let index = 0; index < dataLength; index++) {
        classes = activeIndex === index ? "dot active" : "dot";
        dots.push(<div key={index} className={classes}></div>);
    }

    return (
        <div className="paginator">
            <div className="hr"></div> {/* horizontal rule */}
            {dots.map((dot) => dot)}
        </div>
    );
};

export default Paginator;

You can see here we are using the dataLength to populate an array with JSX objects. One of those objects is give a class active, which will set it apart from the others. The CSS is straight forward and can be found in the repo (link at top).

In App.js we simply import our component and pass in the data.length and state value index. When we slide the carousel, the state value changes and the Paginator will receive this new value and render the updates accordingly.



//App.js
...
<div className="card-container">
    <Paginator dataLength={data.length} activeIndex={index} />
...

To make the dots clickable we can add a function to the onClick attribute like normal. We'll pass this function down from App.js into the Paginator.js component.



//App.js
const handlePageChange = (page) => {
    let n = page - index;
    setIndex(index + n);
};
<Paginator
    ...
    handlePageChange={handlePageChange}
/>
//Paginator.js
onClick={() => handlePageChange(index)}

Basically the onClick function passing in a argument which is the index of the map function, for simplicity. This identifies what "page" it is, and we compare this with the state value. Then we can simply add the number (positive or negative) to set our index state and trigger a render.

Make it mobile friendly

Earlier we added mouse events which handled clicking and dragging a card to trigger the functions which slide the cards. To make our carousel mobile friendly, we also need to add another kind of pointer event, called TouchEvent's.

In our Card components <article> element we should add a new attribute onTouchStart. This event is fired when a tablet or phone has a finger or stylus touch the screen. We'll point it to the same function that handles our mouse events and make some changes there. We should also rename the argument to better reflect that it now handles pointer events, rather than just mouse events.



// Card.js
<article className={cardStyle}>
      <div className="card" onMouseDown={handlePointerEvent} 
      onTouchStart={handlePointerEvent}>
...

In App.js we rename handleMouseDown to handlePointerEvent and then add a variable to check what type of event we're getting.



let isTouchEvent = e.type === "touchstart" ? true : false;

We can use this flag a few more times when we are setting the X coordinate, again using ternary operators. Updating the code changes to -



function onPointerEvent(e) {
    ...
    let initialX = isTouchEvent ? e.touches[0].clientX : 
        e.clientX;
    ...
    function onPointerMove(e) {
        ...
        offset = (isTouchEvent ? e.touches[0].clientX : 
            e.clientX) - initialX;
        ...
    }
...
}

You may notice that we're checking the first index of an array of the touch object. This is because many devices can use multi-touch, so you could track one or more fingers if you wished, for example using pinch to zoom. We don't need to track more than one though, so we just check the first, zeroth, finger/stylus.

We also need to add the functions to the documents touch event listeners, as we did before with the mouse events. We remove them when the touch ends, just like when the mouse click finished. This prevents our functions being called after we're done with them.



// handlePointerEvent
document.ontouchmove = onPointerMove;
document.ontouchend = onPointerEnd;

// onPointerEnd
document.ontouchmove = null;
document.ontouchend = null;

Now if you check it out in Chrome dev tools with mobile view it works, but there is some issues when a card slides off screen to the right, expanding the view and causing scrollbars to appear briefly. We can fix this using media queries but hiding the overflow and restyling the elements slightly.



@media screen and (max-width: 425px) {
  .container {
    width: 100%;
    overflow: hidden;
  }

  .card-container {
    width: 80%;
  }

  .prevCard {
    left: -35%;
  }

  .nextCard {
    left: 135%;
  }
}

This is just for one screen width of 425px and less, if you want to support more widths you'll need to do a bit more testing and add more media queries to reposition.

That's it! We've done it, a nice carousel, with touch and is responsive. Lets see the final product -

Phew, I hope you found some interesting things here and it helps you out. At the end of the day it's a basic carousel but by working through the process to create it I hope it gives you ideas of what else can be achieved. Thanks for reading! If you have any comments of suggestions please do add them below.

Cover photo by picjumbo.com from Pexels

What is Java classpath?

Simon Aust — Sat, 12 Jun 2021 12:48:57 +0000

Have you ever read a tutorial, or someone in a forum, or in Discord, say "make sure it's on the classpath" and don't have the foggiest idea what they are talking about? Well it's your lucky day because we are going to figure out what the mysterious Java classpath is.

There is a TLDR at the bottom, if you'd like the concise answer

How the terminal finds and runs programs

First of all, you are going to be running a lot of your Java programs from a terminal. You've probably already used a number of commands in the terminal already, one such example is -

D:\Coding\Dev\Classpath example demo>echo Hello, World
Hello, world

What is happening here? We're using a program called echo to print the line of text "Hello, World". We are calling the program by typing its name then some text, but how does the computer know we have a program called "echo" and how does it find it? There is something called an environment variable which stores a semi-colon separated list of paths to programs, one is aptly called Path.

Lets have a look at my Path using echo

D:\Coding\Dev\Classpath example demo>echo %Path%
C:\Python38\Scripts\;C:\Python38\;C:\Program Files\Java\jdk-13.0.2\bin;
C:\Program Files (x86)\Common Files\Oracle\Java\javapath;C:\ProgramData\Oracle\Java\javapath;
C:\Program Files (x86)\Intel\iCLS Client\;C:\Program Files\Intel\iCLS Client\;
C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;
...
C:\Program Files\Java\jdk-13.0.2\bin;
...

Wrapping a string with % symbols identifies it as a variable

I've omitted quite a bit here, but you can see these are directory paths within your computer to the location of a program file. The command terminal will check your Path variable's paths when you type a command and see if it can find a matching program with that name, then it will run the program with any options you added, like the text "Hello, world".

Making and running a simple `.java` program

So now we know how the computer finds a program, and we can see from the list C:\Program Files\Java\jdk-13.0.2\bin, this is the location of the java program. This is how we run our Java code, lets make a simple program and run it. Let's stick to the old faithful, slightly modified, it will output "Hello, world, from Main class" to the terminal.

public class Main {
    public static main(String[] args) {
        System.out.println("Hello, world, from Main class");
    }
}

Now we have a program, lets use java to run it.

D:\Coding\Dev\Classpath example demo>java Main
Error: Could not find or load main class Main
Caused by: java.lang.ClassNotFoundException: Main

Huh, something went wrong. It seems java couldn't find our class called "Main". Well, there's a hint in the error, java is looking for a .class file. A class file is a compiled version of our .java file, which the computer can understand and execute. If we look at the documentation for java (always a good idea to read the doc's!) we can see that the structure for a command is java [options] classname [args]. So how do we get a .class file? We can use another program called javac.

javac, short for Java Compiler, will compile your .java into a .class file. Lets give it a go.

D:\Coding\Dev\Classpath example demo>javac Main.java
D:\Coding\Dev\Classpath example demo>dir
 Volume in drive D is Data
 Volume Serial Number is 64F6-4376

 Directory of D:\Coding\Dev\Classpath example demo

26/05/2021  15:42    <DIR>          .
26/05/2021  15:42    <DIR>          ..
26/05/2021  15:42               414 Main.class
26/05/2021  14:07               162 Main.java
               2 File(s)            576 bytes
               2 Dir(s)  320,053,022,720 bytes free

dir - lists out all the folders and files in the current directory

You can see here there is a new file created Main.class. We can now run this file with java.

D:\Coding\Dev\Classpath example demo>java Main
Hello, world, from Main class

Complicating matters

So this is great. What's the issue with "classpath" then? Lets move our Main.class and try again to run the program.

D:\Coding\Dev\Classpath example demo>mkdir SubFolder

D:\Coding\Dev\Classpath example demo>move Main.class SubFolder
        1 file(s) moved.

D:\Coding\Dev\Classpath example demo>tree /F
Folder PATH listing for volume Data
Volume serial number is 64F6-4376
D:.
│   Main.java
│
└───SubFolder
        Main.class

tree /F prints a folder and file hierarchy to the console

Here we have created a new sub-folder called "SubFolder" and placed Main.class within. Running the program as before, this happens -

D:\Coding\Dev\Classpath example demo>java Main
Error: Could not find or load main class Main    
Caused by: java.lang.ClassNotFoundException: Main

We've lost our Main.class! So how do we tell java where it is? We put it on the classpath! Lets do that -

D:\Coding\Dev\Classpath example demo>java -cp ./SubFolder Main 
Hello, world, from Main class

. before /SubFolder means the path is relative to where we
are in the file system

What we just did is set the classpath with the -cp option. This tells the JVM where to find the .class file, and it now runs!

A more "real world" example

Ok, so everything is great, right? Well, right now. In real applications there is a lot of classes and a lot of dependencies. Dependencies are code files which your code depends on, and are usually kept in a library of related files you download and add to your project. These are normally kept outside of your project file structure, usually in a some type of container like a .jar file. So, lets look at a practical example, when a class is out in another folder on it's on, simulating being a dependency.

First we will create our new java file and update Main.java with some code that utilises the new class -

public class ExternalClazz {

    public void printText() {
        System.out.println("Hi from elsewhere");
    } 
}

public class Main {

    public static void main(String[] args) {
        System.out.println("Hello, world, from Main class");

        ExternalClazz externalClazz = new ExternalClazz();
        externalClazz.printText();
    }
}

and compile it, along with Main.java to update that code -

javac ExternalClazz.java
javac Main.java

In fact we could have just used javac Main.java, and it would
have compiled both files, as it will parse through Main.java
and discover it needs to compile ExternalClazz.java for
Main.java to work correctly

This creates ExternalClazz.class in our current directory. We can add it to a .jar file and move it to "Dependency" folder -

D:\Coding\Dev\Classpath example demo>jar cvf MyJar.jar ExternalClazz.class
added manifest
adding: ExternalClazz.class(in = 417) (out= 292)(deflated 29%)

D:\Coding\Dev\Classpath example demo>move MyJar.jar Dependency
        1 file(s) moved.

Now the file structure looks like this -

D:.
│   ExternalClazz.java
│   Main.java
│
├───Dependency
│       MyJar.jar
│
└───SubFolder
        Main.class

So now we have our Main.class in a sub-folder, and our main method has some code which is dependent on a .class which is in a .jar file, also in another folder. How do we run this?

D:\Coding\Dev\Classpath example demo>java -cp ./Dependency/MyJar.jar;./SubFolder Main
Hello, world, from Main class
Hi from elsewhere

We have used the argument -cp to define the classpath, but this time we've used multiple paths. One points to the .jar file, and the other to where our Main.class is. Does this remind you of anything? That's right, it's the same as the Path environment variable, a list of ; separated paths to target locations.

Developer tools

Now, generally we all use IDEs to make our projects, like InteliJ IDEA, VSCode or Eclipse. Normally these integrated development environments will handle setting the classpath and running the programming, but this is still good knowledge to have and understand.

Here in InteliJ IDEA is where the classpath is set for your project, in run/debug configurations, "Use classpath of module" -

and in VSCode, after installing the Java extension -

IDEs are very powerful tools and handle a lot of the under the bonnet configuration, but should we ever run into issues with these configs we'll already be prepared. There are other tools called "build" tools such as Maven and Gradle, which handle pointing JVM to the right places, which is totally out of the scope of this blog post, but they are incredibly useful and you should spend some time to learn them, too.

TLDR;

The Java classpath is a collection of folder or file paths that tell the Java Virtual Machine where the compiled code is which is to be executed in your program. When it can't find the .class files your program cannot run, as the JVM can't find it's instructions. "Putting it on the classpath" means making sure compiled java files are in a folder the classpath knows. Otherwise, you will need to specify that folder when you run your java program. Classpath will check the current folder by default, if it can't find the .class files you need to specify the path with the -cp or -classpath argument, more than one path can be separated with a ;. You can point to .class files or .jar files.

I hope this is helpful, please let me know if I missed anything 😃

Header image photo by Alexander Schimmeck on Unsplash

Bitwise & Bitshift in Java

Simon Aust — Wed, 07 Apr 2021 09:56:46 +0000

In programming we use control flow statements to change the execution of our code. If this then that, sort of thing. I'm sure we all know the standard keywords, if, else, else if. When we use if or else if we put a condition in the parenthesis, which will return a boolean, essentially a yes do this, or a no skip this bit of code and move on.

Here's a (simple) example -

if (1 < 2) {
    System.out.println("One is less than two, well played.");
} else {
    System.out.println("Why am I here? No one listens to me.");
}

Conditional, Relational, Equality Operators

In the snippet of code above you can see the less than operator < evaluating the two operands.

An operand is a object which the operator provides a function
on. In our example above, 1 < 2, 1 and 2 would be operands.

Other operators we know and love are -

Relatioinal

<= less than or equal to
> greater than, >= greater than or equal to

Equality

== equal to
!= not equal to

Conditional

|| or
&& and

The last two are interesting, have you ever seen them on their own, like | or &? Well these are the bitwise version of those conditional operators, bitwise or and bitwise and. The difference being conditional operators work by evaluating two boolean values, while bitwise operators can evaluate two booleans, or two integer types (whole numbers) by evaluating the binary representation. Lets explore them in more depth.

Integral types in Java are byte, short, int, long and
char

Bitwise Operators

Firstly lets have a little look at what an integer looks like in binary. We can use the handy static method Integer.toBinaryString(int) and output to console.

int twenty = 20;
System.out.println(Integer.toBinaryString(twenty)); // 10100

// the bits are one in position 2^2 (which equals 4) and 2^4 (16)
// 10100
// ^ ^ 
// 16 + 4 = 20

Important note: Integer.toBinaryString() does not return
extra leading zeroes. An int is 32 bits, but only the largest
bit of the value to smallest bit is shown in the returned
string.

`|` inclusive OR

The inclusive or operator will check the binary digits of two integer types, one column at a time, if either is binary 1, then the result is binary 1. Here's an example -

int five = 5;  // 0101
int nine = 9;  // 1001
System.out.println(Integer.toBinaryString(five | nine)); // 1101

What is happening here? Lets break it down -

// each bit in each column is compared, from left to right -
// 0 or 1, 1 or 0, 0 or 0 and finally 1 or 1

// 0101
// 1001
// ----
// 1101 == decimal 13

So you could say when a smaller integer is being compared with a bitwise or statement with a larger integer, the result will always at least the value of the bigger number.

`&` AND

The and operator will only result in binary one when both bits are binary one.

int three = 3; // 011
int five = 5; //  101
System.out.println(Integer.toBinaryString(three & five)); // 1 

// from right to left, 0 & 1 = 0, 1 & 0 = 0, 1 & 1 = 1
// 011
// 101
// ---
// 001

We can use & to discover whether a number is odd or even. As
the only odd digit in a binary pattern is $2^0$ , the rightmost bit, we can
use a bit mask to return the first bit, 1 or 0, odd or even, when comparing a number.

int nine = 9; // 1001
int six = 6; //  0110
//                  ^ rightmost bit
int bitMask = 1; // 0001
System.out.println(1 == (six & bitMask) ? "Odd" : "Even"); // Odd
System.out.println(1 == (nine & bitMask) ? "Odd" : "Even");// Even

A bitmask is a binary pattern which will allow us to use bitwise
operators to choose which bits of another pattern to operate on

A common way to check if a number is odd or even is using the modulus operator %, which will return the remainder between two numbers. When using modulus 2, any even number will return zero, any odd number one.

System.out.println(11 % 2); // 1, we know it's odd
System.out.println(10 % 2); // 0, we know it's even

`^` exclusive or XOR

When evaluating two bits it will return 1 only when a single operand is 1.

int five = 5; // 101
int six = 6; // 110
System.out.println(Integer.toBinaryString(five ^ six)); // 11
// 101 
// 110 
// ----
// 011, decimal 3

`~` unary complement / NOT

Inverts all binary one bits to zero, and all binary zero bits to one. In essence NOT 1 == 0, NOT 0 == 1.

int five = 5; // 101b
System.out.println(~five); //  
// 101
// --- NOT
// 11111111111111111111111111111010 == -6

Hold on, why is ~5, 101 in binary, inverted with a bitwise NOT ~, not 010, i.e. decimal 2? Well, computers use binary to represent numbers, both positive and negative. One way to represent negative numbers is a numbering scheme called twos complement. What this means is the leftmost bit in a binary pattern, or the most significant bit (as it's the largest number), is used to signify whether the number is positive or negative, 1 is for a negative number, 0positive. As we are using a integer primitive with our bitwise NOT here, an int is 32 bit, or 4 bytes, in size. As mentioned earlier, the method Integer.toBinaryString() omits preceeding zeroes in a pattern by default, but the rest of the int is infact filled with zeroes to the MSB on the left.

So, all those zeroes have now been inverted to ones, but how does that calculate to negative six? Binary is a summation of all bit values which are 1.

// 0111
// ^^^^
// ||||_ 2^0 == 1
// |||_ 2^1 == 2
// ||_ 2^2 == 4
// |_ 2^3 == 8
// 
// So summing the bits which are 1 gives us, 4 + 2 + 1 == 7

As the MSB is negative if it is 1, and remember our NOT operator inverted it to 1, that value is our base value before we sum the rest of the binary digits from left to right.

Lets do a example with a smaller integer type, byte which is 8 bits or, not surprisingly, one byte.

byte five = 5;
// 0x00FF is a bitmask in hexadecimal, it means we only see 8 
// bits, representing our byte primitive
System.out.println(Integer.toBinaryString(0x00FF & ~five));
// 11111010
// ||||| |
// ||||| |_ 2^1 == 2
// ||||| 
// |||||_ 2^3 == 8
// ||||_ 2^4 == 16
// |||_ 2^5 == 32
// ||_ 2^6 == 64 
// |_ -2^7 == -128 (Most significant bit)

// Doing the sum;
// -256 + 64 + 32 + 16 + 8 + 2 == -6

I hope that helps you understand quickly how we got to negative six as our bitwise NOT result, but do please check this BBC guide on twos complement for some more help if you need it as I won't go into it any deeper.

Unary means the operator works on only one
operand. For example as seen in for loops frequently, i++
unary postfix operator, increments i by one.

Bitshift

There is also some other operators known as bitshift. These move the bits left or right in a binary pattern.

`<<` left shift

Moves the bits in a binary pattern to n times to the left. It is represented as number << placesToShift, for example 1 << 2, moves the bits in integer one two places to the left. The effect of moving the bits multiplies the number by $2^n$ . That is to say, one left shift will multiply the number by $2^1 = 2$ . A shift two places left would be the number multiplied by $2^2 = 4$ .

System.out.println(2 << 1); // 4
// 0010 == decimal 2
// 0010 << 1 == 0100 == 4
                 ^- 
System.out.println(2 << 2) // 8
// 0010 << 2 == 1000 == 8
                ^--

`>>` right shift

As above, the right shift uses the format number >> timesToShift, but it shifts the bits to the right. In effect dividing the number by $2^n$ .

int eight = 8; // 1000 
System.out.println(8 >> 1); // 2^1 == 2. 8 / 2 == 4
// 1000 >> 1 == 0100 == 4
System.out.println(8 >> 2); // 2^2 == 4. 8 / 4 == 2
// 1000 >> 2 == 0010 == 2
System.out.println(8 >> 3); // 2^3 == 8. 8 / 8 == 1
// 1000 >> 4 == 0001 == 1

Now you've read this blog you can do this quick trick to impress your coding friends, to divide any number in half integer >> 1!

With negative numbers things get a little more interesting. Remember twos compliment uses the most significant bit to declare the number positive or negative, for a positive number bits will be filled with zeroes, for a negative number bits will be filled with ones. The same method applies from the bitwise NOT example above, the binary is summed to find the resulting number.

byte negativeFour = -4;
System.out.println(Integer.toBinaryString(0x00FF & 
    negativeFour));      // 11111100
System.out.println(Integer.toBinaryString(0x00FF & 
    negativeFour >> 1)); // 11111110
//                          ^ 1 filled to the left

`>>>` unsigned right shift

Twos complement is a signed representation of a number in binary form. That is to say it can represent positive and negative numbers. An unsigned number has no bit that declares it one or the other, so they are always positive. In the case of the unsigned right shift, space after a shift is filled with zeroes, so any negative number will become a positive number as the MSB will no longer be 1.

int negativeFour = -4;
System.out.println(Integer.toBinaryString(negativeFour));
System.out.println(Integer.toBinaryString(negativeFour >>> 2));
System.out.println(negativeFour >>> 2);

// Output
// 11111111111111111111111111111100
// ^ MSB is 1, the number is negative
// 00111111111111111111111111111111*
// ^^ shifted two places right and filled with zeroes 
// The final output is the sum of the resulting binary,
// without a sign bit it is a positive number
// 1073741823

* I had to amend the zeroes here for example purposes. The actual output will be without the zeroes.

I hope that is clear for you, it's a little tricky to calculate these long binary patterns just looking at them.

Example use case of bitshift with booleans

There is really only one bitwise operator which isn't directly translatable with a single conditional operator and that is XOR, exclusive or.

Say you are have a staff rota application. It has employee objects, with a method that returns if they are scheduled to be at work for a given shift. You only need one worker per shift, so you have a method which checks that only one worker is scheduled on a shift at a time, using the ^ operator.

// atWork(Date) returns true if employee scheduled for work on 
// that date. Both employees are scheduled for work today.
LocalDate today = LocalDate.now();
if(emplyee1.atWork(today) ^ employee2.atWork(today) {
    // we save the rota if only one employee is working
    workRota.save();
} else {
   // reschedule one of the employees, amend the rota
}

We can make the same statement with conditional operators but it is a bit more long winded -

if (!employee.atWork(today) && employee.atWork(today) 
   || employee.atWork(today) && !employee.atWork(today))

It may be a convoluted example that you probably won't have to put in to practice yourself, but it's another tool for your toolbelt, which is never a bad thing.

Conclusion

Bitwise and bitshift can be confusing at first, possibly you've not seen them often, and you may wonder why you would use them. In fact they can be very useful in algorithms, where manipulating binary bits efficiently is very important. Mainly though, it's good that if you see these in someone else's code you can understand what is happening.

Cover image by Gerd Altmann from Pixabay

Different ways to make a list in Java

Simon Aust — Sun, 28 Mar 2021 14:37:16 +0000

Lists are really important. They add the flexibility to resize automatically when adding or removing an element. This is particularly handy when you're taking input from a user in some form, and you don't know how many objects you will need to store in some array. As arrays are of fixed size when they are initialised, if we wanted to resize them, we'd need to create a new bigger array and copy the elements over. This is perfectly possible, but the List type does this work for you.

So, we know why, lets see the many ways we can create a List.

ArrayList<>()

The first list type that most of us will use though is the ArrayList. It keeps elements ordered in the sequence they were input. The simplest way to declare and initialise this type of List, with String elements, is like so;

List<String> list = new ArrayList<>();
list.add("Here");
list.add("we");
list.add("add");
list.add("elements");

This method of creating and adding elements is particularly useful if we are iterating over some other data structure or input, getting elements until the input stops. For example with the
Scanner and standard input stream in your IDE;

Scanner scan = new Scanner(System.in);
// user input = 1 2 3 4 e
while(scan.hasNextInt()) { // returns true if element is an int
    list.add(scan.nextInt());
}
// list = {1,2,3,4}

Arrays.asList()

That's a great way to get an unknown number of elements into our List, but what if we already have an array we need to convert into a List? There's a ~~app~~ utility method for that! From the Arrays class;

String[] strings = new String[]{"Here's", "some", "strings",
    "in a", "string array"};
List<String> asList = Arrays.asList(strings);

Voila, our String[] is now a List. We can add to it or remove elements as we please. Be aware though, that the array you enter as the argument for Arrays.asList(array), is taken and used as the basis for the List (the list is backed by the array). Any changes to the original array will be reflected in the List. This is also true vice versa, if you alter the List it will be reflected in the array.

strings[1] = "altered the string array"; // change the element at 
                                         // index 1
System.out.println(asList); // [Here's, altered the string array, 
                            // strings, in a, string array]

So, just be careful with the source array otherwise you may get some unexpected results.

List.of()

The next way to create a List quickly is List.of(). This is a static method from the List interface, static means we can call the method without an object instance, like;

Person personInstance = new Person();
int age = personInstance.getAge(); // instance method

double pi = Math.PI; // static field from the Math class

The drawback (or benefit) with List.of() is it returns an immutable list. This means you cannot add or remove elements. Something to keep in mind, and depending on your situation, this might fit your need.

List<String> listOfList = List.of("Can't", "change", "this", 
    "list");
listOfList.add("add me please"); // throws 
                                 // UnsupportedOperationException

You should know though, that the internal state of an element can still be altered. That is, if you had a list of Person()s, you could call the statement -

listOf.get(1).setAge(32);

without any exception being thrown.

Arrays.stream()

The last way I will propose to create your List is using streams. Streams were added to Java in version 8, in 2014. They are a big topic, and well worth looking into as they make working with data structures much easier once you get the hang of them. In essence, you send a group of objects in one end, and perform various operations on this group in the middle (intermediate operations), then collect them all up again at the end (terminal operation) and package them back into a data structure of your pleasing.

List<String> streamList = 
    Arrays.stream(strings).collect(Collectors.toList());

This seems overkill compared to the above methods to create a list, but some intermediate operations with streams are filter(), where we could remove strings starting with "s" for example, skip(n) which skips the first n elements, or sorted() will sort the elements of the stream based on it's natural order. As I said, go and look into streams if you like, there's a lot a good things and useful benefits to using them.

That's it, we're done. I hope you found something useful, I know I enjoyed writing this and reading the documents to check my facts. If there's anything you'd like to add (to my first Dev.to post, no less!) please do comment below.

Thanks for reading!